mirror of
https://github.com/docker/compose.git
synced 2025-07-22 05:04:27 +02:00
[v2] use "docker/cli-docs-tool" to generate docs
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
Nicolas De loof
parent
fdc362bf55
commit
3678deed14
@ -1,6 +1,103 @@
|
||||
command: docker compose
|
||||
short: Docker Compose
|
||||
long: "You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage\nmultiple services in Docker containers.\n\n### Use `-f` to specify name and path of one or more Compose files\nUse the `-f` flag to specify the location of a Compose configuration file.\n\n#### Specifying multiple Compose files\nYou can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single \nconfiguration. Compose builds the configuration in the order you supply the files. Subsequent files override and add \nto their predecessors.\n\nFor example, consider this command line:\n\n```console\n$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db\n```\n\nThe `docker-compose.yml` file might specify a `webapp` service.\n\n```yaml\nservices:\n webapp:\n image: examples/web\n ports:\n - \"8000:8000\"\n volumes:\n - \"/data\"\n```\nIf the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file. \nNew values, add to the `webapp` service configuration.\n\n```yaml\nservices:\n webapp:\n build: .\n environment:\n - DEBUG=1\n```\n\nWhen you use multiple Compose files, all paths in the files are relative to the first configuration file specified \nwith `-f`. You can use the `--project-directory` option to override this base path.\n\nUse a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the \nconfiguration are relative to the current working directory.\n\nThe `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory \nand its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.\n\n#### Specifying a path to a single Compose file\nYou can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either \nfrom the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.\n\nFor an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and \nhave a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to \nget the postgres image for the db service from anywhere by using the `-f` flag as follows: \n\n```console\n$ docker compose -f ~/sandbox/rails/compose.yaml pull db\n```\n\n### Use `-p` to specify a project name\n\nEach configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t \nspecify the flag, Compose uses the current directory name. \nProject name can also be set by `COMPOSE_PROJECT_NAME` environment variable.\n\nMost compose subcommand can be ran without a compose file, just passing \nproject name to retrieve the relevant resources.\n\n```console\n$ docker compose -p my_project ps -a\nNAME SERVICE STATUS PORTS\nmy_project_demo_1 demo running \n\n$ docker compose -p my_project logs\ndemo_1 | PING localhost (127.0.0.1): 56 data bytes\ndemo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms\n```\n\n### Use profiles to enable optional services\n\nUse `--profile` to specify one or more active profiles\nCalling `docker compose --profile frontend up` will start the services with the profile `frontend` and services \nwithout any specified profiles. \nYou can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.\n\nProfiles can also be set by `COMPOSE_PROFILES` environment variable.\n\n### Set up environment variables\n\nYou can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.\n\nSetting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,\n`COMPOSE_PROJECT_NAME` environment variable does the same for to the `-p` flag,\nand so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag.\n\nIf flags are explicitly set on command line, associated environment variable is ignored"
|
||||
long: |-
|
||||
You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
|
||||
multiple services in Docker containers.
|
||||
|
||||
### Use `-f` to specify 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. 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
|
||||
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
|
||||
|
||||
$ 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` 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.
|
||||
|
||||
### 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 for to the `-p` flag,
|
||||
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
|
||||
usage: docker compose
|
||||
pname: docker
|
||||
plink: docker.yaml
|
||||
|
||||
@ -1,6 +1,15 @@
|
||||
command: docker compose build
|
||||
short: Build or rebuild services
|
||||
long: "Services are built once and then tagged, by default as `project_service`. \n\nIf the Compose file specifies an\n[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name, \nthe image is tagged with that name, substituting any variables beforehand. See\n[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).\n\nIf you change a service's `Dockerfile` or the contents of its build directory, \nrun `docker compose build` to rebuild it."
|
||||
long: |-
|
||||
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.
|
||||
usage: docker compose build [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,7 +1,12 @@
|
||||
command: docker compose convert
|
||||
aliases: config
|
||||
short: Converts the compose file to platform's canonical format
|
||||
long: "`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,\nit merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into \nfully defined Compose model. \n\nTo allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`"
|
||||
long: |-
|
||||
`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.
|
||||
|
||||
To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`
|
||||
usage: docker compose convert SERVICES
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,9 +1,8 @@
|
||||
command: docker compose cp
|
||||
short: Copy files/folders between a service container and the local filesystem
|
||||
long: Copy files/folders between a service container and the local filesystem
|
||||
usage: |-
|
||||
docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-
|
||||
docker compose cp [OPTIONS] SRC_PATH|- SERVICE:DEST_PATH
|
||||
usage: "docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-\n\tdocker compose
|
||||
cp [OPTIONS] SRC_PATH|- SERVICE:DEST_PATH"
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
options:
|
||||
|
||||
@ -21,8 +21,7 @@ options:
|
||||
- option: remove-orphans
|
||||
value_type: bool
|
||||
default_value: "false"
|
||||
description: |
|
||||
Remove containers for services not defined in the Compose file.
|
||||
description: Remove containers for services not defined in the Compose file.
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
@ -51,7 +50,7 @@ options:
|
||||
shorthand: v
|
||||
value_type: bool
|
||||
default_value: "false"
|
||||
description: |4
|
||||
description: |
|
||||
Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers.
|
||||
deprecated: false
|
||||
experimental: false
|
||||
|
||||
@ -19,7 +19,7 @@ long: |-
|
||||
}
|
||||
```
|
||||
|
||||
The events that can be received using this can be seen [here](https://docs.docker.com/engine/reference/commandline/events/#object-types).
|
||||
The events that can be received using this can be seen [here](/engine/reference/commandline/events/#object-types).
|
||||
usage: docker compose events [options] [--] [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,6 +1,10 @@
|
||||
command: docker compose exec
|
||||
short: Execute a command in a running container.
|
||||
long: "This is the equivalent of `docker exec` targeting a Compose service. \n\nWith this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so \nyou can use a command such as `docker compose exec web sh` to get an interactive prompt."
|
||||
long: |-
|
||||
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
|
||||
you can use a command such as `docker compose exec web sh` to get an interactive prompt.
|
||||
usage: docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
command: docker compose pause
|
||||
short: pause services
|
||||
long: Pauses running containers of a service. They can be unpaused with `docker compose unpause`.
|
||||
long: |
|
||||
Pauses running containers of a service. They can be unpaused with `docker compose unpause`.
|
||||
usage: docker compose pause [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,6 +1,14 @@
|
||||
command: docker compose ps
|
||||
short: List containers
|
||||
long: "Lists containers for a Compose project, with current status and exposed ports.\n\n```console\n$ docker compose ps\nNAME SERVICE STATUS PORTS\nexample_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp\nexample_bar_1 bar exited (1) \n```"
|
||||
long: |-
|
||||
Lists containers for a Compose project, with current status and exposed ports.
|
||||
|
||||
```console
|
||||
$ 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)
|
||||
```
|
||||
usage: docker compose ps [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
command: docker compose pull
|
||||
short: Pull service images
|
||||
long: "Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on \nthose images."
|
||||
long: |-
|
||||
Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on
|
||||
those images.
|
||||
usage: docker compose pull [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
@ -51,7 +53,6 @@ options:
|
||||
experimentalcli: false
|
||||
kubernetes: false
|
||||
swarm: false
|
||||
examples: "suppose you have this `compose.yaml`:\n\n```yaml\nservices:\n db:\n image: postgres\n web:\n build: .\n command: bundle exec rails s -p 3000 -b '0.0.0.0'\n volumes:\n - .:/myapp\n ports:\n - \"3000:3000\"\n depends_on:\n - db\n```\n\nIf you run `docker compose pull ServiceName` in the same directory as the `compose.yaml` file that defines the service, \nDocker pulls the associated image. For example, to call the postgres image configured as the db service in our example, \nyou would run `docker compose pull db`.\n\n```console\n$ docker compose pull db\n[+] Running 1/15\n ⠸ db Pulling 12.4s\n ⠿ 45b42c59be33 Already exists 0.0s\n ⠹ 40adec129f1a Downloading 3.374MB/4.178MB 9.3s\n ⠹ b4c431d00c78 Download complete 9.3s\n ⠹ 2696974e2815 Download complete 9.3s\n ⠹ 564b77596399 Downloading 5.622MB/7.965MB 9.3s\n ⠹ 5044045cf6f2 Downloading 216.7kB/391.1kB 9.3s\n ⠹ d736e67e6ac3 Waiting 9.3s\n ⠹ 390c1c9a5ae4 Waiting 9.3s\n ⠹ c0e62f172284 Waiting 9.3s\n ⠹ ebcdc659c5bf Waiting 9.3s\n ⠹ 29be22cb3acc Waiting 9.3s\n ⠹ f63c47038e66 Waiting 9.3s\n ⠹ 77a0c198cde5 Waiting 9.3s\n ⠹ c8752d5b785c Waiting 9.3s\n``̀"
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
|
||||
@ -1,7 +1,61 @@
|
||||
command: docker compose run
|
||||
short: Run a one-off command on a service.
|
||||
long: "Runs a one-time command against a service. \n\nthe following command starts the `web` service and runs `bash` as its command:\n\n```console\n$ docker compose run web bash\n```\n\nCommands you use with run start in new containers with configuration defined by that of the service,\nincluding volumes, links, and other details. However, there are two important differences:\n\nFirst, the command passed by `run` overrides the command defined in the service configuration. For example, if the \n`web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with \n`python app.py`.\n\nThe second difference is that the `docker compose run` command does not create any of the ports specified in the \nservice configuration. This prevents port collisions with already-open ports. If you do want the service’s ports \nto be created and mapped to the host, specify the `--service-ports`\n\n```console\n$ docker compose run --service-ports web python manage.py shell\n```\n\nAlternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:\n\n```console\n$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell\n```\n\nIf you start a service configured with links, the run command first checks to see if the linked service is running \nand starts the service if it is stopped. Once all the linked services are running, the run executes the command you \npassed it. For example, you could run:\n\n```console\n$ docker compose run db psql -h db -U docker\n```\n\nThis opens an interactive PostgreSQL shell for the linked `db` container.\n\nIf you do not want the run command to start linked containers, use the `--no-deps` flag:\n\n```console\n$ docker compose run --no-deps web python manage.py shell\n```\n\nIf you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:\n\n```console\n$ docker compose run --rm web python manage.py db upgrade\n```\n\nThis runs a database upgrade script, and removes the container when finished running, even if a restart policy is \nspecified in the service configuration."
|
||||
usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
|
||||
long: |-
|
||||
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.
|
||||
usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l
|
||||
KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
options:
|
||||
@ -45,7 +99,7 @@ options:
|
||||
swarm: false
|
||||
- option: name
|
||||
value_type: string
|
||||
description: ' Assign a name to the container'
|
||||
description: Assign a name to the container
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
command: docker compose stop
|
||||
short: Stop services
|
||||
long: Stops running containers without removing them. They can be started again with `docker compose start`.
|
||||
long: |
|
||||
Stops running containers without removing them. They can be started again with `docker compose start`.
|
||||
usage: docker compose stop [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
|
||||
@ -4,7 +4,13 @@ long: Displays the running processes.
|
||||
usage: docker compose top [SERVICES...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
examples: "```console\n$ docker compose top\nexample_foo_1\nUID PID PPID C STIME TTY TIME CMD\nroot 142353 142331 2 15:33 ? 00:00:00 ping localhost -c 5 \n```"
|
||||
examples: |-
|
||||
```console
|
||||
$ 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
|
||||
```
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
|
||||
@ -1,6 +1,22 @@
|
||||
command: docker compose up
|
||||
short: Create and start containers
|
||||
long: "Builds, (re)creates, starts, and attaches to containers for a service.\n\nUnless they are already running, this command also starts any linked services.\n\nThe `docker compose up` command aggregates the output of each container (liked `docker compose logs --follow` does). \nWhen the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the \nbackground and leaves them running.\n\nIf there are existing containers for a service, and the service’s configuration or image was changed after the \ncontainer’s creation, `docker compose up` picks up the changes by stopping and recreating the containers \n(preserving mounted volumes). To prevent Compose from picking up changes, use the `--no-recreate` flag.\n\nIf you want to force Compose to stop and recreate all containers, use the `--force-recreate` flag.\n\nIf the process encounters an error, the exit code for this command is `1`.\nIf the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`."
|
||||
long: |-
|
||||
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 (liked `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
|
||||
(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`.
|
||||
usage: docker compose up [SERVICE...]
|
||||
pname: docker compose
|
||||
plink: docker_compose.yaml
|
||||
@ -18,8 +34,7 @@ options:
|
||||
- option: always-recreate-deps
|
||||
value_type: bool
|
||||
default_value: "false"
|
||||
description: |
|
||||
Recreate dependent containers. Incompatible with --no-recreate.
|
||||
description: Recreate dependent containers. Incompatible with --no-recreate.
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
@ -158,8 +173,7 @@ options:
|
||||
- option: remove-orphans
|
||||
value_type: bool
|
||||
default_value: "false"
|
||||
description: |
|
||||
Remove containers for services not defined in the Compose file.
|
||||
description: Remove containers for services not defined in the Compose file.
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
|
||||
@ -18,32 +18,21 @@ package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io/ioutil"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
|
||||
clidocstool "github.com/docker/cli-docs-tool"
|
||||
"github.com/docker/compose/v2/cmd/compose"
|
||||
. "github.com/docker/compose/v2/docs/yaml"
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
const descriptionSourcePath = "docs/reference/"
|
||||
|
||||
func generateCliYaml(opts *options) error {
|
||||
cmd := &cobra.Command{Use: "docker"}
|
||||
cmd.AddCommand(compose.RootCommand(nil))
|
||||
disableFlagsInUseLine(cmd)
|
||||
source := filepath.Join(opts.source, descriptionSourcePath)
|
||||
if err := loadLongDescription(cmd, source); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
cmd.DisableAutoGenTag = true
|
||||
return GenYamlTree(cmd, opts.target)
|
||||
return clidocstool.GenYamlTree(cmd, opts.target)
|
||||
}
|
||||
|
||||
func disableFlagsInUseLine(cmd *cobra.Command) {
|
||||
@ -63,54 +52,16 @@ func visitAll(root *cobra.Command, fn func(*cobra.Command)) {
|
||||
fn(root)
|
||||
}
|
||||
|
||||
func loadLongDescription(cmd *cobra.Command, path ...string) error {
|
||||
for _, cmd := range cmd.Commands() {
|
||||
if cmd.Name() == "" {
|
||||
continue
|
||||
}
|
||||
fullpath := filepath.Join(path[0], strings.Join(append(path[1:], cmd.Name()), "_")+".md")
|
||||
|
||||
if cmd.HasSubCommands() {
|
||||
if err := loadLongDescription(cmd, path[0], cmd.Name()); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
if _, err := os.Stat(fullpath); err != nil {
|
||||
log.Printf("WARN: %s does not exist, skipping\n", fullpath)
|
||||
continue
|
||||
}
|
||||
|
||||
content, err := ioutil.ReadFile(fullpath)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
description, examples := ParseMDContent(string(content))
|
||||
cmd.Long = description
|
||||
cmd.Example = examples
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type options struct {
|
||||
source string
|
||||
target string
|
||||
}
|
||||
|
||||
func parseArgs() (*options, error) {
|
||||
opts := &options{}
|
||||
cwd, _ := os.Getwd()
|
||||
flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
|
||||
flags.StringVar(&opts.source, "root", cwd, "Path to project root")
|
||||
flags.StringVar(&opts.target, "target", filepath.Join(cwd, "docs", "reference"), "Target path for generated yaml files")
|
||||
err := flags.Parse(os.Args[1:])
|
||||
return opts, err
|
||||
}
|
||||
|
||||
func main() {
|
||||
opts, err := parseArgs()
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, err.Error())
|
||||
cwd, _ := os.Getwd()
|
||||
opts := &options{
|
||||
source: cwd,
|
||||
target: filepath.Join(cwd, "docs", "reference"),
|
||||
}
|
||||
fmt.Printf("Project root: %s\n", opts.source)
|
||||
fmt.Printf("Generating yaml files into %s\n", opts.target)
|
||||
|
||||
@ -1,290 +0,0 @@
|
||||
/*
|
||||
Copyright 2020 Docker Compose CLI authors
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
*/
|
||||
|
||||
package yaml
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
yaml "gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
type cmdOption struct {
|
||||
Option string
|
||||
Shorthand string `yaml:",omitempty"`
|
||||
ValueType string `yaml:"value_type,omitempty"`
|
||||
DefaultValue string `yaml:"default_value,omitempty"`
|
||||
Description string `yaml:",omitempty"`
|
||||
Deprecated bool
|
||||
MinAPIVersion string `yaml:"min_api_version,omitempty"`
|
||||
Experimental bool
|
||||
ExperimentalCLI bool
|
||||
Kubernetes bool
|
||||
Swarm bool
|
||||
OSType string `yaml:"os_type,omitempty"`
|
||||
}
|
||||
|
||||
type cmdDoc struct {
|
||||
Name string `yaml:"command"`
|
||||
SeeAlso []string `yaml:"parent,omitempty"`
|
||||
Version string `yaml:"engine_version,omitempty"`
|
||||
Aliases string `yaml:",omitempty"`
|
||||
Short string `yaml:",omitempty"`
|
||||
Long string `yaml:",omitempty"`
|
||||
Usage string `yaml:",omitempty"`
|
||||
Pname string `yaml:",omitempty"`
|
||||
Plink string `yaml:",omitempty"`
|
||||
Cname []string `yaml:",omitempty"`
|
||||
Clink []string `yaml:",omitempty"`
|
||||
Options []cmdOption `yaml:",omitempty"`
|
||||
InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
|
||||
Example string `yaml:"examples,omitempty"`
|
||||
Deprecated bool
|
||||
MinAPIVersion string `yaml:"min_api_version,omitempty"`
|
||||
Experimental bool
|
||||
ExperimentalCLI bool
|
||||
Kubernetes bool
|
||||
Swarm bool
|
||||
OSType string `yaml:"os_type,omitempty"`
|
||||
}
|
||||
|
||||
// GenYamlTree creates yaml structured ref files
|
||||
func GenYamlTree(cmd *cobra.Command, dir string) error {
|
||||
emptyStr := func(s string) string { return "" }
|
||||
return GenYamlTreeCustom(cmd, dir, emptyStr)
|
||||
}
|
||||
|
||||
// GenYamlTreeCustom creates yaml structured ref files
|
||||
func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string) error {
|
||||
for _, c := range cmd.Commands() {
|
||||
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
|
||||
continue
|
||||
}
|
||||
if err := GenYamlTreeCustom(c, dir, filePrepender); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if !cmd.HasParent() {
|
||||
return nil
|
||||
}
|
||||
|
||||
basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
|
||||
filename := filepath.Join(dir, basename)
|
||||
f, err := os.Create(filename)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer f.Close() //nolint: errcheck
|
||||
|
||||
if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
|
||||
return err
|
||||
}
|
||||
return GenYamlCustom(cmd, f)
|
||||
}
|
||||
|
||||
// GenYamlCustom creates custom yaml output
|
||||
// nolint: gocyclo
|
||||
func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
|
||||
cliDoc := cmdDoc{}
|
||||
cliDoc.Name = cmd.CommandPath()
|
||||
|
||||
cliDoc.Aliases = strings.Join(cmd.Aliases, ", ")
|
||||
cliDoc.Short = cmd.Short
|
||||
cliDoc.Long = cmd.Long
|
||||
if len(cliDoc.Long) == 0 {
|
||||
cliDoc.Long = cliDoc.Short
|
||||
}
|
||||
|
||||
if cmd.Runnable() {
|
||||
cliDoc.Usage = cmd.UseLine()
|
||||
}
|
||||
|
||||
if len(cmd.Example) > 0 {
|
||||
cliDoc.Example = cmd.Example
|
||||
}
|
||||
if len(cmd.Deprecated) > 0 {
|
||||
cliDoc.Deprecated = true
|
||||
}
|
||||
// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`
|
||||
for curr := cmd; curr != nil; curr = curr.Parent() {
|
||||
if v, ok := curr.Annotations["version"]; ok && cliDoc.MinAPIVersion == "" {
|
||||
cliDoc.MinAPIVersion = v
|
||||
}
|
||||
if _, ok := curr.Annotations["experimental"]; ok && !cliDoc.Experimental {
|
||||
cliDoc.Experimental = true
|
||||
}
|
||||
if _, ok := curr.Annotations["experimentalCLI"]; ok && !cliDoc.ExperimentalCLI {
|
||||
cliDoc.ExperimentalCLI = true
|
||||
}
|
||||
if _, ok := curr.Annotations["kubernetes"]; ok && !cliDoc.Kubernetes {
|
||||
cliDoc.Kubernetes = true
|
||||
}
|
||||
if _, ok := curr.Annotations["swarm"]; ok && !cliDoc.Swarm {
|
||||
cliDoc.Swarm = true
|
||||
}
|
||||
if os, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" {
|
||||
cliDoc.OSType = os
|
||||
}
|
||||
}
|
||||
|
||||
flags := cmd.NonInheritedFlags()
|
||||
if flags.HasFlags() {
|
||||
cliDoc.Options = genFlagResult(flags)
|
||||
}
|
||||
flags = cmd.InheritedFlags()
|
||||
if flags.HasFlags() {
|
||||
cliDoc.InheritedOptions = genFlagResult(flags)
|
||||
}
|
||||
|
||||
if hasSeeAlso(cmd) {
|
||||
if cmd.HasParent() {
|
||||
parent := cmd.Parent()
|
||||
cliDoc.Pname = parent.CommandPath()
|
||||
link := cliDoc.Pname + ".yaml"
|
||||
cliDoc.Plink = strings.Replace(link, " ", "_", -1)
|
||||
cmd.VisitParents(func(c *cobra.Command) {
|
||||
if c.DisableAutoGenTag {
|
||||
cmd.DisableAutoGenTag = c.DisableAutoGenTag
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
children := cmd.Commands()
|
||||
sort.Sort(byName(children))
|
||||
|
||||
for _, child := range children {
|
||||
if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
|
||||
continue
|
||||
}
|
||||
currentChild := cliDoc.Name + " " + child.Name()
|
||||
cliDoc.Cname = append(cliDoc.Cname, cliDoc.Name+" "+child.Name())
|
||||
link := currentChild + ".yaml"
|
||||
cliDoc.Clink = append(cliDoc.Clink, strings.Replace(link, " ", "_", -1))
|
||||
}
|
||||
}
|
||||
|
||||
final, err := yaml.Marshal(&cliDoc)
|
||||
if err != nil {
|
||||
fmt.Println(err)
|
||||
os.Exit(1)
|
||||
}
|
||||
if _, err := fmt.Fprintln(w, string(final)); err != nil {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func genFlagResult(flags *pflag.FlagSet) []cmdOption {
|
||||
var (
|
||||
result []cmdOption
|
||||
opt cmdOption
|
||||
)
|
||||
|
||||
flags.VisitAll(func(flag *pflag.Flag) {
|
||||
opt = cmdOption{
|
||||
Option: flag.Name,
|
||||
ValueType: flag.Value.Type(),
|
||||
DefaultValue: forceMultiLine(flag.DefValue),
|
||||
Description: forceMultiLine(flag.Usage),
|
||||
Deprecated: len(flag.Deprecated) > 0,
|
||||
}
|
||||
|
||||
// Todo, when we mark a shorthand is deprecated, but specify an empty message.
|
||||
// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
|
||||
// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
|
||||
if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
|
||||
opt.Shorthand = flag.Shorthand
|
||||
}
|
||||
if _, ok := flag.Annotations["experimental"]; ok {
|
||||
opt.Experimental = true
|
||||
}
|
||||
if v, ok := flag.Annotations["version"]; ok {
|
||||
opt.MinAPIVersion = v[0]
|
||||
}
|
||||
if _, ok := flag.Annotations["experimentalCLI"]; ok {
|
||||
opt.ExperimentalCLI = true
|
||||
}
|
||||
if _, ok := flag.Annotations["kubernetes"]; ok {
|
||||
opt.Kubernetes = true
|
||||
}
|
||||
if _, ok := flag.Annotations["swarm"]; ok {
|
||||
opt.Swarm = true
|
||||
}
|
||||
|
||||
// Note that the annotation can have multiple ostypes set, however, multiple
|
||||
// values are currently not used (and unlikely will).
|
||||
//
|
||||
// To simplify usage of the os_type property in the YAML, and for consistency
|
||||
// with the same property for commands, we're only using the first ostype that's set.
|
||||
if ostypes, ok := flag.Annotations["ostype"]; ok && len(opt.OSType) == 0 && len(ostypes) > 0 {
|
||||
opt.OSType = ostypes[0]
|
||||
}
|
||||
|
||||
result = append(result, opt)
|
||||
})
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
// Temporary workaround for yaml lib generating incorrect yaml with long strings
|
||||
// that do not contain \n.
|
||||
func forceMultiLine(s string) string {
|
||||
if len(s) > 60 && !strings.Contains(s, "\n") {
|
||||
s = s + "\n"
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// Small duplication for cobra utils
|
||||
func hasSeeAlso(cmd *cobra.Command) bool {
|
||||
if cmd.HasParent() {
|
||||
return true
|
||||
}
|
||||
for _, c := range cmd.Commands() {
|
||||
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
|
||||
continue
|
||||
}
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// ParseMDContent parse markdown file looking for Description and Examples sections
|
||||
func ParseMDContent(mdString string) (description string, examples string) {
|
||||
parsedContent := strings.Split(mdString, "\n## ")
|
||||
for _, s := range parsedContent {
|
||||
if strings.Index(s, "Description") == 0 {
|
||||
description = strings.TrimSpace(strings.TrimPrefix(s, "Description"))
|
||||
}
|
||||
if strings.Index(s, "Examples") == 0 {
|
||||
examples = strings.TrimSpace(strings.TrimPrefix(s, "Examples"))
|
||||
}
|
||||
}
|
||||
return description, examples
|
||||
}
|
||||
|
||||
type byName []*cobra.Command
|
||||
|
||||
func (s byName) Len() int { return len(s) }
|
||||
func (s byName) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
|
||||
func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
|
||||
2
go.mod
2
go.mod
@ -12,6 +12,7 @@ require (
|
||||
github.com/distribution/distribution/v3 v3.0.0-20210316161203-a01c71e2477e
|
||||
github.com/docker/buildx v0.5.2-0.20210422185057-908a856079fc
|
||||
github.com/docker/cli v20.10.7+incompatible
|
||||
github.com/docker/cli-docs-tool v0.1.1
|
||||
github.com/docker/docker v20.10.7+incompatible
|
||||
github.com/docker/go-connections v0.4.0
|
||||
github.com/docker/go-units v0.4.0
|
||||
@ -37,7 +38,6 @@ require (
|
||||
github.com/stretchr/testify v1.7.0
|
||||
github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
|
||||
golang.org/x/sync v0.0.0-20210220032951-036812b2e83c
|
||||
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b
|
||||
gotest.tools v2.2.0+incompatible
|
||||
gotest.tools/v3 v3.0.3
|
||||
k8s.io/client-go v0.21.0 // indirect
|
||||
|
||||
2
go.sum
2
go.sum
@ -342,6 +342,8 @@ github.com/docker/cli v0.0.0-20191017083524-a8ff7f821017/go.mod h1:JLrzqnKDaYBop
|
||||
github.com/docker/cli v20.10.5+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
|
||||
github.com/docker/cli v20.10.7+incompatible h1:pv/3NqibQKphWZiAskMzdz8w0PRbtTaEB+f6NwdU7Is=
|
||||
github.com/docker/cli v20.10.7+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
|
||||
github.com/docker/cli-docs-tool v0.1.1 h1:c6vuTMvogCkSFQCXIr6Mb4gFgUpdZ+28YMbCBfaQLik=
|
||||
github.com/docker/cli-docs-tool v0.1.1/go.mod h1:oMzPNt1wC3TcxuY22GMnOODNOxkwGH51gV3AhqAjFQ4=
|
||||
github.com/docker/compose-on-kubernetes v0.4.19-0.20190128150448-356b2919c496/go.mod h1:iT2pYfi580XlpaV4KmK0T6+4/9+XoKmk/fhoDod1emE=
|
||||
github.com/docker/distribution v0.0.0-20190905152932-14b96e55d84c/go.mod h1:0+TTO4EOBfRPhZXAeF1Vu+W3hHZ8eLp8PgKVZlcvtFY=
|
||||
github.com/docker/distribution v2.6.0-rc.1.0.20180327202408-83389a148052+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user