From abbba74b27bfbcb7e5dea8018f02e2b065ad51d7 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Tue, 8 Jun 2021 09:39:49 +0200 Subject: [PATCH] update reference docs Signed-off-by: Nicolas De Loof --- cli/cmd/compose/build.go | 2 +- cli/cmd/compose/exec.go | 6 +-- cli/cmd/compose/run.go | 2 +- docs/reference/compose_build.md | 12 ++++++ docs/reference/compose_cp.md | 0 docs/reference/compose_images.md | 0 docs/reference/compose_port.md | 4 ++ docs/reference/compose_ps.md | 9 +++- docs/reference/compose_restart.md | 10 +++++ docs/reference/compose_run.md | 1 + docs/reference/compose_top.md | 2 +- docs/reference/docker_compose.yaml | 2 + docs/reference/docker_compose_build.yaml | 9 +++- docs/reference/docker_compose_cp.yaml | 54 ++++++++++++++++++++++++ docs/reference/docker_compose_exec.yaml | 2 +- docs/reference/docker_compose_port.yaml | 2 +- docs/reference/docker_compose_ps.yaml | 5 ++- docs/reference/docker_compose_run.yaml | 29 ++++++++++++- docs/reference/docker_compose_top.yaml | 2 +- 19 files changed, 138 insertions(+), 15 deletions(-) create mode 100644 docs/reference/compose_cp.md create mode 100644 docs/reference/compose_images.md create mode 100644 docs/reference/compose_port.md create mode 100644 docs/reference/docker_compose_cp.yaml diff --git a/cli/cmd/compose/build.go b/cli/cmd/compose/build.go index 780f39550..773296a3a 100644 --- a/cli/cmd/compose/build.go +++ b/cli/cmd/compose/build.go @@ -64,7 +64,7 @@ func buildCommand(p *projectOptions, backend compose.Service) *cobra.Command { } cmd.Flags().BoolVarP(&opts.quiet, "quiet", "q", false, "Don't print anything to STDOUT") cmd.Flags().BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image.") - cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "tty")`) + cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "noTty")`) cmd.Flags().StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables for services.") cmd.Flags().Bool("parallel", true, "Build images in parallel. DEPRECATED") cmd.Flags().MarkHidden("parallel") //nolint:errcheck diff --git a/cli/cmd/compose/exec.go b/cli/cmd/compose/exec.go index 97b7349f4..a57bed76f 100644 --- a/cli/cmd/compose/exec.go +++ b/cli/cmd/compose/exec.go @@ -36,7 +36,7 @@ type execOpts struct { environment []string workingDir string - tty bool + noTty bool user string detach bool index int @@ -68,7 +68,7 @@ func execCommand(p *projectOptions, backend compose.Service) *cobra.Command { runCmd.Flags().IntVar(&opts.index, "index", 1, "index of the container if there are multiple instances of a service [default: 1].") runCmd.Flags().BoolVarP(&opts.privileged, "privileged", "", false, "Give extended privileges to the process.") runCmd.Flags().StringVarP(&opts.user, "user", "u", "", "Run the command as this user.") - runCmd.Flags().BoolVarP(&opts.tty, "", "T", false, "Disable pseudo-tty allocation. By default `docker compose exec` allocates a TTY.") + runCmd.Flags().BoolVarP(&opts.noTty, "", "T", false, "Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.") runCmd.Flags().StringVarP(&opts.workingDir, "workdir", "w", "", "Path to workdir directory for this command.") runCmd.Flags().SetInterspersed(false) @@ -85,7 +85,7 @@ func runExec(ctx context.Context, backend compose.Service, opts execOpts) error Service: opts.service, Command: opts.command, Environment: opts.environment, - Tty: !opts.tty, + Tty: !opts.noTty, User: opts.user, Privileged: opts.privileged, Index: opts.index, diff --git a/cli/cmd/compose/run.go b/cli/cmd/compose/run.go index 7d619a4db..5884b5541 100644 --- a/cli/cmd/compose/run.go +++ b/cli/cmd/compose/run.go @@ -128,7 +128,7 @@ func runCommand(p *projectOptions, backend compose.Service) *cobra.Command { flags.StringArrayVarP(&opts.environment, "env", "e", []string{}, "Set environment variables") flags.StringArrayVarP(&opts.labels, "labels", "l", []string{}, "Add or override a label") flags.BoolVar(&opts.Remove, "rm", false, "Automatically remove the container when it exits") - flags.BoolVarP(&opts.noTty, "no-TTY", "T", false, "Disable pseudo-tty allocation. By default docker compose run allocates a TTY") + flags.BoolVarP(&opts.noTty, "no-TTY", "T", false, "Disable pseudo-noTty allocation. By default docker compose run allocates a TTY") flags.StringVar(&opts.name, "name", "", " Assign a name to the container") flags.StringVarP(&opts.user, "user", "u", "", "Run as specified username or uid") flags.StringVarP(&opts.workdir, "workdir", "w", "", "Working directory inside the container") diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md index e69de29bb..caa0f55eb 100644 --- a/docs/reference/compose_build.md +++ b/docs/reference/compose_build.md @@ -0,0 +1,12 @@ + +## Description + +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. \ No newline at end of file diff --git a/docs/reference/compose_cp.md b/docs/reference/compose_cp.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_images.md b/docs/reference/compose_images.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_port.md b/docs/reference/compose_port.md new file mode 100644 index 000000000..b78d0837c --- /dev/null +++ b/docs/reference/compose_port.md @@ -0,0 +1,4 @@ + +## Description + +Prints the public port for a port binding. \ No newline at end of file diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index 92fecf0c3..e3a1e0a33 100644 --- a/docs/reference/compose_ps.md +++ b/docs/reference/compose_ps.md @@ -1,4 +1,11 @@ ## Description -Lists containers for a Compose project. +Lists containers for a Compose project, with current status and exposed ports. + +``` +$ docker compose ps +NAME SERVICE STATUS PORTS +example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp +example_bar_1 bar exited (1) +``` \ No newline at end of file diff --git a/docs/reference/compose_restart.md b/docs/reference/compose_restart.md index e69de29bb..30d62d698 100644 --- a/docs/reference/compose_restart.md +++ b/docs/reference/compose_restart.md @@ -0,0 +1,10 @@ +Restarts all stopped and running services. + +If you make changes to your `compose.yml` configuration, these changes are not reflected +after running this command. For example, changes to environment variables (which are added +after a container is built, but before the container's command is executed) are not updated +after restarting. + +If you are looking to configure a service's restart policy, please 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). \ No newline at end of file diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md index 8c83c13bf..19b8ec663 100644 --- a/docs/reference/compose_run.md +++ b/docs/reference/compose_run.md @@ -1,4 +1,5 @@ +## Description Runs a one-time command against a service. diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md index 2845e8cc7..d2d30e80a 100644 --- a/docs/reference/compose_top.md +++ b/docs/reference/compose_top.md @@ -7,7 +7,7 @@ Displays the running processes. ``` $ docker compose top -sample_foo_1 +example_foo_1 UID PID PPID C STIME TTY TIME CMD root 142353 142331 2 15:33 ? 00:00:00 ping localhost -c 5 ``` \ No newline at end of file diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml index cd6d20309..125728719 100644 --- a/docs/reference/docker_compose.yaml +++ b/docs/reference/docker_compose.yaml @@ -57,6 +57,7 @@ plink: docker.yaml cname: - docker compose build - docker compose convert + - docker compose cp - docker compose create - docker compose down - docker compose events @@ -81,6 +82,7 @@ cname: clink: - docker_compose_build.yaml - docker_compose_convert.yaml + - docker_compose_cp.yaml - docker_compose_create.yaml - docker_compose_down.yaml - docker_compose_events.yaml diff --git a/docs/reference/docker_compose_build.yaml b/docs/reference/docker_compose_build.yaml index 8a5e8972a..674119b72 100644 --- a/docs/reference/docker_compose_build.yaml +++ b/docs/reference/docker_compose_build.yaml @@ -1,6 +1,11 @@ command: docker compose build short: Build or rebuild services -long: 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." usage: docker compose build [SERVICE...] pname: docker compose plink: docker_compose.yaml @@ -73,7 +78,7 @@ options: - option: progress value_type: string default_value: auto - description: Set type of progress output ("auto", "plain", "tty") + description: Set type of progress output ("auto", "plain", "noTty") deprecated: false experimental: false experimentalcli: false diff --git a/docs/reference/docker_compose_cp.yaml b/docs/reference/docker_compose_cp.yaml new file mode 100644 index 000000000..cb7282c77 --- /dev/null +++ b/docs/reference/docker_compose_cp.yaml @@ -0,0 +1,54 @@ +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 +pname: docker compose +plink: docker_compose.yaml +options: + - option: all + value_type: bool + default_value: "false" + description: Copy to all the containers of the service. + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: archive + shorthand: a + value_type: bool + default_value: "false" + description: Archive mode (copy all uid/gid information) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: follow-link + shorthand: L + value_type: bool + default_value: "false" + description: Always follow symbol link in SRC_PATH + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: index + value_type: int + default_value: "1" + description: | + Index of the container if there are multiple instances of a service [default: 1]. + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/docs/reference/docker_compose_exec.yaml b/docs/reference/docker_compose_exec.yaml index 5f90c8b1c..f2963c19d 100644 --- a/docs/reference/docker_compose_exec.yaml +++ b/docs/reference/docker_compose_exec.yaml @@ -13,7 +13,7 @@ options: value_type: bool default_value: "false" description: | - Disable pseudo-tty allocation. By default `docker compose exec` allocates a TTY. + Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. deprecated: false experimental: false experimentalcli: false diff --git a/docs/reference/docker_compose_port.yaml b/docs/reference/docker_compose_port.yaml index 1f8f0f019..0005b9338 100644 --- a/docs/reference/docker_compose_port.yaml +++ b/docs/reference/docker_compose_port.yaml @@ -1,6 +1,6 @@ command: docker compose port short: Print the public port for a port binding. -long: Print the public port for a port binding. +long: Prints the public port for a port binding. usage: docker compose port [options] [--] SERVICE PRIVATE_PORT pname: docker compose plink: docker_compose.yaml diff --git a/docs/reference/docker_compose_ps.yaml b/docs/reference/docker_compose_ps.yaml index 042159c36..b91c93609 100644 --- a/docs/reference/docker_compose_ps.yaml +++ b/docs/reference/docker_compose_ps.yaml @@ -1,6 +1,9 @@ command: docker compose ps short: List containers -long: Lists containers for a Compose project. +long: "Lists containers for a Compose project, with current status and exposed ports.\n\n```\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```" usage: docker compose ps pname: docker compose plink: docker_compose.yaml diff --git a/docs/reference/docker_compose_run.yaml b/docs/reference/docker_compose_run.yaml index 471d08339..4aa7d0ed9 100644 --- a/docs/reference/docker_compose_run.yaml +++ b/docs/reference/docker_compose_run.yaml @@ -1,6 +1,31 @@ command: docker compose run short: Run a one-off command on a service. -long: 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`docker compose run web bash`\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```\ndocker + 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```\ndocker compose run --publish 8080:80 -p 2022:22 + -p 127.0.0.1:2021:21 web python manage.py shell\n```\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```\ndocker 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```\ndocker + 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```\ndocker 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...] pname: docker compose @@ -57,7 +82,7 @@ options: value_type: bool default_value: "false" description: | - Disable pseudo-tty allocation. By default docker compose run allocates a TTY + Disable pseudo-noTty allocation. By default docker compose run allocates a TTY deprecated: false experimental: false experimentalcli: false diff --git a/docs/reference/docker_compose_top.yaml b/docs/reference/docker_compose_top.yaml index f8595d616..7492a3769 100644 --- a/docs/reference/docker_compose_top.yaml +++ b/docs/reference/docker_compose_top.yaml @@ -4,7 +4,7 @@ long: Displays the running processes. usage: docker compose top pname: docker compose plink: docker_compose.yaml -examples: "```\n$ docker compose top\nsample_foo_1\nUID PID PPID C STIME +examples: "```\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```" deprecated: false