docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve "Extend your Compose file" (#19129) 

* extends.md: Add trailing newline

* extends.md: Remove trailing whitespace

* extends.md: Correct reference to previously-named file

* extends.md: Correct YAML syntax

* extends.md: Use conventional YAML indentation

* extends.md: Wrap to 80 characters

* Update content/compose/multiple-compose-files/extends.md

---------

Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
Allan Lewis 2024-01-18 16:29:51 +00:00 committed by GitHub
parent 1da0617fa5
commit 9d2f6bbaac
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 41 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
content/compose/multiple-compose-files/extends.md
View File

@ -7,28 +7,29 @@ aliases:
- /compose/extends/ - /compose/extends/
--- ---
Docker Compose's [`extends` attribute](../compose-file/05-services.md#extends) lets you share common configurations Docker Compose's [`extends` attribute](../compose-file/05-services.md#extends)
among different files, or even different projects entirely. lets you share common configurations among different files, or even different
projects entirely.
Extending services Extending services is useful if you have several services that reuse a common
is useful if you have several services that reuse a common set of configuration set of configuration options. With `extends` you can define a common set of
options. With `extends` you can define a common set of service options in one service options in one place and refer to it from anywhere. You can refer to
place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs. another Compose file and select a service you want to also use in your own
application, with the ability to override some attributes for your own needs.
> **Important** > **Important**
> >
> When you use multiple Compose files, you must make sure all paths in the > When you use multiple Compose files, you must make sure all paths in the files
files are relative to the base Compose file. This is required because extend files need not be valid are relative to the base Compose file. This is required because extend files
Compose files. Extend files can contain small fragments of configuration. need not be valid Compose files. Extend files can contain small fragments of
Tracking which fragment of a service is relative to which path is difficult and configuration. Tracking which fragment of a service is relative to which path is
confusing, so to keep paths easier to understand, all paths must be defined difficult and confusing, so to keep paths easier to understand, all paths must
relative to the base file. be defined relative to the base file. { .important }
{ .important }
## How it works ## How it works
When defining any service in your `compose.yaml` file, you can declare that you are When defining any service in your `compose.yaml` file, you can declare that you
extending another service: are extending another service:
```yaml ```yaml
services: services:
@ -96,8 +97,8 @@ services:
### Example one ### Example one
Extending an individual service is useful when you have multiple services that Extending an individual service is useful when you have multiple services that
have a common configuration. The example below is a Compose app with have a common configuration. The example below is a Compose app with two
two services, a web application and a queue worker. Both services use the same services, a web application and a queue worker. Both services use the same
codebase and share many configuration options. codebase and share many configuration options.
The `common.yaml` file defines the common configuration: The `common.yaml` file defines the common configuration:
@ -112,8 +113,8 @@ services:
cpu_shares: 5 cpu_shares: 5
``` ```
The `docker-compose.yaml` defines the concrete services which use the The `docker-compose.yaml` defines the concrete services which use the common
common configuration: configuration:
```yaml ```yaml
services: services:
@ -139,9 +140,9 @@ services:
### Example two ### Example two
Another common use case for `extends` is running one off or administrative tasks against one Another common use case for `extends` is running one off or administrative tasks
or more services in a Compose app. This example demonstrates running a against one or more services in a Compose app. This example demonstrates running
database backup. a database backup.
The `docker-compose.yml` defines the base configuration. The `docker-compose.yml` defines the base configuration.
@ -150,21 +151,21 @@ services:
web: web:
image: example/my_web_app:latest image: example/my_web_app:latest
depends_on: depends_on:
db - db
db: db:
image: postgres:latest image: postgres:latest
``` ```
`docker-compose.admin.yml` adds a new service to run the database `docker-compose.admin.yml` adds a new service to run the database export or
export or backup. backup.
```yaml ```yaml
services: services:
dbadmin: dbadmin:
build: database_admin/ build: database_admin/
depends_on: depends_on:
- db - db
``` ```
To start a normal environment, run `docker compose up -d`. To run a database To start a normal environment, run `docker compose up -d`. To run a database
@ -175,20 +176,22 @@ $ docker compose -f docker-compose.yml -f docker-compose.admin.yml \
run dbadmin db-backup run dbadmin db-backup
``` ```
Compose extends files in Compose extends files in the order they're specified on the command line.
the order they're specified on the command line.
## Exceptions and limitations ## Exceptions and limitations
`volumes_from` and `depends_on` are never shared between `volumes_from` and `depends_on` are never shared between services using
services using `extends`. These exceptions exist to avoid implicit `extends`. These exceptions exist to avoid implicit dependencies; you always
dependencies; you always define `volumes_from` locally. This ensures define `volumes_from` locally. This ensures dependencies between services are
dependencies between services are clearly visible when reading the current file. clearly visible when reading the current file. Defining these locally also
Defining these locally also ensures that changes to the referenced file don't ensures that changes to the referenced file don't break anything.
break anything.
`extends` is useful if you only need a single service to be shared and you are familiar with the file you're extending to, so you can to tweak the configuration. But this isn’t an acceptable solution when you want to re-use someone else's unfamiliar configurations and you don’t know about its own dependencies. `extends` is useful if you only need a single service to be shared and you are
familiar with the file you're extending to, so you can to tweak the
configuration. But this isn’t an acceptable solution when you want to re-use
someone else's unfamiliar configurations and you don’t know about its own
dependencies.
## Reference information ## Reference information
- [`extends`](../compose-file/05-services.md#extends) - [`extends`](../compose-file/05-services.md#extends)