Add the compose chapter

pull/58/head
Baohua Yang 2015-05-08 20:10:01 +08:00
parent 36127abed9
commit 8626d13738
14 changed files with 482 additions and 14 deletions

View File

@ -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 项目

View File

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

BIN
_images/compose.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

4
compose/README.md Normal file
View File

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

142
compose/commands.md Normal file
View File

@ -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`

63
compose/install.md Normal file
View File

@ -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
```

10
compose/intro.md Normal file
View File

@ -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 来实现。

7
compose/usage.md Normal file
View File

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

223
compose/yaml_file.md Normal file
View File

@ -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
```

View File

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

View File

@ -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`

View File

@ -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`

View File

@ -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 安装包来完成安装(支持的系统同样适用)。

View File

@ -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 镜像,启动所有的服务。
```