diff --git a/docs/reference/compose.md b/docs/reference/compose.md index b8f10ce8a..26a216e02 100644 --- a/docs/reference/compose.md +++ b/docs/reference/compose.md @@ -1,7 +1,150 @@ # docker compose -Define and run multi-container applications with Docker +You can use the compose subcommand, `docker compose [-f ...] [options] [COMMAND] [ARGS...]`, to build and manage +multiple services in Docker containers. + +### Use `-f` to specify the name and path of one or more Compose files +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 +to their predecessors. + +For example, consider this command line: + +```console +$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db +``` + +The `docker-compose.yml` file might specify a `webapp` service. + +```yaml +services: + webapp: + image: examples/web + ports: + - "8000:8000" + volumes: + - "/data" +``` +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 +services: + webapp: + build: . + environment: + - DEBUG=1 +``` + +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 +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 +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 +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: + +```console +$ docker compose -f ~/sandbox/rails/compose.yaml pull db +``` + +### Use `-p` to specify a project name + +Each configuration has a project name. Compose sets the project name using +the following mechanisms, in order of precedence: +- The `-p` command line flag +- The `COMPOSE_PROJECT_NAME` environment variable +- The top level `name:` variable from the config file (or the last `name:` +from a series of config files specified using `-f`) +- The `basename` of the project directory containing the config file (or +containing the first config file specified using `-f`) +- The `basename` of the current directory if no config file is specified +Project names must contain only lowercase letters, decimal digits, dashes, +and underscores, and must begin with a lowercase letter or decimal digit. If +the `basename` of the project directory or current directory violates this +constraint, you must use one of the other mechanisms. + +```console +$ docker compose -p my_project ps -a +NAME SERVICE STATUS PORTS +my_project_demo_1 demo running + +$ docker compose -p my_project logs +demo_1 | PING localhost (127.0.0.1): 56 data bytes +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` starts 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` is enabled. + +Profiles can also be set by `COMPOSE_PROFILES` environment variable. + +### Configuring parallelism + +Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls. +Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file +one at a time. This can also be used to control build concurrency. + +Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable. + +### Set up environment variables + +You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags. + +Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag, +`COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag, +`COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag +and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag. + +If flags are explicitly set on the command line, the associated environment variable is ignored. + +Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops docker compose from detecting orphaned +containers for the project. + +Setting the `COMPOSE_MENU` environment variable to `false` disables the helper menu when running `docker compose up` +in attached mode. Alternatively, you can also run `docker compose up --menu=false` to disable the helper menu. + +### Use Dry Run mode to test your command + +Use `--dry-run` flag to test a command without changing your application stack state. +Dry Run mode shows you all the steps Compose applies when executing a command, for example: +```console +$ docker compose --dry-run up --build -d +[+] Pulling 1/1 + ✔ DRY-RUN MODE - db Pulled 0.9s +[+] Running 10/8 + ✔ DRY-RUN MODE - build service backend 0.0s + ✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s + ✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s + ✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Started 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Started Started +``` +From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service. +Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting. + +Dry Run mode works with almost all commands. You cannot use Dry Run mode with a command that doesn't change the state of a Compose stack such as `ps`, `ls`, `logs` for example. ### Subcommands @@ -43,10 +186,10 @@ Define and run multi-container applications with Docker | Name | Type | Default | Description | |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------| -| `--all-resources` | | | Include all resources, even those not used by services | +| `--all-resources` | `bool` | | Include all resources, even those not used by services | | `--ansi` | `string` | `auto` | Control when to print ANSI control characters ("never"\|"always"\|"auto") | -| `--compatibility` | | | Run compose in backward compatibility mode | -| `--dry-run` | | | Execute command in dry run mode | +| `--compatibility` | `bool` | | Run compose in backward compatibility mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--env-file` | `stringArray` | | Specify an alternate environment file | | `-f`, `--file` | `stringArray` | | Compose configuration files | | `--parallel` | `int` | `-1` | Control max parallelism, -1 for unlimited | diff --git a/docs/reference/compose_alpha_publish.md b/docs/reference/compose_alpha_publish.md index 02516d968..7fe79480b 100644 --- a/docs/reference/compose_alpha_publish.md +++ b/docs/reference/compose_alpha_publish.md @@ -7,9 +7,9 @@ Publish compose application | Name | Type | Default | Description | |:--------------------------|:---------|:--------|:-------------------------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--oci-version` | `string` | | OCI Image/Artifact specification version (automatically determined by default) | -| `--resolve-image-digests` | | | Pin image tags to digests | +| `--resolve-image-digests` | `bool` | | Pin image tags to digests | diff --git a/docs/reference/compose_alpha_viz.md b/docs/reference/compose_alpha_viz.md index 04bffc0b8..1a05aaac1 100644 --- a/docs/reference/compose_alpha_viz.md +++ b/docs/reference/compose_alpha_viz.md @@ -5,14 +5,14 @@ EXPERIMENTAL - Generate a graphviz graph from your compose file ### Options -| Name | Type | Default | Description | -|:---------------------|:------|:--------|:---------------------------------------------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--image` | | | Include service's image name in output graph | -| `--indentation-size` | `int` | `1` | Number of tabs or spaces to use for indentation | -| `--networks` | | | Include service's attached networks in output graph | -| `--ports` | | | Include service's exposed ports in output graph | -| `--spaces` | | | If given, space character ' ' will be used to indent,
otherwise tab character '\t' will be used | +| Name | Type | Default | Description | +|:---------------------|:-------|:--------|:---------------------------------------------------------------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--image` | `bool` | | Include service's image name in output graph | +| `--indentation-size` | `int` | `1` | Number of tabs or spaces to use for indentation | +| `--networks` | `bool` | | Include service's attached networks in output graph | +| `--ports` | `bool` | | Include service's exposed ports in output graph | +| `--spaces` | `bool` | | If given, space character ' ' will be used to indent,
otherwise tab character '\t' will be used | diff --git a/docs/reference/compose_attach.md b/docs/reference/compose_attach.md index 6d5cff9d9..0b9ede1e0 100644 --- a/docs/reference/compose_attach.md +++ b/docs/reference/compose_attach.md @@ -8,9 +8,9 @@ Attach local standard input, output, and error streams to a service's running co | Name | Type | Default | Description | |:----------------|:---------|:--------|:----------------------------------------------------------| | `--detach-keys` | `string` | | Override the key sequence for detaching from a container. | -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--index` | `int` | `0` | index of the container if service has multiple replicas. | -| `--no-stdin` | | | Do not attach STDIN | +| `--no-stdin` | `bool` | | Do not attach STDIN | | `--sig-proxy` | `bool` | `true` | Proxy all received signals to the process | diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md index 271dfcde7..eb05121a7 100644 --- a/docs/reference/compose_build.md +++ b/docs/reference/compose_build.md @@ -1,7 +1,15 @@ # docker compose build -Build or rebuild services +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, +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, +run `docker compose build` to rebuild it. ### Options @@ -9,14 +17,14 @@ Build or rebuild services |:----------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------| | `--build-arg` | `stringArray` | | Set build-time variables for services | | `--builder` | `string` | | Set builder to use | -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `-m`, `--memory` | `bytes` | `0` | Set memory limit for the build container. Not supported by BuildKit. | -| `--no-cache` | | | Do not use cache when building the image | -| `--pull` | | | Always attempt to pull a newer version of the image | -| `--push` | | | Push service images | -| `-q`, `--quiet` | | | Don't print anything to STDOUT | +| `--no-cache` | `bool` | | Do not use cache when building the image | +| `--pull` | `bool` | | Always attempt to pull a newer version of the image | +| `--push` | `bool` | | Push service images | +| `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT | | `--ssh` | `string` | | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) | -| `--with-dependencies` | | | Also build dependencies (transitively) | +| `--with-dependencies` | `bool` | | Also build dependencies (transitively) | diff --git a/docs/reference/compose_config.md b/docs/reference/compose_config.md index 8b9671236..0eac3de63 100644 --- a/docs/reference/compose_config.md +++ b/docs/reference/compose_config.md @@ -1,7 +1,9 @@ # docker compose convert -Parse, resolve and render compose file in canonical format +`docker compose config` renders the actual data model to be applied on the Docker Engine. +It merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into +the canonical format. ### Aliases @@ -11,22 +13,22 @@ Parse, resolve and render compose file in canonical format | Name | Type | Default | Description | |:--------------------------|:---------|:--------|:----------------------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--environment` | | | Print environment used for interpolation. | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--environment` | `bool` | | Print environment used for interpolation. | | `--format` | `string` | `yaml` | Format the output. Values: [yaml \| json] | | `--hash` | `string` | | Print the service config hash, one per line. | -| `--images` | | | Print the image names, one per line. | -| `--no-consistency` | | | Don't check model consistency - warning: may produce invalid Compose output | -| `--no-interpolate` | | | Don't interpolate environment variables | -| `--no-normalize` | | | Don't normalize compose model | -| `--no-path-resolution` | | | Don't resolve file paths | +| `--images` | `bool` | | Print the image names, one per line. | +| `--no-consistency` | `bool` | | Don't check model consistency - warning: may produce invalid Compose output | +| `--no-interpolate` | `bool` | | Don't interpolate environment variables | +| `--no-normalize` | `bool` | | Don't normalize compose model | +| `--no-path-resolution` | `bool` | | Don't resolve file paths | | `-o`, `--output` | `string` | | Save to file (default to stdout) | -| `--profiles` | | | Print the profile names, one per line. | -| `-q`, `--quiet` | | | Only validate the configuration, don't print anything | -| `--resolve-image-digests` | | | Pin image tags to digests | -| `--services` | | | Print the service names, one per line. | -| `--variables` | | | Print model variables and default values. | -| `--volumes` | | | Print the volume names, one per line. | +| `--profiles` | `bool` | | Print the profile names, one per line. | +| `-q`, `--quiet` | `bool` | | Only validate the configuration, don't print anything | +| `--resolve-image-digests` | `bool` | | Pin image tags to digests | +| `--services` | `bool` | | Print the service names, one per line. | +| `--variables` | `bool` | | Print model variables and default values. | +| `--volumes` | `bool` | | Print the volume names, one per line. | diff --git a/docs/reference/compose_cp.md b/docs/reference/compose_cp.md index a60388e30..9ed14140e 100644 --- a/docs/reference/compose_cp.md +++ b/docs/reference/compose_cp.md @@ -5,12 +5,12 @@ Copy files/folders between a service container and the local filesystem ### Options -| Name | Type | Default | Description | -|:----------------------|:------|:--------|:--------------------------------------------------------| -| `-a`, `--archive` | | | Archive mode (copy all uid/gid information) | -| `--dry-run` | | | Execute command in dry run mode | -| `-L`, `--follow-link` | | | Always follow symbol link in SRC_PATH | -| `--index` | `int` | `0` | Index of the container if service has multiple replicas | +| Name | Type | Default | Description | +|:----------------------|:-------|:--------|:--------------------------------------------------------| +| `-a`, `--archive` | `bool` | | Archive mode (copy all uid/gid information) | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `-L`, `--follow-link` | `bool` | | Always follow symbol link in SRC_PATH | +| `--index` | `int` | `0` | Index of the container if service has multiple replicas | diff --git a/docs/reference/compose_create.md b/docs/reference/compose_create.md index 06293625a..7ae60c549 100644 --- a/docs/reference/compose_create.md +++ b/docs/reference/compose_create.md @@ -7,14 +7,14 @@ Creates containers for a service | Name | Type | Default | Description | |:-------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------| -| `--build` | | | Build images before starting containers | -| `--dry-run` | | | Execute command in dry run mode | -| `--force-recreate` | | | Recreate containers even if their configuration and image haven't changed | -| `--no-build` | | | Don't build an image, even if it's policy | -| `--no-recreate` | | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | +| `--build` | `bool` | | Build images before starting containers | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--force-recreate` | `bool` | | Recreate containers even if their configuration and image haven't changed | +| `--no-build` | `bool` | | Don't build an image, even if it's policy | +| `--no-recreate` | `bool` | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | | `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never"\|"build") | -| `--quiet-pull` | | | Pull without printing progress information | -| `--remove-orphans` | | | Remove containers for services not defined in the Compose file | +| `--quiet-pull` | `bool` | | Pull without printing progress information | +| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file | | `--scale` | `stringArray` | | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. | diff --git a/docs/reference/compose_down.md b/docs/reference/compose_down.md index 2d7cf5727..2ac0bf2da 100644 --- a/docs/reference/compose_down.md +++ b/docs/reference/compose_down.md @@ -1,17 +1,29 @@ # docker compose down -Stop and remove containers, networks +Stops containers and removes containers, networks, volumes, and images created by `up`. + +By default, the only things removed are: + +- Containers for services defined in the Compose file. +- Networks defined in the networks section of the Compose file. +- The default network, if one is used. + +Networks and volumes defined as external are never removed. + +Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically +mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or +named volumes. ### Options | Name | Type | Default | Description | |:-------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--remove-orphans` | | | Remove containers for services not defined in the Compose file | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file | | `--rmi` | `string` | | Remove images used by services. "local" remove only images that don't have a custom tag ("local"\|"all") | | `-t`, `--timeout` | `int` | `0` | Specify a shutdown timeout in seconds | -| `-v`, `--volumes` | | | Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers | +| `-v`, `--volumes` | `bool` | | Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers | diff --git a/docs/reference/compose_events.md b/docs/reference/compose_events.md index 0a97a46bc..b71f4c993 100644 --- a/docs/reference/compose_events.md +++ b/docs/reference/compose_events.md @@ -1,14 +1,32 @@ # docker compose events -Receive real time events from containers +Stream container events for every container in the project. + +With the `--json` flag, a json object is printed one per line with the format: + +```json +{ + "time": "2015-11-20T18:01:03.615550", + "type": "container", + "action": "create", + "id": "213cf7...5fc39a", + "service": "web", + "attributes": { + "name": "application_web_1", + "image": "alpine:edge" + } +} +``` + +The events that can be received using this can be seen [here](/reference/cli/docker/system/events/#object-types). ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--json` | | | Output events as a stream of json objects | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--json` | `bool` | | Output events as a stream of json objects | diff --git a/docs/reference/compose_exec.md b/docs/reference/compose_exec.md index d647ea0e4..8b54def47 100644 --- a/docs/reference/compose_exec.md +++ b/docs/reference/compose_exec.md @@ -1,18 +1,21 @@ # docker compose exec -Execute a command in a running container +This is the equivalent of `docker exec` targeting a Compose service. + +With this subcommand, you can run arbitrary commands in your services. Commands allocate a TTY by default, so +you can use a command such as `docker compose exec web sh` to get an interactive prompt. ### Options | Name | Type | Default | Description | |:------------------|:--------------|:--------|:---------------------------------------------------------------------------------| -| `-d`, `--detach` | | | Detached mode: Run command in the background | -| `--dry-run` | | | Execute command in dry run mode | +| `-d`, `--detach` | `bool` | | Detached mode: Run command in the background | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `-e`, `--env` | `stringArray` | | Set environment variables | | `--index` | `int` | `0` | Index of the container if service has multiple replicas | | `-T`, `--no-TTY` | `bool` | `true` | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. | -| `--privileged` | | | Give extended privileges to the process | +| `--privileged` | `bool` | | Give extended privileges to the process | | `-u`, `--user` | `string` | | Run the command as this user | | `-w`, `--workdir` | `string` | | Path to workdir directory for this command | diff --git a/docs/reference/compose_images.md b/docs/reference/compose_images.md index a29af42f3..1e4e0259b 100644 --- a/docs/reference/compose_images.md +++ b/docs/reference/compose_images.md @@ -7,9 +7,9 @@ List images used by the created containers | Name | Type | Default | Description | |:----------------|:---------|:--------|:-------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--format` | `string` | `table` | Format the output. Values: [table \| json] | -| `-q`, `--quiet` | | | Only display IDs | +| `-q`, `--quiet` | `bool` | | Only display IDs | diff --git a/docs/reference/compose_kill.md b/docs/reference/compose_kill.md index a10ce55be..e3f9e4fb3 100644 --- a/docs/reference/compose_kill.md +++ b/docs/reference/compose_kill.md @@ -1,14 +1,18 @@ # docker compose kill -Force stop service containers +Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example: + +```console +$ docker-compose kill -s SIGINT +``` ### Options | Name | Type | Default | Description | |:-------------------|:---------|:----------|:---------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--remove-orphans` | | | Remove containers for services not defined in the Compose file | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file | | `-s`, `--signal` | `string` | `SIGKILL` | SIGNAL to send to the container | diff --git a/docs/reference/compose_logs.md b/docs/reference/compose_logs.md index 15291f71d..4c8ba7e34 100644 --- a/docs/reference/compose_logs.md +++ b/docs/reference/compose_logs.md @@ -1,20 +1,20 @@ # docker compose logs -View output from containers +Displays log output from services ### Options | Name | Type | Default | Description | |:---------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `-f`, `--follow` | | | Follow log output | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `-f`, `--follow` | `bool` | | Follow log output | | `--index` | `int` | `0` | index of the container if service has multiple replicas | -| `--no-color` | | | Produce monochrome output | -| `--no-log-prefix` | | | Don't print prefix in logs | +| `--no-color` | `bool` | | Produce monochrome output | +| `--no-log-prefix` | `bool` | | Don't print prefix in logs | | `--since` | `string` | | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | | `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs for each container | -| `-t`, `--timestamps` | | | Show timestamps | +| `-t`, `--timestamps` | `bool` | | Show timestamps | | `--until` | `string` | | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | diff --git a/docs/reference/compose_ls.md b/docs/reference/compose_ls.md index a1148a167..754e91797 100644 --- a/docs/reference/compose_ls.md +++ b/docs/reference/compose_ls.md @@ -1,17 +1,17 @@ # docker compose ls -List running compose projects +Lists running Compose projects ### Options | Name | Type | Default | Description | |:----------------|:---------|:--------|:-------------------------------------------| -| `-a`, `--all` | | | Show all stopped Compose projects | -| `--dry-run` | | | Execute command in dry run mode | +| `-a`, `--all` | `bool` | | Show all stopped Compose projects | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--filter` | `filter` | | Filter output based on conditions provided | | `--format` | `string` | `table` | Format the output. Values: [table \| json] | -| `-q`, `--quiet` | | | Only display IDs | +| `-q`, `--quiet` | `bool` | | Only display IDs | diff --git a/docs/reference/compose_pause.md b/docs/reference/compose_pause.md index 334c82f18..4a0d5bdcc 100644 --- a/docs/reference/compose_pause.md +++ b/docs/reference/compose_pause.md @@ -1,13 +1,13 @@ # docker compose pause -Pause services +Pauses running containers of a service. They can be unpaused with `docker compose unpause`. ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:--------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:--------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | diff --git a/docs/reference/compose_port.md b/docs/reference/compose_port.md index 5e70b3532..bbbfbf156 100644 --- a/docs/reference/compose_port.md +++ b/docs/reference/compose_port.md @@ -1,13 +1,13 @@ # docker compose port -Print the public port for a port binding +Prints the public port for a port binding ### Options | Name | Type | Default | Description | |:-------------|:---------|:--------|:--------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--index` | `int` | `0` | Index of the container if service has multiple replicas | | `--protocol` | `string` | `tcp` | tcp or udp | diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index 70b409ecc..3572c5305 100644 --- a/docs/reference/compose_ps.md +++ b/docs/reference/compose_ps.md @@ -1,20 +1,35 @@ # docker compose ps -List containers +Lists containers for a Compose project, with current status and exposed ports. + +```console +$ docker compose ps +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp +``` + +By default, only running containers are shown. `--all` flag can be used to include stopped containers. + +```console +$ docker compose ps --all +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +example-foo-1 alpine "/entrypoint.…" foo 4 seconds ago Up 2 seconds 0.0.0.0:8080->80/tcp +example-bar-1 alpine "/entrypoint.…" bar 4 seconds ago exited (0) +``` ### Options | Name | Type | Default | Description | |:----------------------|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all stopped containers (including those created by the run command) | -| `--dry-run` | | | Execute command in dry run mode | +| `-a`, `--all` | `bool` | | Show all stopped containers (including those created by the run command) | +| `--dry-run` | `bool` | | Execute command in dry run mode | | [`--filter`](#filter) | `string` | | Filter services by a property (supported filters: status) | | [`--format`](#format) | `string` | `table` | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--no-trunc` | | | Don't truncate output | +| `--no-trunc` | `bool` | | Don't truncate output | | `--orphans` | `bool` | `true` | Include orphaned services (not declared by project) | -| `-q`, `--quiet` | | | Only display IDs | -| `--services` | | | Display services | +| `-q`, `--quiet` | `bool` | | Only display IDs | +| `--services` | `bool` | | Display services | | [`--status`](#status) | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] | diff --git a/docs/reference/compose_pull.md b/docs/reference/compose_pull.md index 2c29052fd..6a47f9d50 100644 --- a/docs/reference/compose_pull.md +++ b/docs/reference/compose_pull.md @@ -1,18 +1,18 @@ # docker compose pull -Pull service images +Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on those images ### Options | Name | Type | Default | Description | |:-------------------------|:---------|:--------|:-------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--ignore-buildable` | | | Ignore images that can be built | -| `--ignore-pull-failures` | | | Pull what it can and ignores images with pull failures | -| `--include-deps` | | | Also pull services declared as dependencies | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--ignore-buildable` | `bool` | | Ignore images that can be built | +| `--ignore-pull-failures` | `bool` | | Pull what it can and ignores images with pull failures | +| `--include-deps` | `bool` | | Also pull services declared as dependencies | | `--policy` | `string` | | Apply pull policy ("missing"\|"always") | -| `-q`, `--quiet` | | | Pull without printing progress information | +| `-q`, `--quiet` | `bool` | | Pull without printing progress information | diff --git a/docs/reference/compose_push.md b/docs/reference/compose_push.md index 90a4fef24..0efc48c46 100644 --- a/docs/reference/compose_push.md +++ b/docs/reference/compose_push.md @@ -1,16 +1,33 @@ # docker compose push -Push service images +Pushes images for services to their respective registry/repository. + +The following assumptions are made: +- You are pushing an image you have built locally +- You have access to the build key + +Examples + +```yaml +services: + service1: + build: . + image: localhost:5000/yourimage ## goes to local registry + + service2: + build: . + image: your-dockerid/yourimage ## goes to your repository on Docker Hub +``` ### Options -| Name | Type | Default | Description | -|:-------------------------|:-----|:--------|:-------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--ignore-push-failures` | | | Push what it can and ignores images with push failures | -| `--include-deps` | | | Also push images of services declared as dependencies | -| `-q`, `--quiet` | | | Push without printing progress information | +| Name | Type | Default | Description | +|:-------------------------|:-------|:--------|:-------------------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--ignore-push-failures` | `bool` | | Push what it can and ignores images with push failures | +| `--include-deps` | `bool` | | Also push images of services declared as dependencies | +| `-q`, `--quiet` | `bool` | | Push without printing progress information | diff --git a/docs/reference/compose_restart.md b/docs/reference/compose_restart.md index d77b461a8..e9bc161ef 100644 --- a/docs/reference/compose_restart.md +++ b/docs/reference/compose_restart.md @@ -1,15 +1,24 @@ # docker compose restart -Restart service containers +Restarts all stopped and running services, or the specified services only. + +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, refer to +[restart](https://github.com/compose-spec/compose-spec/blob/master/spec.md#restart) +or [restart_policy](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#restart_policy). ### Options -| Name | Type | Default | Description | -|:------------------|:------|:--------|:--------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--no-deps` | | | Don't restart dependent services | -| `-t`, `--timeout` | `int` | `0` | Specify a shutdown timeout in seconds | +| Name | Type | Default | Description | +|:------------------|:-------|:--------|:--------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--no-deps` | `bool` | | Don't restart dependent services | +| `-t`, `--timeout` | `int` | `0` | Specify a shutdown timeout in seconds | diff --git a/docs/reference/compose_rm.md b/docs/reference/compose_rm.md index cbd8e50f6..5e84930ba 100644 --- a/docs/reference/compose_rm.md +++ b/docs/reference/compose_rm.md @@ -1,21 +1,30 @@ # docker compose rm -Removes stopped service containers +Removes stopped service containers. -By default, anonymous volumes attached to containers will not be removed. You -can override this with -v. To list all volumes, use "docker volume ls". +By default, anonymous volumes attached to containers are not removed. You can override this with `-v`. To list all +volumes, use `docker volume ls`. -Any data which is not in a volume will be lost. +Any data which is not in a volume is lost. + +Running the command with no options also removes one-off containers created by `docker compose run`: + +```console +$ docker compose rm +Going to remove djangoquickstart_web_run_1 +Are you sure? [yN] y +Removing djangoquickstart_web_run_1 ... done +``` ### Options -| Name | Type | Default | Description | -|:------------------|:-----|:--------|:----------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `-f`, `--force` | | | Don't ask to confirm removal | -| `-s`, `--stop` | | | Stop the containers, if required, before removing | -| `-v`, `--volumes` | | | Remove any anonymous volumes attached to containers | +| Name | Type | Default | Description | +|:------------------|:-------|:--------|:----------------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `-f`, `--force` | `bool` | | Don't ask to confirm removal | +| `-s`, `--stop` | `bool` | | Stop the containers, if required, before removing | +| `-v`, `--volumes` | `bool` | | Remove any anonymous volumes attached to containers | diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md index 656ea353e..2d08ef4c4 100644 --- a/docs/reference/compose_run.md +++ b/docs/reference/compose_run.md @@ -1,30 +1,82 @@ # docker compose run -Run a one-off command on a service +Runs a one-time command against a service. + +The following command starts the `web` service and runs `bash` as its command: + +```console +$ 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 +`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 +to be created and mapped to the host, specify the `--service-ports` + +```console +$ docker compose run --service-ports web python manage.py shell +``` + +Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run: + +```console +$ 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 +passed it. For example, you could run: + +```console +$ docker compose run db psql -h db -U docker +``` + +This opens an interactive PostgreSQL shell for the linked `db` container. + +If you do not want the run command to start linked containers, use the `--no-deps` flag: + +```console +$ docker compose run --no-deps web python manage.py shell +``` + +If you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag: + +```console +$ 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 +specified in the service configuration. ### Options | Name | Type | Default | Description | |:------------------------|:--------------|:--------|:---------------------------------------------------------------------------------| -| `--build` | | | Build image before starting container | +| `--build` | `bool` | | Build image before starting container | | `--cap-add` | `list` | | Add Linux capabilities | | `--cap-drop` | `list` | | Drop Linux capabilities | -| `-d`, `--detach` | | | Run container in background and print container ID | -| `--dry-run` | | | Execute command in dry run mode | +| `-d`, `--detach` | `bool` | | Run container in background and print container ID | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--entrypoint` | `string` | | Override the entrypoint of the image | | `-e`, `--env` | `stringArray` | | Set environment variables | | `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached | | `-l`, `--label` | `stringArray` | | Add or override a label | | `--name` | `string` | | Assign a name to the container | | `-T`, `--no-TTY` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) | -| `--no-deps` | | | Don't start linked services | +| `--no-deps` | `bool` | | Don't start linked services | | `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host | -| `--quiet-pull` | | | Pull without printing progress information | -| `--remove-orphans` | | | Remove containers for services not defined in the Compose file | -| `--rm` | | | Automatically remove the container when it exits | -| `-P`, `--service-ports` | | | Run command with all service's ports enabled and mapped to the host | -| `--use-aliases` | | | Use the service's network useAliases in the network(s) the container connects to | +| `--quiet-pull` | `bool` | | Pull without printing progress information | +| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file | +| `--rm` | `bool` | | Automatically remove the container when it exits | +| `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host | +| `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to | | `-u`, `--user` | `string` | | Run as specified username or uid | | `-v`, `--volume` | `stringArray` | | Bind mount a volume | | `-w`, `--workdir` | `string` | | Working directory inside the container | diff --git a/docs/reference/compose_scale.md b/docs/reference/compose_scale.md index e30508328..3d0dbdb04 100644 --- a/docs/reference/compose_scale.md +++ b/docs/reference/compose_scale.md @@ -5,10 +5,10 @@ Scale services ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:--------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--no-deps` | | | Don't start linked services | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:--------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--no-deps` | `bool` | | Don't start linked services | diff --git a/docs/reference/compose_start.md b/docs/reference/compose_start.md index 4ea26e9b5..08db7ef21 100644 --- a/docs/reference/compose_start.md +++ b/docs/reference/compose_start.md @@ -1,13 +1,13 @@ # docker compose start -Start services +Starts existing containers for a service ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:--------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:--------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | diff --git a/docs/reference/compose_stats.md b/docs/reference/compose_stats.md index acb22840b..43d8bbc33 100644 --- a/docs/reference/compose_stats.md +++ b/docs/reference/compose_stats.md @@ -7,11 +7,11 @@ Display a live stream of container(s) resource usage statistics | Name | Type | Default | Description | |:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all containers (default shows just running) | -| `--dry-run` | | | Execute command in dry run mode | +| `-a`, `--all` | `bool` | | Show all containers (default shows just running) | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--no-stream` | | | Disable streaming stats and only pull the first result | -| `--no-trunc` | | | Do not truncate output | +| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result | +| `--no-trunc` | `bool` | | Do not truncate output | diff --git a/docs/reference/compose_stop.md b/docs/reference/compose_stop.md index e7cf92a80..fe84f24f8 100644 --- a/docs/reference/compose_stop.md +++ b/docs/reference/compose_stop.md @@ -1,14 +1,14 @@ # docker compose stop -Stop services +Stops running containers without removing them. They can be started again with `docker compose start`. ### Options -| Name | Type | Default | Description | -|:------------------|:------|:--------|:--------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `-t`, `--timeout` | `int` | `0` | Specify a shutdown timeout in seconds | +| Name | Type | Default | Description | +|:------------------|:-------|:--------|:--------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `-t`, `--timeout` | `int` | `0` | Specify a shutdown timeout in seconds | diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md index a23373832..eeacb3866 100644 --- a/docs/reference/compose_top.md +++ b/docs/reference/compose_top.md @@ -1,13 +1,13 @@ # docker compose top -Display the running processes +Displays the running processes ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:--------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:--------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | diff --git a/docs/reference/compose_unpause.md b/docs/reference/compose_unpause.md index 9d810e471..92841cead 100644 --- a/docs/reference/compose_unpause.md +++ b/docs/reference/compose_unpause.md @@ -1,13 +1,13 @@ # docker compose unpause -Unpause services +Unpauses paused containers of a service ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:--------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:--------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | diff --git a/docs/reference/compose_up.md b/docs/reference/compose_up.md index dbe00a82f..295000734 100644 --- a/docs/reference/compose_up.md +++ b/docs/reference/compose_up.md @@ -1,40 +1,58 @@ # docker compose up -Create and start containers +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). +One can optionally select a subset of services to attach to using `--attach` flag, or exclude some services using +`--no-attach` to prevent output to be flooded by some verbose services. + +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 +(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. + +If the process encounters an error, the exit code for this command is `1`. +If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`. ### Options | Name | Type | Default | Description | |:-------------------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------| -| `--abort-on-container-exit` | | | Stops all containers if any container was stopped. Incompatible with -d | -| `--abort-on-container-failure` | | | Stops all containers if any container exited with failure. Incompatible with -d | -| `--always-recreate-deps` | | | Recreate dependent containers. Incompatible with --no-recreate. | +| `--abort-on-container-exit` | `bool` | | Stops all containers if any container was stopped. Incompatible with -d | +| `--abort-on-container-failure` | `bool` | | Stops all containers if any container exited with failure. Incompatible with -d | +| `--always-recreate-deps` | `bool` | | Recreate dependent containers. Incompatible with --no-recreate. | | `--attach` | `stringArray` | | Restrict attaching to the specified services. Incompatible with --attach-dependencies. | -| `--attach-dependencies` | | | Automatically attach to log output of dependent services | -| `--build` | | | Build images before starting containers | -| `-d`, `--detach` | | | Detached mode: Run containers in the background | -| `--dry-run` | | | Execute command in dry run mode | +| `--attach-dependencies` | `bool` | | Automatically attach to log output of dependent services | +| `--build` | `bool` | | Build images before starting containers | +| `-d`, `--detach` | `bool` | | Detached mode: Run containers in the background | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `--exit-code-from` | `string` | | Return the exit code of the selected service container. Implies --abort-on-container-exit | -| `--force-recreate` | | | Recreate containers even if their configuration and image haven't changed | -| `--menu` | | | Enable interactive shortcuts when running attached. Incompatible with --detach. Can also be enable/disable by setting COMPOSE_MENU environment var. | +| `--force-recreate` | `bool` | | Recreate containers even if their configuration and image haven't changed | +| `--menu` | `bool` | | Enable interactive shortcuts when running attached. Incompatible with --detach. Can also be enable/disable by setting COMPOSE_MENU environment var. | | `--no-attach` | `stringArray` | | Do not attach (stream logs) to the specified services | -| `--no-build` | | | Don't build an image, even if it's policy | -| `--no-color` | | | Produce monochrome output | -| `--no-deps` | | | Don't start linked services | -| `--no-log-prefix` | | | Don't print prefix in logs | -| `--no-recreate` | | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | -| `--no-start` | | | Don't start the services after creating them | +| `--no-build` | `bool` | | Don't build an image, even if it's policy | +| `--no-color` | `bool` | | Produce monochrome output | +| `--no-deps` | `bool` | | Don't start linked services | +| `--no-log-prefix` | `bool` | | Don't print prefix in logs | +| `--no-recreate` | `bool` | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | +| `--no-start` | `bool` | | Don't start the services after creating them | | `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") | -| `--quiet-pull` | | | Pull without printing progress information | -| `--remove-orphans` | | | Remove containers for services not defined in the Compose file | -| `-V`, `--renew-anon-volumes` | | | Recreate anonymous volumes instead of retrieving data from the previous containers | +| `--quiet-pull` | `bool` | | Pull without printing progress information | +| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file | +| `-V`, `--renew-anon-volumes` | `bool` | | Recreate anonymous volumes instead of retrieving data from the previous containers | | `--scale` | `stringArray` | | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. | | `-t`, `--timeout` | `int` | `0` | Use this timeout in seconds for container shutdown when attached or when containers are already running | -| `--timestamps` | | | Show timestamps | -| `--wait` | | | Wait for services to be running\|healthy. Implies detached mode. | +| `--timestamps` | `bool` | | Show timestamps | +| `--wait` | `bool` | | Wait for services to be running\|healthy. Implies detached mode. | | `--wait-timeout` | `int` | `0` | Maximum duration to wait for the project to be running\|healthy | -| `-w`, `--watch` | | | Watch source code and rebuild/refresh containers when files are updated. | +| `-w`, `--watch` | `bool` | | Watch source code and rebuild/refresh containers when files are updated. | diff --git a/docs/reference/compose_version.md b/docs/reference/compose_version.md index 9284d8e93..3a6329dad 100644 --- a/docs/reference/compose_version.md +++ b/docs/reference/compose_version.md @@ -7,9 +7,9 @@ Show the Docker Compose version information | Name | Type | Default | Description | |:-----------------|:---------|:--------|:---------------------------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | +| `--dry-run` | `bool` | | Execute command in dry run mode | | `-f`, `--format` | `string` | | Format the output. Values: [pretty \| json]. (Default: pretty) | -| `--short` | | | Shows only Compose's version number | +| `--short` | `bool` | | Shows only Compose's version number | diff --git a/docs/reference/compose_wait.md b/docs/reference/compose_wait.md index 9c9ff6f1c..cc62d5967 100644 --- a/docs/reference/compose_wait.md +++ b/docs/reference/compose_wait.md @@ -5,10 +5,10 @@ Block until the first service container stops ### Options -| Name | Type | Default | Description | -|:-----------------|:-----|:--------|:---------------------------------------------| -| `--down-project` | | | Drops project when the first container stops | -| `--dry-run` | | | Execute command in dry run mode | +| Name | Type | Default | Description | +|:-----------------|:-------|:--------|:---------------------------------------------| +| `--down-project` | `bool` | | Drops project when the first container stops | +| `--dry-run` | `bool` | | Execute command in dry run mode | diff --git a/docs/reference/compose_watch.md b/docs/reference/compose_watch.md index 2a2d226ef..e2b4aef1a 100644 --- a/docs/reference/compose_watch.md +++ b/docs/reference/compose_watch.md @@ -5,12 +5,12 @@ Watch build context for service and rebuild/refresh containers when files are up ### Options -| Name | Type | Default | Description | -|:------------|:-----|:--------|:----------------------------------------------| -| `--dry-run` | | | Execute command in dry run mode | -| `--no-up` | | | Do not build & start services before watching | -| `--prune` | | | Prune dangling images on rebuild | -| `--quiet` | | | hide build output | +| Name | Type | Default | Description | +|:------------|:-------|:--------|:----------------------------------------------| +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--no-up` | `bool` | | Do not build & start services before watching | +| `--prune` | `bool` | | Prune dangling images on rebuild | +| `--quiet` | `bool` | | hide build output | diff --git a/docs/yaml/main/generate.go b/docs/yaml/main/generate.go index 90ac25cf1..090861683 100644 --- a/docs/yaml/main/generate.go +++ b/docs/yaml/main/generate.go @@ -48,7 +48,21 @@ func generateDocs(opts *options) error { if err != nil { return err } - return tool.GenAllTree() + for _, format := range opts.formats { + switch format { + case "yaml": + if err := tool.GenYamlTree(cmd); err != nil { + return err + } + case "md": + if err := tool.GenMarkdownTree(cmd); err != nil { + return err + } + default: + return fmt.Errorf("unknown format %q", format) + } + } + return nil } func disableFlagsInUseLine(cmd *cobra.Command) { @@ -69,15 +83,17 @@ func visitAll(root *cobra.Command, fn func(*cobra.Command)) { } type options struct { - source string - target string + source string + target string + formats []string } func main() { cwd, _ := os.Getwd() opts := &options{ - source: filepath.Join(cwd, "docs", "reference"), - target: filepath.Join(cwd, "docs", "reference"), + source: filepath.Join(cwd, "docs", "reference"), + target: filepath.Join(cwd, "docs", "reference"), + formats: []string{"yaml", "md"}, } fmt.Printf("Project root: %s\n", opts.source) fmt.Printf("Generating yaml files into %s\n", opts.target)