Merge pull request #1416 from docker/docs

reference documentation

Author: gtardif

docs/reference/compose.md

@@ -0,0 +1,99 @@
+
+
+## Description
+
+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:
+
+```
+$ 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: 
+```
+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.
+
+```
+$ 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

docs/reference/compose_convert.md

@@ -0,0 +1,9 @@
+
+
+## Description
+
+`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,
+it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into 
+fully defined Compose model. 
+
+To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`

docs/reference/compose_down.md

@@ -0,0 +1,17 @@
+
+
+## Description
+
+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 will not be automatically
+mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
+named volumes.

docs/reference/compose_events.md

@@ -0,0 +1,22 @@
+
+## Description
+
+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](/engine/reference/commandline/events/#object-types).

docs/reference/compose_exec.md

@@ -0,0 +1,7 @@
+
+## Description
+
+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.

docs/reference/compose_kill.md

@@ -0,0 +1,8 @@
+
+## Description
+
+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/compose_logs.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Displays log output from services.

docs/reference/compose_ls.md

@@ -0,0 +1,4 @@
+
+## Description
+
+List Compose projects running on platform.

docs/reference/compose_pause.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Pauses running containers of a service. They can be unpaused with `docker compose unpause`.

docs/reference/compose_ps.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Lists containers for a Compose project.