Merge pull request #2066 from mnowster/reorder-reference-docs

Reorder reference docs

docs/yml.md

@@ -19,22 +19,6 @@ As with `docker run`, options specified in the Dockerfile (e.g., `CMD`,
 `EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to
 specify them again in `docker-compose.yml`.
 
-Values for configuration options can contain environment variables, e.g.
-`image: postgres:${POSTGRES_VERSION}`. For more details, see the section on
-[variable substitution](#variable-substitution).
-
-### image
-
-Tag, partial image ID or digest. Can be local or remote - Compose will attempt to
-pull if it doesn't exist locally.
-
-    image: ubuntu
-    image: orchardup/postgresql
-    image: a4bc65fd
-    image: busybox@sha256:38a203e1986cf79639cfb9b2e1d6e773de84002feea2d4eb006b52004ee8502d
-
-Using `image` together with either `build`  or `dockerfile` is not allowed. Attempting to do so results in an error.
-
 ### build
 
 Path to a directory containing a Dockerfile. When the value supplied is a
@@ -47,13 +31,17 @@ Compose will build and tag it with a generated name, and use that image thereaft
 
 Using `build` together with `image` is not allowed. Attempting to do so results in an error.
 
-### dockerfile
+### cap_add, cap_drop
 
-Alternate Dockerfile.
+Add or drop container capabilities.
+See `man 7 capabilities` for a full list.
 
-Compose will use an alternate file to build with.
+    cap_add:
+      - ALL
 
-    dockerfile: Dockerfile-alternate
+    cap_drop:
+      - NET_ADMIN
+      - SYS_ADMIN
 
 Using `dockerfile` together with `image` is not allowed. Attempting to do so results in an error.
 
@@ -63,124 +51,71 @@ Override the default command.
 
     command: bundle exec thin -p 3000
 
-<a name="links"></a>
-### links
-
-Link to containers in another service. Either specify both the service name and
-the link alias (`SERVICE:ALIAS`), or just the service name (which will also be
-used for the alias).
-
-    links:
-     - db
-     - db:database
-     - redis
-
-An entry with the alias' name will be created in `/etc/hosts` inside containers
-for this service, e.g:
-
-    172.17.2.186  db
-    172.17.2.186  database
-    172.17.2.187  redis
-
-Environment variables will also be created - see the [environment variable
-reference](env.md) for details.
-
-### external_links
-
-Link to containers started outside this `docker-compose.yml` or even outside
-of Compose, especially for containers that provide shared or common services.
-`external_links` follow semantics similar to `links` when specifying both the
-container name and the link alias (`CONTAINER:ALIAS`).
-
-    external_links:
-     - redis_1
-     - project_db_1:mysql
-     - project_db_1:postgresql
-
-### extra_hosts
+### container_name
 
-Add hostname mappings. Use the same values as the docker client `--add-host` parameter.
+Specify a custom container name, rather than a generated default name.
 
-    extra_hosts:
-     - "somehost:162.242.195.82"
-     - "otherhost:50.31.209.229"
+    container_name: my-web-container
 
-An entry with the ip address and hostname will be created in `/etc/hosts` inside containers for this service, e.g:
+Because Docker container names must be unique, you cannot scale a service
+beyond 1 container if you have specified a custom name. Attempting to do so
+results in an error.
 
-    162.242.195.82  somehost
-    50.31.209.229   otherhost
+### devices
 
-### ports
+List of device mappings.  Uses the same format as the `--device` docker
+client create option.
 
-Makes an exposed port accessible on a host and the port is available to
-any client that can reach that host. Docker binds the exposed port to a random
-port on the host within an *ephemeral port range* defined by
-`/proc/sys/net/ipv4/ip_local_port_range`. You can also map to a specific port or range of ports.
+    devices:
+      - "/dev/ttyUSB0:/dev/ttyUSB0"
 
-Acceptable formats for the `ports` value are:
+### dns
 
-* `containerPort`
-* `ip:hostPort:containerPort`
-* `ip::containerPort`
-* `hostPort:containerPort`
+Custom DNS servers. Can be a single value or a list.
 
-You can specify a range for both the `hostPort` and the `containerPort` values.
-When specifying ranges, the container port values in the range must match the
-number of host port values in the range, for example,
-`1234-1236:1234-1236/tcp`. Once a host is running, use the 'docker-compose port' command
-to see the actual mapping.
+    dns: 8.8.8.8
+    dns:
+      - 8.8.8.8
+      - 9.9.9.9
 
-The following configuration shows examples of the port formats in use:
+### dns_search
 
-    ports:
-     - "3000"
-     - "3000-3005"
-     - "8000:8000"
-     - "9090-9091:8080-8081"
-     - "49100:22"
-     - "127.0.0.1:8001:8001"
-     - "127.0.0.1:5000-5010:5000-5010"
+Custom DNS search domains. Can be a single value or a list.
 
+    dns_search: example.com
+    dns_search:
+      - dc1.example.com
+      - dc2.example.com
 
-When mapping ports, in the `hostPort:containerPort` format, you may
-experience erroneous results when using a container port lower than 60. This
-happens because YAML parses numbers in the format `xx:yy` as sexagesimal (base
-60). To avoid this problem, always explicitly specify your port
-mappings as strings.
+### dockerfile
 
-### expose
+Alternate Dockerfile.
 
-Expose ports without publishing them to the host machine - they'll only be
-accessible to linked services. Only the internal port can be specified.
+Compose will use an alternate file to build with.
 
-    expose:
-     - "3000"
-     - "8000"
+    dockerfile: Dockerfile-alternate
 
-### volumes
+### env_file
 
-Mount paths as volumes, optionally specifying a path on the host machine
-(`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
+Add environment variables from a file. Can be a single value or a list.
 
-    volumes:
-     - /var/lib/mysql
-     - ./cache:/tmp/cache
-     - ~/configs:/etc/configs/:ro
+If you have specified a Compose file with `docker-compose -f FILE`, paths in
+`env_file` are relative to the directory that file is in.
 
-You can mount a relative path on the host, which will expand relative to
-the directory of the Compose configuration file being used. Relative paths
-should always begin with `.` or `..`.
+Environment variables specified in `environment` override these values.
 
-> Note: No path expansion will be done if you have also specified a
-> `volume_driver`.
+    env_file: .env
 
-### volumes_from
+    env_file:
+      - ./common.env
+      - ./apps/web.env
+      - /opt/secrets.env
 
-Mount all of the volumes from another service or container.
+Compose expects each line in an env file to be in `VAR=VAL` format. Lines
+beginning with `#` (i.e. comments) are ignored, as are blank lines.
 
-    volumes_from:
-     - service_name
-     - container_name
+    # Set Rails/Rack environment
+    RACK_ENV=development
 
 ### environment
 
@@ -201,27 +136,14 @@ machine Compose is running on, which can be helpful for secret or host-specific
       - SHOW=true
       - SESSION_SECRET
 
-### env_file
-
-Add environment variables from a file. Can be a single value or a list.
-
-If you have specified a Compose file with `docker-compose -f FILE`, paths in
-`env_file` are relative to the directory that file is in.
-
-Environment variables specified in `environment` override these values.
-
-    env_file: .env
-
-    env_file:
-      - ./common.env
-      - ./apps/web.env
-      - /opt/secrets.env
+### expose
 
-Compose expects each line in an env file to be in `VAR=VAL` format. Lines
-beginning with `#` (i.e. comments) are ignored, as are blank lines.
+Expose ports without publishing them to the host machine - they'll only be
+accessible to linked services. Only the internal port can be specified.
 
-    # Set Rails/Rack environment
-    RACK_ENV=development
+    expose:
+     - "3000"
+     - "8000"
 
 ### extends
 
@@ -267,6 +189,40 @@ service within the current file.
 For more on `extends`, see the [tutorial](extends.md#example) and
 [reference](extends.md#reference).
 
+### external_links
+
+Link to containers started outside this `docker-compose.yml` or even outside
+of Compose, especially for containers that provide shared or common services.
+`external_links` follow semantics similar to `links` when specifying both the
+container name and the link alias (`CONTAINER:ALIAS`).
+
+    external_links:
+     - redis_1
+     - project_db_1:mysql
+     - project_db_1:postgresql
+
+### extra_hosts
+
+Add hostname mappings. Use the same values as the docker client `--add-host` parameter.
+
+    extra_hosts:
+     - "somehost:162.242.195.82"
+     - "otherhost:50.31.209.229"
+
+An entry with the ip address and hostname will be created in `/etc/hosts` inside containers for this service, e.g:
+
+    162.242.195.82  somehost
+    50.31.209.229   otherhost
+
+### image
+
+Tag or partial image ID. Can be local or remote - Compose will attempt to
+pull if it doesn't exist locally.
+
+    image: ubuntu
+    image: orchardup/postgresql
+    image: a4bc65fd
+
 ### labels
 
 Add metadata to containers using [Docker labels](http://docs.docker.com/userguide/labels-custom-metadata/). You can use either an array or a dictionary.
@@ -283,15 +239,26 @@ It's recommended that you use reverse-DNS notation to prevent your labels from c
       - "com.example.department=Finance"
       - "com.example.label-with-empty-value"
 
-### container_name
+### links
 
-Specify a custom container name, rather than a generated default name.
+Link to containers in another service. Either specify both the service name and
+the link alias (`SERVICE:ALIAS`), or just the service name (which will also be
+used for the alias).
 
-    container_name: my-web-container
+    links:
+     - db
+     - db:database
+     - redis
 
-Because Docker container names must be unique, you cannot scale a service
-beyond 1 container if you have specified a custom name. Attempting to do so
-results in an error.
+An entry with the alias' name will be created in `/etc/hosts` inside containers
+for this service, e.g:
+
+    172.17.2.186  db
+    172.17.2.186  database
+    172.17.2.187  redis
+
+Environment variables will also be created - see the [environment variable
+reference](env.md) for details.
 
 ### log_driver
 
@@ -336,53 +303,56 @@ container and the host operating system the PID address space.  Containers
 launched with this flag will be able to access and manipulate other
 containers in the bare-metal machine's namespace and vise-versa.
 
-### dns
-
-Custom DNS servers. Can be a single value or a list.
+### ports
 
-    dns: 8.8.8.8
-    dns:
-      - 8.8.8.8
-      - 9.9.9.9
+Expose ports. Either specify both ports (`HOST:CONTAINER`), or just the container
+port (a random host port will be chosen).
 
-### cap_add, cap_drop
+> **Note:** When mapping ports in the `HOST:CONTAINER` format, you may experience
+> erroneous results when using a container port lower than 60, because YAML will
+> parse numbers in the format `xx:yy` as sexagesimal (base 60). For this reason,
+> we recommend always explicitly specifying your port mappings as strings.
 
-Add or drop container capabilities.
-See `man 7 capabilities` for a full list.
+    ports:
+     - "3000"
+     - "8000:8000"
+     - "49100:22"
+     - "127.0.0.1:8001:8001"
 
-    cap_add:
-      - ALL
+### security_opt
 
-    cap_drop:
-      - NET_ADMIN
-      - SYS_ADMIN
+Override the default labeling scheme for each container.
 
-### dns_search
+      security_opt:
+        - label:user:USER
+        - label:role:ROLE
 
-Custom DNS search domains. Can be a single value or a list.
+### volumes
 
-    dns_search: example.com
-    dns_search:
-      - dc1.example.com
-      - dc2.example.com
+Mount paths as volumes, optionally specifying a path on the host machine
+(`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
 
-### devices
+    volumes:
+     - /var/lib/mysql
+     - ./cache:/tmp/cache
+     - ~/configs:/etc/configs/:ro
 
-List of device mappings.  Uses the same format as the `--device` docker
-client create option.
+You can mount a relative path on the host, which will expand relative to
+the directory of the Compose configuration file being used. Relative paths
+should always begin with `.` or `..`.
 
-    devices:
-      - "/dev/ttyUSB0:/dev/ttyUSB0"
+> Note: No path expansion will be done if you have also specified a
+> `volume_driver`.
 
-### security_opt
+### volumes_from
 
-Override the default labeling scheme for each container.
+Mount all of the volumes from another service or container.
 
-      security_opt:
-        - label:user:USER
-        - label:role:ROLE
+    volumes_from:
+     - service_name
+     - container_name
 
-### working\_dir, entrypoint, user, hostname, domainname, mac\_address, mem\_limit, memswap\_limit, privileged, ipc, restart, stdin\_open, tty, cpu\_shares, cpuset, read\_only, volume\_driver
+### cpu\_shares, cpuset, domainname, entrypoint, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, privileged, read\_only, restart, stdin\_open, tty, user, volume\_driver, working\_dir
 
 Each of these is a single value, analogous to its
 [docker run](https://docs.docker.com/reference/run/) counterpart.
@@ -390,26 +360,24 @@ Each of these is a single value, analogous to its
     cpu_shares: 73
     cpuset: 0,1
 
-    working_dir: /code
     entrypoint: /code/entrypoint.sh
     user: postgresql
+    working_dir: /code
 
-    hostname: foo
     domainname: foo.com
-
+    hostname: foo
+    ipc: host
     mac_address: 02:42:ac:11:65:43
 
     mem_limit: 1000000000
     memswap_limit: 2000000000
     privileged: true
 
-    ipc: host
-
     restart: always
 
+    read_only: true
     stdin_open: true
     tty: true
-    read_only: true
 
     volume_driver: mydriver