Skip to content

spec clarifications #25601

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aevesdocker merged 1 commit into from
Jul 20, 2026
Merged

spec clarifications #25601

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions content/reference/compose-file/services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1766,11 +1766,13 @@ Unlike `post_start` and `pre_stop`, which run a command inside the running servi
- `privileged`: Lets the `pre_start` command run with privileged access.
- `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command.
- `environment`: Sets the environment variables to run the `pre_start` command. The command inherits the `environment` set for the service's main command, and this section lets you append or override values.
- `per_replica: false`: Whether the hook runs once for the service as a whole before any replica starts.
- `per_replica: false`: Whether the step runs once for the service as a whole before any replica starts.

A `pre_start` container joins the same networks as the service, so it can reach services declared in `depends_on`, and shares the service's declared volume mounts so files it produces in a shared volume are visible to the service. With `per_replica: false` and a scaled service, only mounts that are shared across replicas (named volumes, bind mounts) are usable. Per-instance mounts (`tmpfs`, anonymous volumes) cannot be addressed by a single run.
`pre_start` steps only run once the service's `depends_on` conditions have been satisfied, so a step can rely on those dependencies the same way the main service command does. A`pre_start` container joins the same networks as the service, so it can reach services declared in `depends_on`, and shares the service's declared volume mounts so files it produces in a shared volume are visible to the service.

@docker-agent docker-agent Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Missing space before inline code span

The text reads Apre_start — there is no space between "A" and the opening backtick. In rendered Markdown this will either break the code span or display as a typographical error. It should read `A `pre_start.

@docker-agent docker-agent Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Missing space before inline code span: 'Apre_start' should be 'A pre_start'

The new sentence reads ...the same way the main service command does. Apre_start container joins... — there is no space between A and the opening backtick. In rendered Markdown this will display as A followed by inline code, running them together visually. Add a space so it reads A pre_start container joins….


A `pre_start` step that has already succeeded for its current definition is not re-run on a subsequent `up`, nor when the service container restarts under its `restart` policy. A step runs again when its definition changes, when the previous run did not succeed, or when the service is recreated.
With `per_replica: false` and a scaled service, only mounts that are shared across replicas (named volumes, bind mounts) are usable. Per-instance mounts (`tmpfs`, anonymous volumes) cannot be addressed by a single run. This is not an error. The steps run without access to per-instance mounts. Data a `per_replica: false` step must share with the service belongs in a named volume or bind mount.

A `pre_start` step that has already succeeded for its current definition is not re-run on a subsequent `up`, nor when the service container restarts under its `restart` policy. A step runs again when its definition changes, when the previous run did not succeed, or when the service is recreated. For example, after a change to the service configuration or an explicit forced recreation.

@docker-agent docker-agent Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Sentence fragment

"For example, after a change to the service configuration or an explicit forced recreation." is a sentence fragment — it has no subject or main verb. Consider merging it with the preceding sentence:

A step runs again when its definition changes, when the previous run did not succeed, or when the service is recreated — for example, after a change to the service configuration or an explicit forced recreation.

@docker-agent docker-agent Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] 'For example…' is a sentence fragment

The appended text For example, after a change to the service configuration or an explicit forced recreation. has no main verb, making it a fragment. Consider integrating it into the preceding sentence, for example:

A step runs again when its definition changes, when the previous run did not succeed, or when the service is recreated — for example, after a change to the service configuration or an explicit forced recreation.


```yaml
services:
Expand Down Expand Up @@ -1799,7 +1801,7 @@ volumes:

`pre_stop` defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly.

Configuration is equivalent to [post_start](#post_start).
Configuration is equivalent to [`post_start`](#post_start).

### `privileged`

Expand Down