Add the compose chapter

README.md

@@ -21,6 +21,10 @@ v0.4
 * [亚马逊图书](http://www.amazon.cn/%E5%9B%BE%E4%B9%A6/dp/B00R5MYI7C/ref=lh_ni_t?ie=UTF8&psc=1&smid=A1AJ19PSB66TGU)
 
 ## 主要版本历史
+* 0.5: 2015-?
+    * 添加 Compose 项目
+    * 添加 Machine 项目
+    * 添加 Swarm 项目
 * 0.4: 2015-05-08
     * 添加 Etcd 项目
     * 添加 Fig 项目

SUMMARY.md

@@ -69,6 +69,20 @@
    * [联合文件系统](underly/ufs.md)
    * [容器格式](underly/container_format.md)
    * [网络](underly/network.md)
+* [Docker Compose 项目](compose/README.md)
+   * [简介](compose/intro.md)
+   * [安装](compose/install.md)
+   * [使用](compose/usage.md)
+   * [命令说明](compose/commands.md)
+   * [YAML 模板文件](compose/yaml_file.md)
+* [Docker Machine 项目](machine/README.md)
+   * [简介](machine/intro.md)
+   * [安装](machine/install.md)
+   * [使用](machine/usage.md)
+* [Docker Swarm 项目](swarm/README.md)
+   * [简介](swarm/intro.md)
+   * [安装](swarm/install.md)
+   * [使用](swarm/usage.md)
 * [Etcd 项目](etcd/README.md)
    * [简介](etcd/intro.md)
    * [安装](etcd/install.md)
@@ -98,3 +112,4 @@
    * [WordPress](appendix_repo/wordpress.md)
    * [Node.js](appendix_repo/nodejs.md)
 * [附录三：有用的资源](appendix_resources/README.md)
+

compose/README.md

@@ -0,0 +1,4 @@
+# Docker Compose 项目
+Docker Compose 是 Docker 官方编排（Orchestration）项目之一，负责快速在集群中部署分布式应用。
+
+本章将介绍 Compose 项目情况以及安装和使用。

compose/commands.md

@@ -0,0 +1,142 @@
+## Compose 命令说明
+
+大部分命令都可以运行在一个或多个服务上。如果没有特别的说明，命令则应用在项目所有的服务上。
+
+执行 `docker-compose [COMMAND] --help` 查看具体某个命令的使用说明。
+
+基本的使用格式是
+```sh
+docker-compose [options] [COMMAND] [ARGS...]
+```
+
+## 选项
+
+* `--verbose` 输出更多调试信息。
+* `--version` 打印版本并退出。
+* `-f, --file FILE` 使用特定的 compose 模板文件，默认为 `docker-compose.yml`。
+* `-p, --project-name NAME` 指定项目名称，默认使用目录名称。
+
+## 命令
+
+### `build`
+
+构建或重新构建服务。
+
+服务一旦构建后，将会带上一个标记名，例如 web_db。
+
+可以随时在项目目录下运行 `docker-compose build` 来重新构建服务。
+
+### `help`
+
+获得一个命令的帮助。
+
+### `kill`
+
+通过发送 `SIGKILL` 信号来强制停止服务容器。支持通过参数来指定发送的信号，例如
+```sh
+$ docker-compose kill -s SIGINT
+```
+
+### `logs`
+
+查看服务的输出。
+
+### `port`
+
+打印绑定的公共端口。
+
+### `ps`
+
+列出所有容器。
+
+### `pull`
+
+拉取服务镜像。
+
+### `rm`
+
+删除停止的服务容器。
+
+### `run`
+
+在一个服务上执行一个命令。
+
+例如：
+
+```
+$ docker-compose run ubuntu ping docker.com
+```
+
+将会启动一个 ubuntu 服务，执行 `ping docker.com` 命令。
+
+默认情况下，所有关联的服务将会自动被启动，除非这些服务已经在运行中。
+
+该命令类似启动容器后运行指定的命令，相关卷、链接等等都将会按照期望创建。
+
+两个不同点：
+* 给定命令将会覆盖原有的自动运行命令；
+* 不会自动创建端口，以避免冲突。
+
+如果不希望自动启动关联的容器，可以使用 `--no-deps` 选项，例如
+
+```
+$ docker-compose run --no-deps web python manage.py shell
+```
+
+将不会启动 web 容器所关联的其它容器。
+
+### `scale`
+
+设置同一个服务运行的容器个数。
+
+通过 `service=num` 的参数来设置数量。例如：
+
+```
+$ docker-compose scale web=2 worker=3
+```
+
+### `start`
+
+启动一个已经存在的服务容器。
+
+### `stop`
+
+停止一个已经运行的容器，但不删除它。通过 `docker-compose start` 可以再次启动这些容器。
+
+### `up`
+
+构建，（重新）创建，启动，链接一个服务相关的容器。
+
+链接的服务都将会启动，除非他们已经运行。
+
+默认情况， `docker-compose up` 将会整合所有容器的输出，并且退出时，所有容器将会停止。
+
+如果使用 `docker-compose up -d` ，将会在后台启动并运行所有的容器。
+
+默认情况，如果该服务的容器已经存在， `docker-compose up` 将会停止并尝试重新创建他们（保持使用 `volumes-from` 挂载的卷），以保证 `docker-compose.yml` 的修改生效。如果你不想容器被停止并重新创建，可以使用 `docker-compose up --no-recreate`。如果需要的话，这样将会启动已经停止的容器。
+
+## 环境变量
+
+环境变量可以用来配置 Compose 的行为。
+
+以`DOCKER_`开头的变量和用来配置 Docker 命令行客户端的使用一样。如果使用 boot2docker , `$(boot2docker shellinit)` 将会设置它们为正确的值。
+
+### `COMPOSE_PROJECT_NAME`
+
+设置通过 Compose 启动的每一个容器前添加的项目名称，默认是当前工作目录的名字。
+
+### `COMPOSE_FILE`
+
+设置要使用的 `docker-compose.yml` 的路径。默认路径是当前工作目录。
+
+### `DOCKER_HOST`
+
+设置 Docker daemon 的地址。默认使用 `unix:///var/run/docker.sock`，与 Docker 客户端采用的默认值一致。
+
+### `DOCKER_TLS_VERIFY`
+
+如果设置不为空，则与 Docker daemon 交互通过 TLS 进行。
+
+### `DOCKER_CERT_PATH`
+
+配置 TLS 通信所需要的验证（`ca.pem`、`cert.pem` 和 `key.pem`）文件的路径，默认是 `~/.docker` 。

compose/install.md

@@ -0,0 +1,63 @@
+## 安装
+
+安装 Compose 之前，要先安装 Docker，在此不再赘述。
+
+### PIP 安装
+这种方式最为推荐。
+
+执行命令。
+```sh
+$ sudo pip install -U docker-compose
+```
+
+安装成功后，可以查看 `docker-compose` 命令的用法。
+```sh
+$ docker-compose -h
+Fast, isolated development environments using Docker.
+
+Usage:
+  docker-compose [options] [COMMAND] [ARGS...]
+  docker-compose -h|--help
+
+Options:
+  --verbose                 Show more output
+  --version                 Print version and exit
+  -f, --file FILE           Specify an alternate compose file (default: docker-compose.yml)
+  -p, --project-name NAME   Specify an alternate project name (default: directory name)
+
+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
+  rm        Remove stopped containers
+  run       Run a one-off command
+  scale     Set number of containers for a service
+  start     Start services
+  stop      Stop services
+  restart   Restart services
+  up        Create and start containers
+```
+
+之后，可以添加 bash 补全命令。
+```sh
+$ curl -L https://raw.githubusercontent.com/docker/compose/1.2.0/contrib/completion/bash/docker-compose > /etc/bash_completion.d/docker-compose
+
+```
+
+### 二进制包
+发布的二进制包可以在 [https://github.com/docker/compose/releases](https://github.com/docker/compose/releases) 找到。
+
+下载后直接放到执行路径即可。
+
+例如，在常见的 Linux 平台上。
+
+```
+$ sudo curl -L https://github.com/docker/compose/releases/download/1.2.0/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
+$ sudo chmod a+x /usr/local/bin/docker-compose
+```
+
+

compose/intro.md

@@ -0,0 +1,10 @@
+## 简介
+Compose 项目目前在 [Github](https://github.com/docker/compose) 上进行维护，目前最新版本是 1.2.0。
+
+Compose 定位是“defining and running complex applications with Docker”，前身是 Fig，兼容 Fig 的模板文件。
+
+Dockerfile 可以让用户管理一个单独的应用容器；而 Compose 则允许用户在一个模板（YAML 格式）中定义一组相关联的应用容器（被称为一个 `project`，即项目），例如一个 Web 服务容器再加上后端的数据库服务容器等。
+
+![](../_images/compose.png)
+
+该项目由 Python 编写，实际上调用了 Docker 提供的 API 来实现。

compose/usage.md

@@ -0,0 +1,7 @@
+## 使用
+
+### 术语
+首先介绍几个术语。
+
+* 服务（service）：一个应用容器，实际上可以运行多个相同镜像的实例。
+* 项目(project)：由一组关联的应用容器组成的一个完整业务单元。

compose/yaml_file.md

@@ -0,0 +1,223 @@
+## YAML 模板文件
+
+默认的模板文件是 `docker-compose.yml`，其中定义的每个服务都必须通过 `image` 指令指定镜像或 `build` 指令（需要 Dockerfile）来自动构建。
+
+其它大部分指令都跟 `docker run` 中的类似。
+
+如果使用 `build` 指令，在 `Dockerfile` 中设置的选项(例如：`CMD`, `EXPOSE`, `VOLUME`, `ENV` 等) 将会自动被获取，无需在 `docker-compose.yml` 中再次设置。
+
+### `image`
+
+指定为镜像名称或镜像 ID。如果镜像在本地不存在，`Compose` 将会尝试拉去这个镜像。
+
+例如：
+```sh
+image: ubuntu
+image: orchardup/postgresql
+image: a4bc65fd
+```
+
+### `build`
+
+指定 `Dockerfile` 所在文件夹的路径。 `Compose` 将会利用它自动构建这个镜像，然后使用这个镜像。
+
+```
+build: /path/to/build/dir
+```
+
+### `command`
+
+覆盖容器启动后默认执行的命令。
+
+```sh
+command: bundle exec thin -p 3000
+```
+
+### `links`
+
+链接到其它服务中的容器。使用服务名称（同时作为别名）或服务名称：服务别名 `（SERVICE:ALIAS）` 格式都可以。
+
+```sh
+links:
+ - db
+ - db:database
+ - redis
+```
+
+使用的别名将会自动在服务容器中的 `/etc/hosts` 里创建。例如：
+
+```sh
+172.17.2.186  db
+172.17.2.186  database
+172.17.2.187  redis
+```
+
+相应的环境变量也将被创建。
+
+### `external_links`
+链接到 docker-compose.yml 外部的容器，甚至 并非 `Compose` 管理的容器。参数格式跟 `links` 类似。
+
+```
+external_links:
+ - redis_1
+ - project_db_1:mysql
+ - project_db_1:postgresql
+```
+
+
+### `ports`
+
+暴露端口信息。
+
+使用宿主：容器 `（HOST:CONTAINER）`格式或者仅仅指定容器的端口（宿主将会随机选择端口）都可以。
+
+```
+ports:
+ - "3000"
+ - "8000:8000"
+ - "49100:22"
+ - "127.0.0.1:8001:8001"
+```
+
+*注：当使用 `HOST:CONTAINER` 格式来映射端口时，如果你使用的容器端口小于 60 你可能会得到错误得结果，因为 `YAML` 将会解析 `xx:yy` 这种数字格式为 60 进制。所以建议采用字符串格式。*
+
+
+### `expose`
+
+暴露端口，但不映射到宿主机，只被连接的服务访问。
+
+仅可以指定内部端口为参数
+
+```sh
+expose:
+ - "3000"
+ - "8000"
+```
+
+### `volumes`
+
+卷挂载路径设置。可以设置宿主机路径 （`HOST:CONTAINER`） 或加上访问模式 （`HOST:CONTAINER:ro`）。
+
+```sh
+volumes:
+ - /var/lib/mysql
+ - cache/:/tmp/cache
+ - ~/configs:/etc/configs/:ro
+```
+
+### `volumes_from`
+
+从另一个服务或容器挂载它的所有卷。
+
+```sh
+volumes_from:
+ - service_name
+ - container_name
+```
+
+### `environment`
+
+设置环境变量。你可以使用数组或字典两种格式。
+
+只给定名称的变量会自动获取它在 Compose 主机上的值，可以用来防止泄露不必要的数据。
+
+```
+environment:
+  RACK_ENV: development
+  SESSION_SECRET:
+
+environment:
+  - RACK_ENV=development
+  - SESSION_SECRET
+```
+
+### `env_file`
+从文件中获取环境变量，可以为单独的文件路径或列表。
+
+如果通过 `docker-compose -f FILE` 指定了模板文件，则 `env_file` 中路径会基于模板文件路径。
+
+如果有变量名称与 `environment` 指令冲突，则以后者为准。
+
+```sh
+env_file: .env
+
+env_file:
+  - ./common.env
+  - ./apps/web.env
+  - /opt/secrets.env
+```
+
+环境变量文件中每一行必须符合格式，支持 `#` 开头的注释行。
+
+```sh
+# common.env: Set Rails/Rack environment
+RACK_ENV=development
+```
+
+### `extends`
+基于已有的服务进行扩展。例如我们已经有了一个 webapp 服务，模板文件为 `common.yml`。
+```sh
+# common.yml
+webapp:
+  build: ./webapp
+  environment:
+    - DEBUG=false
+    - SEND_EMAILS=false
+```
+
+编写一个新的 `development.yml` 文件，使用 `common.yml` 中的 webapp 服务进行扩展。
+```sh
+# development.yml
+web:
+  extends:
+    file: common.yml
+    service: webapp
+  ports:
+    - "8000:8000"
+  links:
+    - db
+  environment:
+    - DEBUG=true
+db:
+  image: postgres
+```
+后者会自动继承 common.yml 中的 webapp 服务及相关环节变量。
+
+
+### `net`
+
+设置网络模式。使用和 `docker client` 的 `--net` 参数一样的值。
+
+```
+net: "bridge"
+net: "none"
+net: "container:[name or id]"
+net: "host"
+```
+
+### `dns`
+
+配置DNS服务器。它可以是一个值，也可以是一个列表。
+
+```
+dns: 8.8.8.8
+dns:
+  - 8.8.8.8
+  - 9.9.9.9
+```
+
+`working_dir, entrypoint, user, hostname, domainname, mem_limit, privileged`
+
+这些都是和 `docker run` 对应的一个值。
+
+```
+working_dir: /code
+entrypoint: /code/entrypoint.sh
+user: postgresql
+
+hostname: foo
+domainname: foo.com
+
+mem_limit: 1000000000
+privileged: true
+```

fig/README.md

@@ -1,2 +1,2 @@
 #Fig
-在你的应用里面添加一个 `fig.yml` 文件，并指定一些简单的内容，执行 `fig up` 它就能帮你快速建立起一个容器。
+在你的应用里面添加一个 `fig.yml` 文件，并指定一些简单的内容，执行 `fig up` 它就能帮你快速建立起一个容器。目前已经正式更名为 [Compose](../compose/README.md)。

fig/cli_ref.md

@@ -138,4 +138,4 @@ $ fig scale web=2 worker=3
 
 `DOCKER_CERT_PATH`
 
-配置 `ca.pem` 的路径， `cert.pem` 和 `key.pem` 文件用来进行TLS验证.默认路径是 `~/.docker` 。
+配置 `ca.pem` 的路径， `cert.pem` 和 `key.pem` 文件用来进行TLS验证.默认路径是 `~/.docker` 。

fig/env_ref.md

@@ -28,4 +28,4 @@ Fig 使用 Docker 链接来暴露一个服务的容器给其它容器。每一
 
 `name_NAME`
 
-完整合格的容器名称，例如： `DB_1_NAME=/myapp_web_1/myapp_db_1`
+完整合格的容器名称，例如： `DB_1_NAME=/myapp_web_1/myapp_db_1`

fig/install.md

@@ -12,12 +12,12 @@ $(boot2docker shellinit)
 关于 `Ubuntu` 还有 `其它的平台` 的安装，可以参照 [Ubuntu 安装指南(中文)](../install/ubuntu.md) 以及 [官方安装手册(英文)](https://docs.docker.com/installation/)。
 
 
-下一步，安装 Fig ： 
+下一步，安装 Fig ：
 
 ```
 curl -L https://github.com/docker/fig/releases/download/1.0.1/fig-`uname -s`-`uname -m` > /usr/local/bin/fig; chmod +x /usr/local/bin/fig
 ```
-**如果你的 Docker 是管理员身份安装，以上命令可能也需要相同的身份。*  
+**如果你的 Docker 是管理员身份安装，以上命令可能也需要相同的身份。*
 
 目前 Fig 的发行版本只支持 OSX 和 64 位的 Linux 系统。但因为它是用 Python 语言写的，所以对于其它平台上的用户，可以通过 Python 安装包来完成安装（支持的系统同样适用）。
 

fig/intro.md

@@ -11,7 +11,7 @@ RUN pip install -r requirements.txt
 
 在 `fig.yml` 文件中指定应用使用的不同服务，让它们能够在一个独立的环境中一起运行：
 
-```  
+```
 web:
   build: .
   command: python app.py
@@ -28,7 +28,7 @@ db:
 
 ![Docker](../_images/fig-example-large.gif)
 
-Fig 可用的命令有:   
+Fig 可用的命令有:
 
 * 启动、停止，和重建服务
 * 查看服务的运行状态
@@ -38,7 +38,7 @@ Fig 可用的命令有:
 ##快速上手
 我们试着让一个基本的 Python web 应用运行在 Fig 上。这个实验假设你已经知道一些 Python 知识，如果你不熟悉，但清楚概念上的东西也是没有问题的。
 
-首先，[安装 Docker 和 Fig](install.md)  
+首先，[安装 Docker 和 Fig](install.md)
 
 为你的项目创建一个目录
 
@@ -46,7 +46,7 @@ Fig 可用的命令有:
 $ mkdir figtest
 $ cd figtest
 ```
-进入目录，创建 `app.py`，这是一个能够让 Redis 上的一个值自增的简单 web 应用，基于 Flask 框架。  
+进入目录，创建 `app.py`，这是一个能够让 Redis 上的一个值自增的简单 web 应用，基于 Flask 框架。
 
 ```
 from flask import Flask
@@ -63,9 +63,9 @@ def hello():
 if __name__ == "__main__":
     app.run(host="0.0.0.0", debug=True)
 ```
-在 `requirements.txt` 文件中指定应用的 Python 依赖包。   
+在 `requirements.txt` 文件中指定应用的 Python 依赖包。
 
-```  
+```
 flask
 redis
 ```
@@ -94,11 +94,11 @@ web:
 redis:
   image: redis
   ```
-这里指定了两个服务：  
+这里指定了两个服务：
 
 * web 服务，通过当前目录的 `Dockerfile` 创建。并且说明了在容器里面执行`python app.py ` 命令 ，转发在容器里开放的 5000 端口到本地主机的 5000 端口，连接 Redis 服务，并且挂载当前目录到容器里面，这样我们就可以不用重建镜像也能直接使用代码。
-* redis 服务，我们使用公用镜像 [redis](https://registry.hub.docker.com/_/redis/)。  
-* 
+* redis 服务，我们使用公用镜像 [redis](https://registry.hub.docker.com/_/redis/)。
+*
 现在如果执行 `fig up` 命令 ，它就会拉取 redis 镜像，启动所有的服务。
 
 ```