YAML文件参考

compose文件格式为.yaml,默认文件名为docker-compose.yml。

services配置参考

注意：compose文件有两个版本：version 1和version 2。关于版本1和版本2的区别请参考Versioning章节。

image

指定为镜像名称或镜像 ID。如果镜像在本地不存在，Compose 将会尝试拉取这个镜像,除非你同时指定了build。例如：

image: ubuntu:14.04

注意：在版本1中，使用同时使用build和image将会出错

build

指定Dockerfile所在文件夹的路径。Compose将会利用它自动构建这个镜像，然后使用这个镜像。

build: /path/to/build/dir

command

覆盖容器启动后默认执行的命令。

command: bundle exec thin -p 3000

亦可像dockerfile一样，写成列表的形式：

command: [bundle, exec, thin, -p, 3000]

container_name

指定容器的名称，若不指定将会为容器生成一个默认名称。容器名称必须唯一，否则出错。

container_name: my-web-container

depends_on

两个容器之间的依赖：

docker-compose up将会按照依赖关系启动容器。在下面的例子中，db和redis将先于web启动。
docker-compose up SERVICE将会自动启动容器所依赖的容器。下面的例子中，使用docker-compose up web启动web容器时，将会创建和启动db和redis。
```
version: '2'
services:
web:
  build: .
  depends_on:
    - db
    - redis
redis:
  image: redis
db:
  image: postgres
```

entrypoint

覆盖默认的entrypoint。

entrypoint: /code/entrypoint.sh

亦可像dockerfile一样，将entrypoint写为列表的形式:

entrypoint:
    - php
    - -d
    - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
    - -d
    - memory_limit=-1
    - vendor/bin/phpunit

env_file

从文件中获取环境变量，可以为单独的文件路径或是文件路径列表。

如果通过docker-compose -f FILE指定了模板文件，则env_file中路径会基于模板文件路径。

如果有变量名称与environment指令冲突，environment指令会覆盖该变量，即以environment指令为准。

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/secrets.env

环境变量文件中每一行必须符合格式，支持 # 开头的注释行。

# Set Rails/Rack environment
RACK_ENV=development

environment

设置环境变量。你可以使用数组或字典两种格式。

任何布尔值：true、false、yes、no，需要用引号（''）括起来，因为YML解析器会将其转化为True或False。

只给定名称的变量会自动获取它在 Compose 主机上的值，可以用来防止泄露不必要的数据。

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

environment:
  - RACK_ENV=development
  - SHOW=true
  - SESSION_SECRET

expose

暴露端口，但不映射到宿主机，只被连接的容器访问。

仅可以指定内部端口为参数

expose:
 - "3000"
 - "8000"

labels

注：常用

为容器增加元数据(metadata)，可使用数组或字典的形式。

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

net

只支持版本1，版本2中使用network_mode

网络模式，与docker run命令中--net参数一致。container:...形式能够使用服务的名称代替容器的名称或id。

net: "bridge"
net: "host"
net: "none"
net: "container:[service name or container name/id]"

network_mode

只支持版本2，版本1中使用net

网络模式，与docker run命令中--net参数一致,增加了特定的形式：service:[service name]。

network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"

networks

只支持版本2，版本1中使用net

网络连接。参考网络配置参考

services:
  some-service:
    networks:
     - some-network
     - other-network

aliases

服务在网络上的别名（代替主机名）。在同一个网络上的其他容器能够使用服务名或者是这个别名去连接这个服务中的容器。

因为别名是网络范围的，相同的服务在不同的网络中可以有不同的别名。

注意：一个网络范围的别名能够通过多个容器甚至是多个服务共享。如果是的话，那么它的名字将是什么名字就无法保证。

一般的形式如下：

services:
  some-service:
    networks:
      some-network:
        aliases:
         - alias1
         - alias3
      other-network:
        aliases:
         - alias2

在下面的例子中，提供了三个服务（web、worker和db）以及两个网络（new和legacy）。

version: '2'

services:
  web:
    build: ./web
    networks:
      - new

  worker:
    build: ./worker
    networks:
    - legacy

  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

ipv4_address, ipv6_address

当服务加入网络时，为容器指定静态IP地址。

networks章节中需要有相应的网络配置：必须含有ipam，并且子网和网关配置正确。如果要配置IPv6地址，com.docker.network.enable_ipv6驱动选项必须配置为true。一个例子：

version: '2'

services:
  app:
    image: busybox
    command: ifconfig
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    driver: bridge
    driver_opts:
      com.docker.network.enable_ipv6: "true"
    ipam:
      driver: default
      config:
      - subnet: 172.16.238.0/24
        gateway: 172.16.238.1
      - subnet: 2001:3984:3989::/64
        gateway: 2001:3984:3989::1

ports

暴露端口信息。使用[宿主：容器]HOST:CONTAINER格式或者仅仅指定容器的端口（宿主将会随机选择端口）都可以。

注意：建议定义端口映射时使用""形式

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"

volumes

卷挂载路径设置。可以设置宿主机路径（HOST:CONTAINER）或加上访问模式（HOST:CONTAINER:ro）。

volumes:
  # Just specify a path and let the Engine create a volume
  - /var/lib/mysql

  # Specify an absolute path mapping
  - /opt/data:/var/lib/mysql

  # Path on the host, relative to the Compose file
  - ./cache:/tmp/cache

  # User-relative path
  - ~/configs:/etc/configs/:ro

  # Named volume
  - datavolume:/var/lib/mysql

volumes_from

从另一个服务或容器挂载它的所有卷。ro指定只读，rw指定读写，默认为rw。

volumes_from:
 - service_name
 - service_name:ro
 - container:container_name
 - container:container_name:rw

注意：container:...形式只在版本2中支持，版本1中直接写容器名称不需要container:标签，如下：

- service_name
- service_name:ro
- container_name
- container_name:rw

cap_add,capdrop

增加或删除容器的能力。例如：

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

说明：cap-add: -ALL将为容器增加所有的功能。cap_drop: - NET_ADMIN - SYS_ADMIN将删除容器的网络和系统能力。

cgroup_parent

为容器指定一个可选的父cgroup。

cgroup_parent: m-executor-abcd

devices

设备映射列表。等同于使用docker run命令创建容器时的--device选项。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

dns

自定义DNS服务。可以是一个或是列表。

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_search

自定义DNS服务查询域。可以是一个或是列表。

dns_search: example.com
dns_search:
  - dc1.example.com
  - dc2.example.com

tmpfs

在容器中挂在临时的文件系统。可以是一个或是列表。

tmpfs: /run
tmpfs:
  - /run
  - /tmp

extends

基于已有的服务进行扩展，可以是当前文件也可以是其他文件。

例如我们已经有了一个webapp服务，模板文件为common.yml。

# common.yml
webapp:
  build: ./webapp
  environment:
    - DEBUG=false
    - SEND_EMAILS=false

编写一个新的development.yml文件，使用common.yml中的webapp服务进行扩展。

# development.yml
web:
  extends:
    file: common.yml
    service: webapp
  ports:
    - "8000:8000"
  links:
    - db
  environment:
    - DEBUG=true
db:
  image: postgres

后者会自动继承common.yml中的webapp服务及相关环境变量。

external_links

链接到docker-compose.yml外部的容器，甚至并非Compose管理的容器。参数格式跟links类似。

external_links:
 - redis_1
 - project_db_1:mysql
 - project_db_1:postgresql

extra_hosts

增加主机名映射。与docker run命令参数--add-host一致。

extra_hosts:
 - "somehost:162.242.195.82"
 - "otherhost:50.31.209.229"

在容器的/etc/hosts文件里，会创建完整的ip地址和主机名：

162.242.195.82  somehost
50.31.209.229   otherhost

links

链接到其它服务中的容器。使用[服务名称]（同时作为别名）或[服务名称：服务别名]（SERVICE:ALIAS）格式都可以。

web:
  links:
   - db
   - db:database
   - redis

Links同时也表达了服务奖的依赖关系（就像 depends_on定义的那样），所以服务的启动顺序已经被确定了。

logging

只支持版本2，在版本1中使用log_driver和log_opt

为服务配置logging。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver:为服务的容器定义了logging驱动的名称，与docker run中--log-driver参数一致。

默认的值是json-file

driver: "json-file"
driver: "syslog"
driver: "none"

注意：只有json-file驱动，在docker-compose up和docker-compose logs中能够直接获取。使用其他的驱动将不会打印任何日志。

使用关键字options定义logging选项，与docker run中--log-opt参数一致。

options是一个键值对key: value，例如：

driver: "syslog"
options:
  syslog-address: "tcp://192.168.0.42:123"

log_driver

只支持版本1，版本2中使用logging

定义日志驱动，默认是json-file。

log_driver: syslog

log_opt

只支持版本1，版本2中使用logging

用键值对key: value形式定义日志的选项，一个syslog选项的例子如下：

log_opt:
  syslog-address: "tcp://192.168.0.42:123"

pid

跟主机系统共享进程命名空间。打开该选项的容器可以相互通过进程 ID 来访问和操作。

pid: "host"

security_opt

为每个容器重写默认的标签方案。

security_opt:
  - label:user:USER
  - label:role:ROLE

stop_signal

设置停止容器的信号。默认停止使用SIGTERM。

stop_signal: SIGUSR1

ulimits

重写容器的默认ulimits。

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

cpu_shares, cpu_quota, cpuset, domainname, hostname, ipc, mac_address, mem_limit, memswap_limit, privileged, read_only, restart, shm_size, stdin_open, tty, user, working_dir

cpu_shares: 73
cpu_quota: 50000
cpuset: 0,1

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000
memswap_limit: 2000000000
privileged: true

restart: always

read_only: true
shm_size: 64M
stdin_open: true
tty: true

网络配置参考

顶级（即与services关键字处于同一级别）networks关键字可以创建自定义网络。

driver

指定网络使用的驱动。默认的驱动取决于Docker引擎的配置，在单主机上，大都是bridge，在Swarm上，一般是overlay。

如果驱动无法获取，Docker引擎将会返回一个错误。

driver: overlay

driver_opts

为网络指定一系列的可选项，使用键值对的形式。这些选项是依赖驱动的，可参阅驱动文档获取更多信息。可选的。

driver_opts:
    foo: "bar"
    baz: 1

ipam

指定自定义IPAM配置。包含若干属性，每个属性都是可选的：

driver：自定义IPAM驱动，代替默认值。
config：带有零个或多个配置块的列表，每个配置块可包含如下关键字：
- subnet：网段的子网，采用CIDR的形式
- ip_range：容器IP范围
- gateway：IPV4或IPV6网关
- aux_addresses：网络驱动的附加IPV4或IPV6地址，作为主机名和IP的映射

一个完整的例子如下：

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7

external

如果设置external为true,表示该网络时在在Compose外面创建的。docker-compose up将不会创建该网络，如果该网络不存在将会出错。

关键字external不能与其他的网络配置关键字同时使用（driver、driver_opt、ipam）。

下面的例子中，proxy是与外界的网关。Compose将会在已存在的网络中查找outside，并将proxy服务的容器和该网络连接。

version: '2'

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

可将Compose file中使用的网络名与实际网络名分开指定：

networks:
  outside:
    external:
      name: actual-name-of-network

变量替代

Compose文件中配置项里可以包含环境变量的值。Compose可以只用运行docker-compose主机上的sHell环境变量值。比如，shell中含有环境变量EXTERNAL_PORT=8000，在compose文件中可这样使用：

web:
  build: .
  ports:
    - "${EXTERNAL_PORT}:5000"

运行docker-compose后，Compose在shell中查找EXTERNAL_PORT环境变量，并用其值进行替换。本例中，在创建web容器前，将会使用端口映射8000:5000。

若shell中没有设置该环境变量，Compose将会使用空字符串替代。

支持$VARIABLE和${VARIABLE}两种形式的变量。

若果配置中需要使用$符号，请使用$$。