docker-compose

介紹

 

Compose 項目是 Docker 官方的開源項目，負責實現對 Docker 容器集群的快速編排。從功能上看，跟 OpenStack 中的 Heat 十分類似。其代碼目前在 https://github.com/docker/compose 上開源。

 

Compose 定位是 「定義和運行多個 Docker 容器的應用（Defining and running multi-container Docker applications）」，其前身是開源項目 Fig。

 

Compose允許用戶通過一個單獨的 docker-compose.yml 模板文件（YAML 格式）來定義一組相關聯的應用容器為一個項目（project）。

Compose 中有兩個重要的概念：

• 服務 (service)：一個應用的容器，實際上可以包括若干運行相同鏡像的容器實例。

• 項目 (project)：由一組關聯的應用容器組成的一個完整業務單元，在 docker-compose.yml 文件中定義。

Compose 的默認管理對象是項目，通過子命令對項目中的一組容器進行便捷地生命周期管理。

Compose 項目由 Python 編寫，實現上調用了 Docker 服務提供的 API 來對容器進行管理。因此，只要所操作的平台支持 Docker API，就可以在其上利用 Compose 來進行編排管理。

 

安裝

Compose 可以通過 Python 的包管理工具 pip 進行安裝，也可以直接下載編譯好的二進制文件使用，甚至能夠直接在 Docker 容器中運行。

前兩種方式是傳統方式，適合本地環境下安裝使用；最后一種方式則不破壞系統環境，更適合雲計算場景。

Docker for Mac 、Docker for Windows 自帶 docker-compose 二進制文件，安裝 Docker 之后可以直接使用。

$ docker-compose --version

 

二進制包

$ sudo curl -L https://github.com/docker/compose/releases/download/1.17.1/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose

 

PIP 安裝

這種方式是將 Compose 當作一個 Python 應用來從 pip 源中安裝。

執行安裝命令：

$ sudo pip install -U docker-compose

 

可以看到類似如下輸出，說明安裝成功。

Collecting docker-compose
  Downloading docker-compose-1.17.1.tar.gz (149kB): 149kB downloaded
...
Successfully installed docker-compose cached-property requests texttable websocket-client docker-py dockerpty six enum34 backports.ssl-match-hostname ipaddress

 

bash 補全命令

$ curl -L https://raw.githubusercontent.com/docker/compose/1.8.0/contrib/completion/bash/docker-compose > /etc/bash_completion.d/docker-compose

 

容器中執行

$ curl -L https://github.com/docker/compose/releases/download/1.8.0/run.sh > /usr/local/bin/docker-compose
$ chmod +x /usr/local/bin/docker-compose

 

卸載

如果是二進制包方式安裝的，刪除二進制文件即可。
$ sudo rm /usr/local/bin/docker-compose

如果是通過 pip 安裝的，則執行如下命令即可刪除。
$ sudo pip uninstall docker-compose

 

使用

首先介紹幾個術語。

• 服務 (service)：一個應用容器，實際上可以運行多個相同鏡像的實例。

• 項目 (project)：由一組關聯的應用容器組成的一個完整業務單元。

 

可見，一個項目可以由多個服務（容器）關聯而成，Compose 面向項目進行管理。

官網示例：

#新建文件夾，在該目錄中編寫 app.py 文件

from flask import Flask
from redis import Redis

app = Flask(__name__)
redis = Redis(host='redis', port=6379)

@app.route('/')
def hello():
    count = redis.incr('hits')
    return 'Hello World! 該頁面已被訪問 {} 次。\n'.format(count)

if __name__ == "__main__":
    app.run(host="0.0.0.0", debug=True)


Dockerfile

#編寫 Dockerfile 文件，內容為

FROM python:3.6-alpine
ADD . /code
WORKDIR /code
RUN pip install redis flask
CMD ["python", "app.py"]


docker-compose.yml

#編寫 docker-compose.yml 文件，這個是 Compose 使用的主模板文件。

version: '3'
services:

  web:
    build: .
    ports:
     - "5000:5000"

  redis:
    image: "redis:alpine"

#運行 compose 項目

$ docker-compose up
此時訪問本地 5000 端口，每次刷新頁面，計數就會加 1

 

使用說明

執行 docker-compose [COMMAND] --help 或者 docker-compose help [COMMAND] 可以查看具體某個命令的使用格式。

docker-compose 命令的基本的使用格式是

docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]

 

命令選項

 

• -f, --file FILE 指定使用的 Compose 模板文件，默認為 docker-compose.yml，可以多次指定。

• -p, --project-name NAME 指定項目名稱，默認將使用所在目錄名稱作為項目名。

• --x-networking 使用 Docker 的可拔插網絡后端特性

• --x-network-driver DRIVER 指定網絡后端的驅動，默認為 bridge

• --verbose 輸出更多調試信息。

• -v, --version 打印版本並退出

 

命令使用說明

 

build

格式為：

docker-compose build [options] [SERVICE...]。

構建（重新構建）項目中的服務容器。

服務容器一旦構建后，將會帶上一個標記名，例如對於 web 項目中的一個 db 容器，可能是 web_db。

可以隨時在項目目錄下運行 docker-compose build 來重新構建服務。

選項包括：

• --force-rm 刪除構建過程中的臨時容器。

• --no-cache 構建鏡像過程中不使用 cache（這將加長構建過程）。

• --pull 始終嘗試通過 pull 來獲取更新版本的鏡像。

 

config

驗證 Compose 文件格式是否正確，若正確則顯示配置，若格式錯誤顯示錯誤原因。

 

down

此命令將會停止 up 命令所啟動的容器，並移除網絡

 

exec

進入指定的容器。

 

help

獲得一個命令的幫助。

 

images

列出 Compose 文件中包含的鏡像。

 

kill

通過發送 SIGKILL 信號來強制停止服務容器。格式為 

docker-compose kill [options] [SERVICE...]。

 

支持通過 -s 參數來指定發送的信號，例如通過如下指令發送 SIGINT 信號。

$ docker-compose kill -s SIGINT

 

logs

查看服務容器的輸出。格式為 

docker-compose logs [options] [SERVICE...]。

默認情況下，docker-compose 將對不同的服務輸出使用不同的顏色來區分。可以通過 --no-color 來關閉顏色。

該命令在調試問題的時候十分有用。

 

pause

暫停一個服務容器。格式為 

docker-compose pause [SERVICE...]

 

port

打印某個容器端口所映射的公共端口。格式為 

docker-compose port [options] SERVICE PRIVATE_PORT。

選項：

• --protocol=proto 指定端口協議，tcp（默認值）或者 udp。
• --index=index 如果同一服務存在多個容器，指定命令對象容器的序號（默認為 1）。

 

ps

列出項目中目前的所有容器，格式為 

docker-compose ps [options] [SERVICE...]。

選項：

• -q 只打印容器的 ID 信息。

 

pull

拉取服務依賴的鏡像。格式為 

docker-compose pull [options] [SERVICE...]。

選項：

• --ignore-pull-failures 忽略拉取鏡像過程中的錯誤。

 

push

推送服務依賴的鏡像到 Docker 鏡像倉庫。

 

restart

重啟項目中的服務。格式為 

docker-compose restart [options] [SERVICE...]。

選項：

• -t, --timeout TIMEOUT 指定重啟前停止容器的超時（默認為 10 秒）。

 

rm

刪除所有（停止狀態的）服務容器。格式為 

docker-compose rm [options] [SERVICE...]。

推薦先執行 docker-compose stop 命令來停止容器。

選項：

• -f, --force 強制直接刪除，包括非停止狀態的容器。一般盡量不要使用該選項。
• -v 刪除容器所掛載的數據卷。

 

run

在指定服務上執行一個命令。格式為 

docker-compose run [options] [-p PORT...] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]。

例如：

$ docker-compose run ubuntu ping docker.com

將會啟動一個 ubuntu 服務容器，並執行 ping docker.com 命令。

默認情況下，如果存在關聯，則所有關聯的服務將會自動被啟動，除非這些服務已經在運行中。

該命令類似啟動容器后運行指定的命令，相關卷、鏈接等等都將會按照配置自動創建。

兩個不同點：

• 給定命令將會覆蓋原有的自動運行命令；
• 不會自動創建端口，以避免沖突。

如果不希望自動啟動關聯的容器，可以使用 --no-deps 選項，例如

$ docker-compose run --no-deps web python manage.py shell

將不會啟動 web 容器所關聯的其它容器。

選項：

• -d 后台運行容器。
• --name NAME 為容器指定一個名字。
• --entrypoint CMD 覆蓋默認的容器啟動指令。
• -e KEY=VAL 設置環境變量值，可多次使用選項來設置多個環境變量。
• -u, --user="" 指定運行容器的用戶名或者 uid。
• --no-deps 不自動啟動關聯的服務容器。
• --rm 運行命令后自動刪除容器，d 模式下將忽略。
• -p, --publish=[] 映射容器端口到本地主機。
• --service-ports 配置服務端口並映射到本地主機。
• -T 不分配偽 tty，意味着依賴 tty 的指令將無法運行。

 

scale

設置指定服務運行的容器個數。格式為

docker-compose scale [options] [SERVICE=NUM...]。

通過 service=num 的參數來設置數量。例如：

$ docker-compose scale web=3 db=2

將啟動 3 個容器運行 web 服務，2 個容器運行 db 服務。

一般的，當指定數目多於該服務當前實際運行容器，將新創建並啟動容器；反之，將停止容器。

選項：

• -t, --timeout TIMEOUT 停止容器時候的超時（默認為 10 秒）。

 

start

啟動已經存在的服務容器。格式為 

docker-compose start [SERVICE...]。

 

stop

停止已經處於運行狀態的容器，但不刪除它。格式為 

docker-compose stop [options] [SERVICE...]。

通過 docker-compose start 可以再次啟動這些容器。

選項：

• -t, --timeout TIMEOUT 停止容器時候的超時（默認為 10 秒）。

 

top

查看各個服務容器內運行的進程。

 

unpause

恢復處於暫停狀態中的服務。格式為 

docker-compose unpause [SERVICE...]。

 

up

它將嘗試自動完成包括構建鏡像，（重新）創建服務，啟動服務，並關聯服務相關容器的一系列操作。鏈接的服務都將會被自動啟動，除非已經處於運行狀態。格式為 

docker-compose up [options] [SERVICE...]。

 

大部分時候都可以直接通過該命令來啟動一個項目。

默認情況，docker-compose up 啟動的容器都在前台，控制台將會同時打印所有容器的輸出信息，可以很方便進行調試。

當通過 Ctrl-C 停止命令時，所有容器將會停止。

如果使用 docker-compose up -d，將會在后台啟動並運行所有的容器。一般推薦生產環境下使用該選項。

默認情況，如果服務容器已經存在，docker-compose up 將會嘗試停止容器，然后重新創建（保持使用 volumes-from 掛載的卷），以保證新啟動的服務匹配 docker-compose.yml 文件的最新內容。

如果用戶不希望容器被停止並重新創建，可以使用 

docker-compose up --no-recreate。

這樣將只會啟動處於停止狀態的容器，而忽略已經運行的服務。

如果用戶只想重新部署某個服務，可以使用 

docker-compose up --no-deps -d <SERVICE_NAME>

來重新創建服務並后台停止舊服務，啟動新服務，並不會影響到其所依賴的服務。

選項：

• -d 在后台運行服務容器。
• --no-color 不使用顏色來區分不同的服務的控制台輸出。
• --no-deps 不啟動服務所鏈接的容器。
• --force-recreate 強制重新創建容器，不能與 --no-recreate 同時使用。
• --no-recreate 如果容器已經存在了，則不重新創建，不能與 --force-recreate 同時使用。
• --no-build 不自動構建缺失的服務鏡像。
• -t, --timeout TIMEOUT 停止容器時候的超時（默認為 10 秒）。

 

version

打印版本信息。格式為。

 docker-compose version

 

compose模板文件

 

模板文件是使用 Compose 的核心，涉及到的指令關鍵字也比較多。這里面大部分指令跟 docker run 相關參數的含義都是類似的。

默認的模板文件名稱為 docker-compose.yml，格式為 YAML 格式。

version: "3"

services:
  webapp:
    image: examples/web
    ports:
      - "80:80"
    volumes:
      - "/data"

注意每個服務都必須通過 image 指令指定鏡像或 build 指令（需要 Dockerfile）等來自動構建生成鏡像。

如果使用 build 指令，在 Dockerfile 中設置的選項(例如：CMD, EXPOSE, VOLUME, ENV 等) 將會自動被獲取，無需在 docker-compose.yml 中再次設置。

 

build

指定 Dockerfile 所在文件夾的路徑（可以是絕對路徑，或者相對 docker-compose.yml 文件的路徑）。 Compose 將會利用它自動構建這個鏡像，然后使用這個鏡像。

version: '3'
services:

  webapp:
    build: ./dir

 

你也可以使用 context 指令指定 Dockerfile 所在文件夾的路徑。

使用 dockerfile 指令指定 Dockerfile 文件名。

使用 arg 指令指定構建鏡像時的變量。

version: '3'
services:

  webapp:
    build:
      context: ./dir dockerfile: Dockerfile-alternate
      args: buildno: 1

 

使用 cache_from 指定構建鏡像的緩存

build:
  context: .
  cache_from: - alpine:latest
    - corp/web_app:3.14

 

cap_add, cap_drop

指定容器的內核能力（capacity）分配。

例如，讓容器擁有所有能力可以指定為：

cap_add:
  - ALL

去掉 NET_ADMIN 能力可以指定為：
cap_drop:
  - NET_ADMIN

 

command

覆蓋容器啟動后默認執行的命令。

command: echo "hello world"

 

configs

僅用於 Swarm mode，詳細內容請查看 Swarm mode 一節。

 

cgroup_parent

指定父 cgroup 組，意味着將繼承該組的資源限制。

例如，創建了一個 cgroup 組名稱為 cgroups_1。

cgroup_parent: cgroups_1

 

container_name

指定容器名稱。默認將會使用 項目名稱_服務名稱_序號 這樣的格式。

container_name: docker-web-container

注意: 指定容器名稱后，該服務將無法進行擴展（scale），因為 Docker 不允許多個容器具有相同的名稱。

 

devices

指定設備映射關系。

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

 

depends_on

解決容器的依賴、啟動先后的問題。以下例子中會先啟動 redis db 再啟動 web

version: '3'

services:
  web:
    build: .
    depends_on: - db
      - redis

  redis:
    image: redis

  db:
    image: postgres

注意：web 服務不會等待 redis db 「完全啟動」之后才啟動。

 

dns

自定義 DNS 服務器。可以是一個值，也可以是一個列表。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 114.114.114.114

 

dns_search

配置 DNS 搜索域。可以是一個值，也可以是一個列表。

dns_search: example.com

dns_search:
  - domain1.example.com
  - domain2.example.com

 

tmpfs

掛載一個 tmpfs 文件系統到容器。

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

 

env_file

從文件中獲取環境變量，可以為單獨的文件路徑或列表。

如果通過 docker-compose -f FILE 方式來指定 Compose 模板文件，則 env_file 中變量的路徑會基於模板文件路徑。

如果有變量名稱與 environment 指令沖突，則按照慣例，以后者為准。

env_file: .env

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

環境變量文件中每一行必須符合格式，支持 # 開頭的注釋行。

# common.env: Set development environment
PROG_ENV=development

 

environment

設置環境變量。你可以使用數組或字典兩種格式。

只給定名稱的變量會自動獲取運行 Compose 主機上對應變量的值，可以用來防止泄露不必要的數據。

environment:
  RACK_ENV: development
  SESSION_SECRET:

environment:
  - RACK_ENV=development
  - SESSION_SECRET

如果變量名稱或者值中用到 true|false，yes|no 等表達 布爾 含義的詞匯，最好放到引號里，避免 YAML 自動解析某些內容為對應的布爾語義。這些特定詞匯，包括

y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF

 

expose

暴露端口，但不映射到宿主機，只被連接的服務訪問。

僅可以指定內部端口為參數

expose:
 - "3000"
 - "8000"

 

extra_hosts

類似 Docker 中的 --add-host 參數，指定額外的 host 名稱映射信息。

extra_hosts:
 - "googledns:8.8.8.8"
 - "dockerhub:52.1.157.61"

 

會在啟動后的服務容器中 /etc/hosts 文件中添加如下兩條條目。

8.8.8.8 googledns
52.1.157.61 dockerhub

 

healthcheck

通過命令檢查容器是否健康運行。

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3

 

image

指定為鏡像名稱或鏡像 ID。如果鏡像在本地不存在，Compose 將會嘗試拉去這個鏡像。

image: ubuntu
image: orchardup/postgresql
image: a4bc65fd

 

labels

為容器添加 Docker 元數據（metadata）信息。例如可以為容器添加輔助說明信息。

labels:
  com.startupteam.description: "webapp for a startup team"
  com.startupteam.department: "devops department"
  com.startupteam.release: "rc3 for v1.0"

 

logging

配置日志選項。

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

 

目前支持三種日志驅動類型。

driver: "json-file"
driver: "syslog"
driver: "none"
options 配置日志驅動的相關參數。

options:
  max-size: "200k"
  max-file: "10"

 

network_mode

設置網絡模式。使用和 docker run 的 --network 參數一樣的值。

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

 

networks

配置容器連接的網絡。

version: "3"
services:

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

networks:
  some-network:
  other-network:

 

pid

跟主機系統共享進程命名空間。打開該選項的容器之間，以及容器和宿主機系統之間可以通過進程 ID 來相互訪問和操作。

pid: "host"
 

ports

暴露端口信息。

使用宿主端口：容器端口 (HOST:CONTAINER) 格式，或者僅僅指定容器的端口（宿主將會隨機選擇端口）都可以。

ports:
 - "3000"
 - "8000:8000"
 - "49100:22"
 - "127.0.0.1:8001:8001"

注意：當使用 HOST:CONTAINER 格式來映射端口時，如果你使用的容器端口小於 60 並且沒放到引號里，可能會得到錯誤結果，因為 YAML 會自動解析 xx:yy 這種數字格式為 60 進制。為避免出現這種問題，建議數字串都采用引號包括起來的字符串格式。

 

secrets

存儲敏感數據，例如 mysql 服務密碼。

version: "3"
services:

mysql:
  image: mysql
  environment:
    MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
  secrets: - db_root_password
    - my_other_secret

secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

 

security_opt

指定容器模板標簽（label）機制的默認屬性（用戶、角色、類型、級別等）。例如配置標簽的用戶名和角色名。

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

 

stop_signal

設置另一個信號來停止容器。在默認情況下使用的是 SIGTERM 停止容器。

stop_signal: SIGUSR1
 

sysctls

配置容器內核參數。

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

 

ulimits

指定容器的 ulimits 限制值。

例如，指定最大進程數為 65535，指定文件句柄數為 20000（軟限制，應用可以隨時修改，不能超過硬限制） 和 40000（系統硬限制，只能 root 用戶提高）。

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

 

volumes

數據卷所掛載路徑設置。可以設置宿主機路徑 （HOST:CONTAINER） 或加上訪問模式 （HOST:CONTAINER:ro）。

該指令中路徑支持相對路徑。

volumes:
 - /var/lib/mysql
 - cache/:/tmp/cache
 - ~/configs:/etc/configs/:ro

 

其它指令

此外，還有包括 domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir 等指令，基本跟 docker run 中對應參數的功能一致。

 

指定服務容器啟動后執行的入口文件。

entrypoint: /code/entrypoint.sh

 

指定容器中運行應用的用戶名。

user: nginx

 

指定容器中工作目錄。

working_dir: /code

 

指定容器中搜索域名、主機名、mac 地址等。

domainname: your_website.com
hostname: test
mac_address: 08-00-27-00-0C-0A

 

允許容器中運行一些特權命令。

privileged: true

 

指定容器退出后的重啟策略為始終重啟。該命令對保持服務始終運行十分有效，在生產環境中推薦配置為 always 或者 unless-stopped。

restart: always

 

以只讀模式掛載容器的 root 文件系統，意味着不能對容器內容進行修改。

read_only: true

 

打開標准輸入，可以接受外部輸入。

stdin_open: true

 

模擬一個偽終端。

tty: true

 

讀取變量

Compose 模板文件支持動態讀取主機的系統環境變量和當前目錄下的 .env 文件中的變量。

例如，下面的 Compose 文件將從運行它的環境中讀取變量 ${MONGO_VERSION} 的值，並寫入執行的指令中。

version: "3"
services:

db:
  image: "mongo:${MONGO_VERSION}"

 

如果執行 MONGO_VERSION=3.2 docker-compose up 則會啟動一個 mongo:3.2 鏡像的容器；如果執行 MONGO_VERSION=2.8 docker-compose up 則會啟動一個 mongo:2.8 鏡像的容器。

若當前目錄存在 .env 文件，執行 docker-compose 命令時將從該文件中讀取變量。

在當前目錄新建 .env 文件並寫入以下內容。

# 支持 # 號注釋 MONGO_VERSION=3.6 

執行 docker-compose up 則會啟動一個 mongo:3.6 鏡像的容器