From c7629bd8e69aca2d7f9c84d9b723d2c545590649 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Fri, 17 Jan 2025 12:23:17 +0000 Subject: [PATCH 1/7] ENGDOCS-2382 --- content/reference/compose-file/services.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 56dae4b3920..116d1a0cea4 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -257,7 +257,20 @@ cgroup_parent: m-executor-abcd command: bundle exec thin -p 3000 ``` -The value can also be a list, in a manner similar to [Dockerfile](https://docs.docker.com/reference/dockerfile/#cmd): +> [!NOTE] +> +> Unlike the `CMD` instruction of an image, the [shell-form syntax](https://docs.docker.com/reference/dockerfile/#shell-form) for `command` +> does not implicitly run in the context of the [`SHELL` instruction](https://docs.docker.com/reference/dockerfile/#shell). +> +> If you expect the command to rely on features of a shell environment such as environment variables, then ensure the command is run within a shell: +> +> ```yaml +> command: /bin/sh -c 'echo "hello $$HOSTNAME"' +> ``` +> +> When the `entrypoint` (or image `ENTRYPOINT`) is configured to run the shell instead, to ensure `command` is processed correctly you should use the exec-form described bellow. + +The value can also be a list, in a manner similar to the [exec-form syntax](/reference/dockerfile.md#exec-form) used by the [Dockerfile](/reference/dockerfile.md#cmd): ```yaml command: [ "bundle", "exec", "thin", "-p", "3000" ] @@ -766,6 +779,8 @@ extends: - `service`: Defines the name of the service being referenced as a base, for example `web` or `database`. - `file`: The location of a Compose configuration file defining that service. +#### Restrictions + When a service uses `extends`, it can also specify dependencies on other resources, an explicit `volumes` declaration for instance. However, it's important to note that `extends` does not automatically incorporate the target volume definition into the extending Compose file. Instead, you are responsible for ensuring that an equivalent resource exists for the service being extended to maintain consistency. Docker Compose verifies that a resource with the referenced ID is present within the Compose model. Dependencies on other resources in an `extends` target can be: From 12a727d81b35d0752d191facf87ddc84b93db2a1 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Fri, 17 Jan 2025 15:50:24 +0000 Subject: [PATCH 2/7] edit --- content/reference/compose-file/services.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 116d1a0cea4..e1fdc3ae853 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -259,16 +259,13 @@ command: bundle exec thin -p 3000 > [!NOTE] > -> Unlike the `CMD` instruction of an image, the [shell-form syntax](https://docs.docker.com/reference/dockerfile/#shell-form) for `command` -> does not implicitly run in the context of the [`SHELL` instruction](https://docs.docker.com/reference/dockerfile/#shell). -> -> If you expect the command to rely on features of a shell environment such as environment variables, then ensure the command is run within a shell: +> Unlike the `CMD` instruction in a Dockerfile, the `command` field doesn't automatically run within the context of the [`SHELL`](/reference/dockerfile/#shell-form) instruction defined in the image. If your `command` relies shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example: > > ```yaml > command: /bin/sh -c 'echo "hello $$HOSTNAME"' > ``` > -> When the `entrypoint` (or image `ENTRYPOINT`) is configured to run the shell instead, to ensure `command` is processed correctly you should use the exec-form described bellow. +>If the `entrypoint`, (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. The value can also be a list, in a manner similar to the [exec-form syntax](/reference/dockerfile.md#exec-form) used by the [Dockerfile](/reference/dockerfile.md#cmd): From f6d2d5573a781a3c5d5f0d1f15e543af18d92bbd Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Fri, 17 Jan 2025 15:54:41 +0000 Subject: [PATCH 3/7] edit --- content/reference/compose-file/services.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index e1fdc3ae853..65cbf5fc777 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -257,6 +257,10 @@ cgroup_parent: m-executor-abcd command: bundle exec thin -p 3000 ``` +If the value is `null`, the default command from the image is used. + +If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, or in other words overridden to be empty. + > [!NOTE] > > Unlike the `CMD` instruction in a Dockerfile, the `command` field doesn't automatically run within the context of the [`SHELL`](/reference/dockerfile/#shell-form) instruction defined in the image. If your `command` relies shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example: @@ -265,17 +269,11 @@ command: bundle exec thin -p 3000 > command: /bin/sh -c 'echo "hello $$HOSTNAME"' > ``` > ->If the `entrypoint`, (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. - -The value can also be a list, in a manner similar to the [exec-form syntax](/reference/dockerfile.md#exec-form) used by the [Dockerfile](/reference/dockerfile.md#cmd): - -```yaml -command: [ "bundle", "exec", "thin", "-p", "3000" ] -``` - -If the value is `null`, the default command from the image is used. - -If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, or in other words overridden to be empty. +> If the `entrypoint`, (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. For example: +> +> ```yaml +> command: [ "bundle", "exec", "thin", "-p", "3000" ] +> ``` ### `configs` From b10d1fb920d6da849c63da0b79dc9ed19919ea39 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Fri, 17 Jan 2025 15:56:06 +0000 Subject: [PATCH 4/7] edit --- content/reference/compose-file/services.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 65cbf5fc777..1a418f296ac 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -263,13 +263,13 @@ If the value is `[]` (empty list) or `''` (empty string), the default command de > [!NOTE] > -> Unlike the `CMD` instruction in a Dockerfile, the `command` field doesn't automatically run within the context of the [`SHELL`](/reference/dockerfile/#shell-form) instruction defined in the image. If your `command` relies shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example: +> Unlike the `CMD` instruction in a Dockerfile, the `command` field doesn't automatically run within the context of the [`SHELL`](/reference/dockerfile.md#shell-form) instruction defined in the image. If your `command` relies on shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example: > > ```yaml > command: /bin/sh -c 'echo "hello $$HOSTNAME"' > ``` > -> If the `entrypoint`, (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. For example: +> If the `entrypoint` (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. For example: > > ```yaml > command: [ "bundle", "exec", "thin", "-p", "3000" ] From 5e1a6d2d4882451bab9af0338cebeaf299a6b458 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 20 Jan 2025 08:48:31 +0000 Subject: [PATCH 5/7] edit --- content/reference/compose-file/services.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 1a418f296ac..4404dc3dbd9 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -268,12 +268,9 @@ If the value is `[]` (empty list) or `''` (empty string), the default command de > ```yaml > command: /bin/sh -c 'echo "hello $$HOSTNAME"' > ``` -> -> If the `entrypoint` (or the image's `ENTRYPOINT`) is configured to invoke a shell, use the exec form syntax for `command` to ensure proper processing. For example: -> -> ```yaml -> command: [ "bundle", "exec", "thin", "-p", "3000" ] -> ``` + +The value can also be a list, similar to the [exec-form syntax](/reference/dockerfile.md#exec-form) +used by the [Dockerfile](/manuals/engine/reference.md#cmd). ### `configs` From e03fb7f4fb8a5907f1fd1eda78f3e8e392cef372 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 20 Jan 2025 08:55:21 +0000 Subject: [PATCH 6/7] fix link --- content/reference/compose-file/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 4404dc3dbd9..038c864c7cf 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -270,7 +270,7 @@ If the value is `[]` (empty list) or `''` (empty string), the default command de > ``` The value can also be a list, similar to the [exec-form syntax](/reference/dockerfile.md#exec-form) -used by the [Dockerfile](/manuals/engine/reference.md#cmd). +used by the [Dockerfile](/reference/dockerfile.md#exec-form). ### `configs` From 156485b5a1961d98d4618750ffd9d9f7e02b17e2 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Mon, 20 Jan 2025 13:45:33 +0000 Subject: [PATCH 7/7] info on extends --- content/reference/compose-file/services.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 038c864c7cf..ef47796444f 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -773,11 +773,9 @@ extends: #### Restrictions -When a service uses `extends`, it can also specify dependencies on other resources, an explicit `volumes` declaration for instance. However, it's important to note that `extends` does not automatically incorporate the target volume definition into the extending Compose file. Instead, you are responsible for ensuring that an equivalent resource exists for the service being extended to maintain consistency. Docker Compose verifies that a resource with the referenced ID is present within the Compose model. +When a service is referenced using `extends`, it can declare dependencies on other resources. These dependencies may be explicitly defined through attributes like `volumes`, `networks`, `configs`, `secrets`, `links`, `volumes_from`, or `depends_on`. Alternatively, dependencies can reference another service using the `service:{name}` syntax in namespace declarations such as `ipc`, `pid`, or `network_mode`. -Dependencies on other resources in an `extends` target can be: -- An explicit reference by `volumes`, `networks`, `configs`, `secrets`, `links`, `volumes_from` or `depends_on` -- A reference to another service using the `service:{name}` syntax in namespace declaration (`ipc`, `pid`, `network_mode`) +Compose does not automatically import these referenced resources into the extended model. It is your responsibility to ensure all required resources are explicitly declared in the model that relies on extends. Circular references with `extends` are not supported, Compose returns an error when one is detected.