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

docs: fix trailing whitespace from markdown and regenerate 

Trailing whitespace in Markdown can force line-breaks, which doesn't seem to
be the intent on these;

    find . -type f -print0 | xargs -0 perl -pi -e 's/ +$//'

The trailing whitespace also can cause the YAML to go wonky (although the
cli-docs-tool now takes that into account), and caused the "examples" section
to be missed in the `docker compose pull` page (something we should fix in
the tool).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-03-09 13:24:09 +01:00 committed by Nicolas De loof
parent 35b790dcdf
commit 1d06741032
11 changed files with 87 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/reference/compose.md
View File

@ -9,8 +9,8 @@ multiple services in Docker containers.
Use the `-f` flag to specify the location of a Compose configuration file.
#### Specifying multiple Compose files
You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
to their predecessors.
For example, consider this command line:
@ -30,7 +30,7 @@ services:
volumes:
- "/data"
```
If the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file.
If the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file.
New values, add to the `webapp` service configuration.
```yaml
@ -41,22 +41,22 @@ services:
- DEBUG=1
```
When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
with `-f`. You can use the `--project-directory` option to override this base path.
Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
configuration are relative to the current working directory.
The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.
#### Specifying a path to a single Compose file
You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.
For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and
have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to
get the postgres image for the db service from anywhere by using the `-f` flag as follows:
For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and
have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to
get the postgres image for the db service from anywhere by using the `-f` flag as follows:
```console
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
@ -64,17 +64,17 @@ $ docker compose -f ~/sandbox/rails/compose.yaml pull db
### Use `-p` to specify a project name
Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
specify the flag, Compose uses the current directory name.
Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
specify the flag, Compose uses the current directory name.
Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
Most compose subcommand can be ran without a compose file, just passing
Most compose subcommand can be ran without a compose file, just passing
project name to retrieve the relevant resources.
```console
$ docker compose -p my_project ps -a
NAME SERVICE STATUS PORTS
my_project_demo_1 demo running
my_project_demo_1 demo running
$ docker compose -p my_project logs
demo_1 | PING localhost (127.0.0.1): 56 data bytes
@ -84,8 +84,8 @@ demo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
### Use profiles to enable optional services
Use `--profile` to specify one or more active profiles
Calling `docker compose --profile frontend up` will start the services with the profile `frontend` and services
without any specified profiles.
Calling `docker compose --profile frontend up` will start the services with the profile `frontend` and services
without any specified profiles.
You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.
Profiles can also be set by `COMPOSE_PROFILES` environment variable.
@ -100,5 +100,5 @@ and so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag
If flags are explicitly set on command line, associated environment variable is ignored
Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
containers for the project.

6
docs/reference/compose_build.md
View File

@ -1,12 +1,12 @@
## Description
Services are built once and then tagged, by default as `project_service`.
Services are built once and then tagged, by default as `project_service`.
If the Compose file specifies an
[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name,
[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name,
the image is tagged with that name, substituting any variables beforehand. See
[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).
If you change a service's `Dockerfile` or the contents of its build directory,
If you change a service's `Dockerfile` or the contents of its build directory,
run `docker compose build` to rebuild it.

4
docs/reference/compose_convert.md
View File

@ -3,7 +3,7 @@
## Description
`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,
it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into
fully defined Compose model.
it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into
fully defined Compose model.
To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`

4
docs/reference/compose_exec.md
View File

@ -1,7 +1,7 @@
## Description
This is the equivalent of `docker exec` targeting a Compose service.
This is the equivalent of `docker exec` targeting a Compose service.
With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so
With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so
you can use a command such as `docker compose exec web sh` to get an interactive prompt.

2
docs/reference/compose_ps.md
View File

@ -7,5 +7,5 @@ Lists containers for a Compose project, with current status and exposed ports.
$ docker compose ps
NAME SERVICE STATUS PORTS
example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp
example_bar_1 bar exited (1)
example_bar_1 bar exited (1)
```

10
docs/reference/compose_pull.md
View File

@ -1,11 +1,11 @@
## Description
Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on
Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on
those images.
## Examples
## Examples
suppose you have this `compose.yaml`:
@ -24,8 +24,8 @@ services:
- db
```
If you run `docker compose pull ServiceName` in the same directory as the `compose.yaml` file that defines the service,
Docker pulls the associated image. For example, to call the postgres image configured as the db service in our example,
If you run `docker compose pull ServiceName` in the same directory as the `compose.yaml` file that defines the service,
Docker pulls the associated image. For example, to call the postgres image configured as the db service in our example,
you would run `docker compose pull db`.
```console
@ -46,4 +46,4 @@ $ docker compose pull db
⠹ f63c47038e66 Waiting 9.3s
⠹ 77a0c198cde5 Waiting 9.3s
⠹ c8752d5b785c Waiting 9.3s
``̀
``̀`

6
docs/reference/compose_restart.md
View File

@ -1,8 +1,8 @@
Restarts all stopped and running services.
If you make changes to your `compose.yml` configuration, these changes are not reflected
after running this command. For example, changes to environment variables (which are added
after a container is built, but before the container's command is executed) are not updated
If you make changes to your `compose.yml` configuration, these changes are not reflected
after running this command. For example, changes to environment variables (which are added
after a container is built, but before the container's command is executed) are not updated
after restarting.
If you are looking to configure a service's restart policy, please refer to

16
docs/reference/compose_run.md
View File

@ -1,7 +1,7 @@
## Description
Runs a one-time command against a service.
Runs a one-time command against a service.
the following command starts the `web` service and runs `bash` as its command:
@ -12,12 +12,12 @@ $ docker compose run web bash
Commands you use with run start in new containers with configuration defined by that of the service,
including volumes, links, and other details. However, there are two important differences:
First, the command passed by `run` overrides the command defined in the service configuration. For example, if the
`web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with
First, the command passed by `run` overrides the command defined in the service configuration. For example, if the
`web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with
`python app.py`.
The second difference is that the `docker compose run` command does not create any of the ports specified in the
service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports
The second difference is that the `docker compose run` command does not create any of the ports specified in the
service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports
to be created and mapped to the host, specify the `--service-ports`
```console
@ -30,8 +30,8 @@ Alternatively, manual port mapping can be specified with the `--publish` or `-p`
$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
```
If you start a service configured with links, the run command first checks to see if the linked service is running
and starts the service if it is stopped. Once all the linked services are running, the run executes the command you
If you start a service configured with links, the run command first checks to see if the linked service is running
and starts the service if it is stopped. Once all the linked services are running, the run executes the command you
passed it. For example, you could run:
```console
@ -52,5 +52,5 @@ If you want to remove the container after running while overriding the container
$ docker compose run --rm web python manage.py db upgrade
```
This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
specified in the service configuration.

2
docs/reference/compose_top.md
View File

@ -9,5 +9,5 @@ Displays the running processes.
$ docker compose top
example_foo_1
UID PID PPID C STIME TTY TIME CMD
root 142353 142331 2 15:33 ? 00:00:00 ping localhost -c 5
root 142353 142331 2 15:33 ? 00:00:00 ping localhost -c 5
```

8
docs/reference/compose_up.md
View File

@ -5,12 +5,12 @@ Builds, (re)creates, starts, and attaches to containers for a service.
Unless they are already running, this command also starts any linked services.
The `docker compose up` command aggregates the output of each container (like `docker compose logs --follow` does).
When the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the
The `docker compose up` command aggregates the output of each container (like `docker compose logs --follow` does).
When the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the
background and leaves them running.
If there are existing containers for a service, and the service’s configuration or image was changed after the
container’s creation, `docker compose up` picks up the changes by stopping and recreating the containers
If there are existing containers for a service, and the service’s configuration or image was changed after the
container’s creation, `docker compose up` picks up the changes by stopping and recreating the containers
(preserving mounted volumes). To prevent Compose from picking up changes, use the `--no-recreate` flag.
If you want to force Compose to stop and recreate all containers, use the `--force-recreate` flag.

41
docs/reference/docker_compose_pull.yaml
View File

@ -53,6 +53,47 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
suppose you have this `compose.yaml`:
```yaml
services:
db:
image: postgres
web:
build: .
command: bundle exec rails s -p 3000 -b '0.0.0.0'
volumes:
- .:/myapp
ports:
- "3000:3000"
depends_on:
- db
```
If you run `docker compose pull ServiceName` in the same directory as the `compose.yaml` file that defines the service,
Docker pulls the associated image. For example, to call the postgres image configured as the db service in our example,
you would run `docker compose pull db`.
```console
$ docker compose pull db
[+] Running 1/15
⠸ db Pulling 12.4s
⠿ 45b42c59be33 Already exists 0.0s
⠹ 40adec129f1a Downloading 3.374MB/4.178MB 9.3s
⠹ b4c431d00c78 Download complete 9.3s
⠹ 2696974e2815 Download complete 9.3s
⠹ 564b77596399 Downloading 5.622MB/7.965MB 9.3s
⠹ 5044045cf6f2 Downloading 216.7kB/391.1kB 9.3s
⠹ d736e67e6ac3 Waiting 9.3s
⠹ 390c1c9a5ae4 Waiting 9.3s
⠹ c0e62f172284 Waiting 9.3s
⠹ ebcdc659c5bf Waiting 9.3s
⠹ 29be22cb3acc Waiting 9.3s
⠹ f63c47038e66 Waiting 9.3s
⠹ 77a0c198cde5 Waiting 9.3s
⠹ c8752d5b785c Waiting 9.3s
``̀`
deprecated: false
experimental: false
experimentalcli: false