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)。