From 1d067410327752166315b54bb43ed5b21bc653db Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 9 Mar 2022 13:24:09 +0100 Subject: [PATCH] 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 --- docs/reference/compose.md | 34 ++++++++++---------- docs/reference/compose_build.md | 6 ++-- docs/reference/compose_convert.md | 4 +-- docs/reference/compose_exec.md | 4 +-- docs/reference/compose_ps.md | 2 +- docs/reference/compose_pull.md | 10 +++--- docs/reference/compose_restart.md | 6 ++-- docs/reference/compose_run.md | 16 +++++----- docs/reference/compose_top.md | 2 +- docs/reference/compose_up.md | 8 ++--- docs/reference/docker_compose_pull.yaml | 41 +++++++++++++++++++++++++ 11 files changed, 87 insertions(+), 46 deletions(-) diff --git a/docs/reference/compose.md b/docs/reference/compose.md index 3634d80c4..03bc6f400 100644 --- a/docs/reference/compose.md +++ b/docs/reference/compose.md @@ -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. diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md index df3d78f8a..d42f0a53b 100644 --- a/docs/reference/compose_build.md +++ b/docs/reference/compose_build.md @@ -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. diff --git a/docs/reference/compose_convert.md b/docs/reference/compose_convert.md index 344060f06..ca421d5f0 100644 --- a/docs/reference/compose_convert.md +++ b/docs/reference/compose_convert.md @@ -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` diff --git a/docs/reference/compose_exec.md b/docs/reference/compose_exec.md index 1a392f620..d6fa981ee 100644 --- a/docs/reference/compose_exec.md +++ b/docs/reference/compose_exec.md @@ -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. diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index ac7faaea2..30e6dcbf4 100644 --- a/docs/reference/compose_ps.md +++ b/docs/reference/compose_ps.md @@ -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) ``` diff --git a/docs/reference/compose_pull.md b/docs/reference/compose_pull.md index 0f6b6845e..7a76a44c5 100644 --- a/docs/reference/compose_pull.md +++ b/docs/reference/compose_pull.md @@ -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 -``̀ \ No newline at end of file +``̀` diff --git a/docs/reference/compose_restart.md b/docs/reference/compose_restart.md index 0e38b5652..65cebc080 100644 --- a/docs/reference/compose_restart.md +++ b/docs/reference/compose_restart.md @@ -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 diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md index c2d4eab15..e73def59e 100644 --- a/docs/reference/compose_run.md +++ b/docs/reference/compose_run.md @@ -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. diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md index 5ccb40bbf..e70f4341a 100644 --- a/docs/reference/compose_top.md +++ b/docs/reference/compose_top.md @@ -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 ``` diff --git a/docs/reference/compose_up.md b/docs/reference/compose_up.md index f16527356..7ff40855f 100644 --- a/docs/reference/compose_up.md +++ b/docs/reference/compose_up.md @@ -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. diff --git a/docs/reference/docker_compose_pull.yaml b/docs/reference/docker_compose_pull.yaml index 52d75785f..c4e13251f 100644 --- a/docs/reference/docker_compose_pull.yaml +++ b/docs/reference/docker_compose_pull.yaml @@ -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