diff --git a/README.md b/README.md index 4756136..7539f7b 100644 --- a/README.md +++ b/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 项目 diff --git a/SUMMARY.md b/SUMMARY.md index a6aff09..678670a 100644 --- a/SUMMARY.md +++ b/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) + diff --git a/_images/compose.png b/_images/compose.png new file mode 100644 index 0000000..d753482 Binary files /dev/null and b/_images/compose.png differ diff --git a/compose/README.md b/compose/README.md new file mode 100644 index 0000000..0892ff7 --- /dev/null +++ b/compose/README.md @@ -0,0 +1,4 @@ +# Docker Compose 项目 +Docker Compose 是 Docker 官方编排（Orchestration）项目之一，负责快速在集群中部署分布式应用。 + +本章将介绍 Compose 项目情况以及安装和使用。 diff --git a/compose/commands.md b/compose/commands.md new file mode 100644 index 0000000..d218ad1 --- /dev/null +++ b/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` 。 diff --git a/compose/install.md b/compose/install.md new file mode 100644 index 0000000..8d1e084 --- /dev/null +++ b/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 +``` + + diff --git a/compose/intro.md b/compose/intro.md new file mode 100644 index 0000000..46fe5a8 --- /dev/null +++ b/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 来实现。 diff --git a/compose/usage.md b/compose/usage.md new file mode 100644 index 0000000..78621c4 --- /dev/null +++ b/compose/usage.md @@ -0,0 +1,7 @@ +## 使用 + +### 术语 +首先介绍几个术语。 + +* 服务（service）：一个应用容器，实际上可以运行多个相同镜像的实例。 +* 项目(project)：由一组关联的应用容器组成的一个完整业务单元。 diff --git a/compose/yaml_file.md b/compose/yaml_file.md new file mode 100644 index 0000000..d70b029 --- /dev/null +++ b/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 +``` diff --git a/fig/README.md b/fig/README.md index 2a47bcf..b75df69 100644 --- a/fig/README.md +++ b/fig/README.md @@ -1,2 +1,2 @@ #Fig -在你的应用里面添加一个 `fig.yml` 文件，并指定一些简单的内容，执行 `fig up` 它就能帮你快速建立起一个容器。 \ No newline at end of file +在你的应用里面添加一个 `fig.yml` 文件，并指定一些简单的内容，执行 `fig up` 它就能帮你快速建立起一个容器。目前已经正式更名为 [Compose](../compose/README.md)。 diff --git a/fig/cli_ref.md b/fig/cli_ref.md index a6c9bb3..a2bf8f1 100644 --- a/fig/cli_ref.md +++ b/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` 。 \ No newline at end of file +配置 `ca.pem` 的路径， `cert.pem` 和 `key.pem` 文件用来进行TLS验证.默认路径是 `~/.docker` 。 diff --git a/fig/env_ref.md b/fig/env_ref.md index 96e9f92..4592756 100644 --- a/fig/env_ref.md +++ b/fig/env_ref.md @@ -28,4 +28,4 @@ Fig 使用 Docker 链接来暴露一个服务的容器给其它容器。每一 `name_NAME` -完整合格的容器名称，例如： `DB_1_NAME=/myapp_web_1/myapp_db_1` \ No newline at end of file +完整合格的容器名称，例如： `DB_1_NAME=/myapp_web_1/myapp_db_1` diff --git a/fig/install.md b/fig/install.md index 9a81d3a..c4a099f 100644 --- a/fig/install.md +++ b/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 安装包来完成安装（支持的系统同样适用）。 diff --git a/fig/intro.md b/fig/intro.md index bec3994..1ceb589 100644 --- a/fig/intro.md +++ b/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 镜像，启动所有的服务。 ```