Updating Compose documentation

- Split out commands into individual pages for maintainability
- Add full usage in commands pages for usability
- Updated description of the run command
- adding in Aanand's comment

Signed-off-by: Mary Anthony <[email protected]>

docs/env.md

@@ -10,7 +10,6 @@ weight=3
 <![end-metadata]-->
 
 # Compose environment variables reference
-===============================
 
 **Note:** Environment variables are no longer the recommended method for connecting to linked services. Instead, you should use the link name (by default, the name of the linked service) as the hostname to connect to. See the [docker-compose.yml documentation](yml.md#links) for details.
 

docs/reference/build.md

@@ -0,0 +1,22 @@
+<!--[metadata]>
++++
+title = "build"
+description = "build"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  build"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# build
+
+```
+Usage: build [options] [SERVICE...]
+
+Options:
+--no-cache  Do not use cache when building the image.
+```
+
+Services are built once and then tagged as `project_service`, e.g.,
+`composetest_db`. If you change a service's Dockerfile or the contents of its
+build directory, run `docker-compose build` to rebuild it.

docs/reference/docker-compose.md

@@ -0,0 +1,55 @@
+<!--[metadata]>
++++
+title = "docker-compose"
+description = "docker-compose Command Binary"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  docker-compose"]
+[menu.main]
+parent = "smn_compose_cli"
+weight=-2	
++++
+<![end-metadata]-->
+
+
+# docker-compose Command
+
+```
+Usage:
+  docker-compose [options] [COMMAND] [ARGS...]
+  docker-compose -h|--help
+
+Options:
+  -f, --file FILE           Specify an alternate compose file (default: docker-compose.yml)
+  -p, --project-name NAME   Specify an alternate project name (default: directory name)
+  --verbose                 Show more output
+  -v, --version             Print version and exit
+
+Commands:
+  build              Build or rebuild services
+  help               Get help on a command
+  kill               Kill containers
+  logs               View output from containers
+  port               Print the public port for a port binding
+  ps                 List containers
+  pull               Pulls service images
+  restart            Restart services
+  rm                 Remove stopped containers
+  run                Run a one-off command
+  scale              Set number of containers for a service
+  start              Start services
+  stop               Stop services
+  up                 Create and start containers
+  migrate-to-labels  Recreate containers to add labels
+```
+
+The Docker Compose binary. You use this command to build and manage multiple services in Docker containers.
+
+Use the `-f` flag to specify the location of a Compose configuration file. This
+flag is optional. If you don't provide this flag. Compose looks for a file named
+`docker-compose.yml` in the  working directory. If the file is not found,
+Compose looks in each parent directory successively, until it finds the file.
+
+Use a `-` as the filename to read configuration file from stdin. When stdin is
+used all paths in the configuration are relative to the current working
+directory.
+
+Each configuration can 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.

docs/reference/help.md

@@ -0,0 +1,17 @@
+<!--[metadata]>
++++
+title = "help"
+description = "help"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  help"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# help
+
+```
+Usage: help COMMAND
+```
+
+Displays help and usage instructions for a command.

docs/reference/index.md

@@ -0,0 +1,29 @@
+<!--[metadata]>
++++
+title = "Compose CLI reference"
+description = "Compose CLI reference"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+identifier = "smn_compose_cli"
+parent = "smn_compose_ref"	
++++
+<![end-metadata]-->
+
+## Compose CLI reference
+
+The following pages describe the usage information for the [docker-compose](/reference/docker-compose.md) subcommands. You can also see this information by running `docker-compose [SUBCOMMAND] --help` from the command line.
+
+* [build](/reference/reference/build.md)
+* [help](/reference/help.md)
+* [kill](/reference/kill.md)          
+* [ps](/reference/ps.md)
+* [restart](/reference/restart.md)
+* [run](/reference/run.md)
+* [start](/reference/start.md)
+* [up](/reference/up.md)
+* [logs](/reference/logs.md)
+* [port](/reference/port.md)
+* [pull](/reference/pull.md) 
+* [rm](/reference/rm.md)
+* [scale](/reference/scale.md)
+* [stop](/reference/stop.md)

docs/reference/kill.md

@@ -0,0 +1,23 @@
+<!--[metadata]>
++++
+title = "kill"
+description = "Forces running containers to stop."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  kill"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# kill
+
+```
+Usage: kill [options] [SERVICE...]
+
+Options:
+-s SIGNAL         SIGNAL to send to the container. Default signal is SIGKILL.
+```
+
+Forces running containers to stop by sending a `SIGKILL` signal. Optionally the
+signal can be passed, for example:
+
+    $ docker-compose kill -s SIGINT

docs/reference/logs.md

@@ -0,0 +1,20 @@
+<!--[metadata]>
++++
+title = "logs"
+description = "Displays log output from services."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  logs"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# logs
+
+```
+Usage: logs [options] [SERVICE...]
+
+Options:
+--no-color  Produce monochrome output.
+```
+
+Displays log output from services.

docs/reference/overview.md

@@ -0,0 +1,68 @@
+<!--[metadata]>
++++
+title = "Introduction to the CLI"
+description = "Introduction to the CLI"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+parent = "smn_compose_cli"
+weight=-2	
++++
+<![end-metadata]-->
+
+
+# Introduction to the CLI
+
+This section describes the subcommands you can use with the `docker-compose` command.  You can run subcommand against one or more services. To run against a specific service, you supply the service name from your compose configuration. If you do not specify the service name, the command runs against all the services in your configuration.
+
+## Environment Variables
+
+Several environment variables are available for you to configure the Docker Compose command-line behaviour.
+
+Variables starting with `DOCKER_` are the same as those used to configure the
+Docker command-line client. If you're using `docker-machine`, then the `eval "$(docker-machine env my-docker-vm)"` command should set them to their correct values. (In this example, `my-docker-vm` is the name of a machine you created.)
+
+### COMPOSE\_PROJECT\_NAME
+
+Sets the project name. This value is prepended along with the service name to the container container on start up. For example, if you project name is `myapp` and it includes two services `db` and `web` then compose starts containers named  `myapp_db_1` and `myapp_web_1` respectively.
+
+Setting this is optional. If you do not set this, the `COMPOSE_PROJECT_NAME` defaults to the `basename` of the current working directory.
+
+### COMPOSE\_FILE
+
+Specify the file containing the compose configuration. If not provided, Compose looks for a file named  `docker-compose.yml` in the current directory and then each parent directory in succession until a file by that name is found.
+
+### DOCKER\_HOST
+
+Sets the URL of the `docker` daemon. As with the Docker client, defaults to `unix:///var/run/docker.sock`.
+
+### DOCKER\_TLS\_VERIFY
+
+When set to anything other than an empty string, enables TLS communication with
+the `docker` daemon.
+
+### DOCKER\_CERT\_PATH
+
+Configures the path to the `ca.pem`, `cert.pem`, and `key.pem` files used for TLS verification. Defaults to `~/.docker`.
+
+### COMPOSE\_MAX\_WORKERS
+
+Configures the maximum number of worker threads to be used when executing
+commands in parallel. Only a subset of commands execute in parallel, `stop`,
+`kill` and `rm`.
+
+
+
+
+
+
+
+## Compose documentation
+
+- [User guide](/)
+- [Installing Compose](install.md)
+- [Get started with Django](django.md)
+- [Get started with Rails](rails.md)
+- [Get started with Wordpress](wordpress.md)
+- [Yaml file reference](yml.md)
+- [Compose environment variables](env.md)
+- [Compose command line completion](completion.md)

docs/reference/port.md

@@ -0,0 +1,22 @@
+<!--[metadata]>
++++
+title = "port"
+description = "Prints the public port for a port binding.s"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  port"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# port
+
+```
+Usage: port [options] SERVICE PRIVATE_PORT
+
+Options:
+--protocol=proto  tcp or udp [default: tcp]
+--index=index     index of the container if there are multiple
+                  instances of a service [default: 1]
+```
+
+Prints the public port for a port binding.

docs/reference/ps.md

@@ -0,0 +1,20 @@
+<!--[metadata]>
++++
+title = "ps"
+description = "Lists containers."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  ps"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# ps
+
+```
+Usage: ps [options] [SERVICE...]
+
+Options:
+-q    Only display IDs
+```
+
+Lists containers.

docs/reference/pull.md

@@ -0,0 +1,20 @@
+<!--[metadata]>
++++
+title = "pull"
+description = "Pulls service images."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  pull"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# pull
+
+```
+Usage: pull [options] [SERVICE...]
+
+Options:
+--allow-insecure-ssl    Allow insecure connections to the docker registry
+```
+
+Pulls service images.

docs/reference/restart.md

@@ -0,0 +1,20 @@
+<!--[metadata]>
++++
+title = "restart"
+description = "Restarts Docker Compose services."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  restart"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# restart
+
+```
+Usage: restart [options] [SERVICE...]
+
+Options:
+-t, --timeout TIMEOUT      Specify a shutdown timeout in seconds. (default: 10)
+```
+
+Restarts services.

docs/reference/rm.md

@@ -0,0 +1,21 @@
+<!--[metadata]>
++++
+title = "rm"
+description = "Removes stopped service containers."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  rm"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# rm
+
+```
+Usage: rm [options] [SERVICE...]
+
+Options:
+-f, --force   Don't ask to confirm removal
+-v            Remove volumes associated with containers
+```
+
+Removes stopped service containers.

docs/reference/run.md

@@ -0,0 +1,54 @@
+<!--[metadata]>
++++
+title = "run"
+description = "Runs a one-off command on a service."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  run"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# run
+
+```
+Usage: run [options] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]
+
+Options:
+--allow-insecure-ssl  Allow insecure connections to the docker
+                          registry
+-d                    Detached mode: Run container in the background, print
+                          new container name.
+--entrypoint CMD      Override the entrypoint of the image.
+-e KEY=VAL            Set an environment variable (can be used multiple times)
+-u, --user=""         Run as specified username or uid
+--no-deps             Don't start linked services.
+--rm                  Remove container after run. Ignored in detached mode.
+--service-ports       Run command with the service's ports enabled and mapped to the host.
+-T                    Disable pseudo-tty allocation. By default `docker-compose run` allocates a TTY.
+```
+
+Runs a one-time command against a service. For example, the following command starts the `web` service and runs `bash` as its command. 
+
+    $ docker-compose run web bash
+
+Commands you use with `run` start in new containers with the same configuration as defined by the service' configuration. This means the container has the same volumes, links, as defined in the configuration file. There two differences though.
+
+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 the `docker-compose run` command does not create any of the ports specified in the service configuration. This prevents the port collisions with already open ports. If you *do want* the service's ports created and mapped to the host, specify the `--service-ports` flag:
+
+    $ docker-compose run --service-ports 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.  So, for example, you could run:
+
+    $ docker-compose run db psql -h db -U docker
+
+This would open up an interactive PostgreSQL shell for the linked `db` container.
+
+If you do not want the `run` command to start linked containers, specify the `--no-deps` flag:
+
+    $ docker-compose run --no-deps web python manage.py shell
+
+
+
+

docs/reference/scale.md

@@ -0,0 +1,21 @@
+<!--[metadata]>
++++
+title = "scale"
+description = "Sets the number of containers to run for a service."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  scale"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# scale
+
+```
+Usage: scale [SERVICE=NUM...]
+```
+
+Sets the number of containers to run for a service.
+
+Numbers are specified as arguments in the form `service=num`. For example:
+
+    $ docker-compose scale web=2 worker=3

docs/reference/start.md

@@ -0,0 +1,17 @@
+<!--[metadata]>
++++
+title = "start"
+description = "Starts existing containers for a service."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  start"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# start
+
+```
+Usage: start [SERVICE...]
+```
+
+Starts existing containers for a service.

docs/reference/stop.md

@@ -0,0 +1,21 @@
+<!--[metadata]>
++++
+title = "stop"
+description = "Stops running containers without removing them. "
+keywords = ["fig, composition, compose, docker, orchestration, cli, stop"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# stop
+
+```
+Usage: stop [options] [SERVICE...]
+
+Options:
+-t, --timeout TIMEOUT      Specify a shutdown timeout in seconds (default: 10).
+```
+
+Stops running containers without removing them. They can be started again with
+`docker-compose start`.

docs/reference/up.md

@@ -0,0 +1,42 @@
+<!--[metadata]>
++++
+title = "up"
+description = "Builds, (re)creates, starts, and attaches to containers for a service."
+keywords = ["fig, composition, compose, docker, orchestration, cli,  up"]
+[menu.main]
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# up
+
+```
+Usage: up [options] [SERVICE...]
+
+Options:
+--allow-insecure-ssl   Allow insecure connections to the docker
+                       registry
+-d                     Detached mode: Run containers in the background,
+                       print new container names.
+--no-color             Produce monochrome output.
+--no-deps              Don't start linked services.
+--x-smart-recreate     Only recreate containers whose configuration or
+                       image needs to be updated. (EXPERIMENTAL)
+--no-recreate          If containers already exist, don't recreate them.
+--no-build             Don't build an image, even if it's missing
+-t, --timeout TIMEOUT  Use this timeout in seconds for container shutdown
+                       when attached or when containers are already
+                       running. (default: 10)
+```
+
+Builds, (re)creates, starts, and attaches to containers for a service.
+
+Linked services will be started, unless they are already running.
+
+By default, `docker-compose up` will aggregate the output of each container and,
+when it exits, all containers will be stopped. Running `docker-compose up -d`,
+will start the containers in the background and leave them running.
+
+By default, if there are existing containers for a service, `docker-compose up` will stop and recreate them (preserving mounted volumes with [volumes-from]), so that changes in `docker-compose.yml` are picked up. If you do not want containers stopped and recreated, use `docker-compose up --no-recreate`. This will still start any stopped containers, if needed.
+
+[volumes-from]: http://docs.docker.io/en/latest/use/working_with_volumes/