Merge pull request #239 from yeasy/dev

SUMMARY.md

@@ -87,7 +87,7 @@
     * [YAML 模板文件](compose/yaml_file.md)
     * [实战 Django](compose/django.md)
     * [实战 Rails](compose/rails.md)
-    * [实战 wordpress](compose/wordpress.md)
+    * [实战 WordPress](compose/wordpress.md)
 * [Docker 三剑客之 Machine 项目](machine/README.md)
     * [安装](machine/install.md)
     * [使用](machine/usage.md)

compose/README.md

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

compose/commands.md

@@ -7,17 +7,22 @@
 
 Compose 命令的基本的使用格式是
 
-```sh
+```bash
 docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
 ```
 
 ### 命令选项
 
 * `-f, --file FILE` 指定使用的 Compose 模板文件，默认为 `docker-compose.yml`，可以多次指定。
+
 * `-p, --project-name NAME` 指定项目名称，默认将使用所在目录名称作为项目名。
-* `--x-networking` 使用 Docker 的可拔插网络后端特性（需要 Docker 1.9 及以后版本）。
+
-* `--x-network-driver DRIVER` 指定网络后端的驱动，默认为 `bridge`（需要 Docker 1.9 及以后版本）。
+* `--x-networking` 使用 Docker 的可拔插网络后端特性
+
+* `--x-network-driver DRIVER` 指定网络后端的驱动，默认为 `bridge`
+
 * `--verbose` 输出更多调试信息。
+
 * `-v, --version` 打印版本并退出。
 
 ### 命令使用说明
@@ -34,7 +39,9 @@ docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
 选项包括：
 
 * `--force-rm` 删除构建过程中的临时容器。
+
 * `--no-cache` 构建镜像过程中不使用 cache（这将加长构建过程）。
+
 * `--pull` 始终尝试通过 pull 来获取更新版本的镜像。
 
 #### `help`
@@ -48,7 +55,7 @@ docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
 
 支持通过 `-s` 参数来指定发送的信号，例如通过如下指令发送 `SIGINT` 信号。
 
-```sh
+```bash
 $ docker-compose kill -s SIGINT
 ```
 
@@ -72,6 +79,7 @@ $ docker-compose kill -s SIGINT
 选项：
 
 * `--protocol=proto` 指定端口协议，tcp（默认值）或者 udp。
+
 * `--index=index` 如果同一服务存在多个容器，指定命令对象容器的序号（默认为 1）。
 
 #### `ps`
@@ -109,6 +117,7 @@ $ docker-compose kill -s SIGINT
 选项：
 
 * `-f, --force` 强制直接删除，包括非停止状态的容器。一般尽量不要使用该选项。
+
 * `-v` 删除容器所挂载的数据卷。
 
 #### `run`
@@ -118,7 +127,7 @@ $ docker-compose kill -s SIGINT
 
 例如：
 
-```sh
+```bash
 $ docker-compose run ubuntu ping docker.com
 ```
 
@@ -131,11 +140,12 @@ $ docker-compose run ubuntu ping docker.com
 两个不同点：
 
 * 给定命令将会覆盖原有的自动运行命令；
+
 * 不会自动创建端口，以避免冲突。
 
 如果不希望自动启动关联的容器，可以使用 `--no-deps` 选项，例如
 
-```sh
+```bash
 $ docker-compose run --no-deps web python manage.py shell
 ```
 
@@ -144,14 +154,23 @@ $ docker-compose run --no-deps web python manage.py shell
 选项：
 
 * `-d` 后台运行容器。
+
 * `--name NAME` 为容器指定一个名字。
+
 * `--entrypoint CMD` 覆盖默认的容器启动指令。
+
 * `-e KEY=VAL` 设置环境变量值，可多次使用选项来设置多个环境变量。
+
 * `-u, --user=""` 指定运行容器的用户名或者 uid。
+
 * `--no-deps` 不自动启动关联的服务容器。
+
 * `--rm` 运行命令后自动删除容器，`d` 模式下将忽略。
+
 * `-p, --publish=[]` 映射容器端口到本地主机。
+
 * `--service-ports` 配置服务端口并映射到本地主机。
+
 * `-T` 不分配伪 tty，意味着依赖 tty 的指令将无法运行。
 
 #### `scale`
@@ -161,7 +180,7 @@ $ docker-compose run --no-deps web python manage.py shell
 
 通过 `service=num` 的参数来设置数量。例如：
 
-```sh
+```bash
 $ docker-compose scale web=3 db=2
 ```
 
@@ -212,11 +231,17 @@ $ docker-compose scale web=3 db=2
 选项：
 
 * `-d` 在后台运行服务容器。
+
 * `--no-color` 不使用颜色来区分不同的服务的控制台输出。
+
 * `--no-deps` 不启动服务所链接的容器。
+
 * `--force-recreate` 强制重新创建容器，不能与 `--no-recreate` 同时使用。
+
 * `--no-recreate` 如果容器已经存在了，则不重新创建，不能与 `--force-recreate` 同时使用。
+
 * `--no-build` 不自动构建缺失的服务镜像。
+
 * `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。
 
 #### `migrate-to-labels`

compose/demo/compose-haproxy-web/docker-compose.yml

@@ -0,0 +1,29 @@
+version: "3"
+services:
+
+  weba:
+    build: ./web
+    expose:
+        - 80
+
+  webb:
+    build: ./web
+    expose:
+        - 80
+
+  webc:
+    build: ./web
+    expose:
+        - 80
+
+  haproxy:
+    image: haproxy:latest
+    volumes:
+        - ./haproxy:/haproxy-override
+        - ./haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+    ports:
+        - "80:80"
+        - "70:70"
+    expose:
+        - "80"
+        - "70"

compose/demo/compose-haproxy-web/haproxy/haproxy.cfg

@@ -0,0 +1,32 @@
+global
+  log 127.0.0.1 local0
+  log 127.0.0.1 local1 notice
+
+defaults
+  log global
+  mode http
+  option httplog
+  option dontlognull
+  timeout connect 5000ms
+  timeout client 50000ms
+  timeout server 50000ms
+
+listen stats
+    bind 0.0.0.0:70
+    stats enable
+    stats uri /
+
+frontend balancer
+    bind 0.0.0.0:80
+    mode http
+    default_backend web_backends
+
+backend web_backends
+    mode http
+    option forwardfor
+    balance roundrobin
+    server weba weba:80 check
+    server webb webb:80 check
+    server webc webc:80 check
+    option httpchk GET /
+    http-check expect status 200

compose/demo/compose-haproxy-web/web/Dockerfile

@@ -0,0 +1,5 @@
+FROM python:2.7
+WORKDIR /code
+ADD . /code
+EXPOSE 80
+CMD python index.py

compose/demo/compose-haproxy-web/web/index.py

@@ -0,0 +1,68 @@
+#!/usr/bin/python
+#authors: yeasy.github.com
+#date: 2013-07-05
+
+import sys
+import BaseHTTPServer
+from SimpleHTTPServer import SimpleHTTPRequestHandler
+import socket
+import fcntl
+import struct
+import pickle
+from datetime import datetime
+from collections import OrderedDict
+
+class HandlerClass(SimpleHTTPRequestHandler):
+    def get_ip_address(self,ifname):
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        return socket.inet_ntoa(fcntl.ioctl(
+            s.fileno(),
+            0x8915,  # SIOCGIFADDR
+            struct.pack('256s', ifname[:15])
+        )[20:24])
+    def log_message(self, format, *args):
+        if len(args) < 3 or "200" not in args[1]:
+            return
+        try:
+            request = pickle.load(open("pickle_data.txt","r"))
+        except:
+            request=OrderedDict()
+        time_now = datetime.now()
+        ts = time_now.strftime('%Y-%m-%d %H:%M:%S')
+        server = self.get_ip_address('eth0')
+        host=self.address_string()
+        addr_pair = (host,server)
+        if addr_pair not in request:
+            request[addr_pair]=[1,ts]
+        else:
+            num = request[addr_pair][0]+1
+            del request[addr_pair]
+            request[addr_pair]=[num,ts]
+        file=open("index.html", "w")
+        file.write("<!DOCTYPE html> <html> <body><center><h1><font color=\"blue\" face=\"Georgia, Arial\" size=8><em>HA</em></font> Webpage Visit Results</h1></center>")
+        for pair in request:
+            if pair[0] == host:
+                guest = "LOCAL: "+pair[0]
+            else:
+                guest = pair[0]
+            if (time_now-datetime.strptime(request[pair][1],'%Y-%m-%d %H:%M:%S')).seconds < 3:
+                file.write("<p style=\"font-size:150%\" >#"+ str(request[pair][1]) +": <font color=\"red\">"+str(request[pair][0])+ "</font> requests " + "from &lt<font color=\"blue\">"+guest+"</font>&gt to WebServer &lt<font color=\"blue\">"+pair[1]+"</font>&gt</p>")
+            else:
+                file.write("<p style=\"font-size:150%\" >#"+ str(request[pair][1]) +": <font color=\"maroon\">"+str(request[pair][0])+ "</font> requests " + "from &lt<font color=\"navy\">"+guest+"</font>&gt to WebServer &lt<font color=\"navy\">"+pair[1]+"</font>&gt</p>")
+        file.write("</body> </html>")
+        file.close()
+        pickle.dump(request,open("pickle_data.txt","w"))
+
+if __name__ == '__main__':
+    try:
+        ServerClass  = BaseHTTPServer.HTTPServer
+        Protocol     = "HTTP/1.0"
+        addr = len(sys.argv) < 2 and "0.0.0.0" or sys.argv[1]
+        port = len(sys.argv) < 3 and 80 or int(sys.argv[2])
+        HandlerClass.protocol_version = Protocol
+        httpd = ServerClass((addr, port), HandlerClass)
+        sa = httpd.socket.getsockname()
+        print "Serving HTTP on", sa[0], "port", sa[1], "..."
+        httpd.serve_forever()
+    except:
+        exit()

compose/demo/django/.gitignore

@@ -0,0 +1 @@
+django_example

compose/demo/django/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3
+ENV PYTHONUNBUFFERED 1
+RUN mkdir /code
+WORKDIR /code
+ADD requirements.txt /code/
+RUN pip install -r requirements.txt
+ADD . /code/

compose/demo/django/docker-compose.yml

@@ -0,0 +1,15 @@
+version: "3"
+services:
+
+  db:
+    image: postgres
+
+  web:
+    build: .
+    command: python3 manage.py runserver 0.0.0.0:8000
+    volumes:
+      - .:/code
+    ports:
+      - "8000:8000"
+    links:
+      - db

compose/demo/django/manage.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+import os
+import sys
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_example.settings")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError:
+        # The above import may fail for some other reason. Ensure that the
+        # issue is really that Django is missing to avoid masking other
+        # exceptions on Python 2.
+        try:
+            import django
+        except ImportError:
+            raise ImportError(
+                "Couldn't import Django. Are you sure it's installed and "
+                "available on your PYTHONPATH environment variable? Did you "
+                "forget to activate a virtual environment?"
+            )
+        raise
+    execute_from_command_line(sys.argv)

compose/demo/django/requirements.txt

@@ -0,0 +1,2 @@
+Django>=1.8,<2.0
+psycopg2

compose/demo/wordpress/docker-compose.yml

@@ -0,0 +1,27 @@
+version: "3"
+services:
+
+   db:
+     image: mysql:5.7
+     volumes:
+       - db_data:/var/lib/mysql
+     restart: always
+     environment:
+       MYSQL_ROOT_PASSWORD: somewordpress
+       MYSQL_DATABASE: wordpress
+       MYSQL_USER: wordpress
+       MYSQL_PASSWORD: wordpress
+
+   wordpress:
+     depends_on:
+       - db
+     image: wordpress:latest
+     ports:
+       - "8000:80"
+     restart: always
+     environment:
+       WORDPRESS_DB_HOST: db:3306
+       WORDPRESS_DB_USER: wordpress
+       WORDPRESS_DB_PASSWORD: wordpress
+volumes:
+    db_data:

compose/django.md

@@ -1,12 +1,15 @@
 ## 使用 Django
 
-我们现在将使用 Docker Compose 配置并运行一个 `Django/PostgreSQL` 应用。
+本小节内容适合 Python 开发人员阅读。
+
+我们现在将使用 `Docker Compose` 配置并运行一个 `Django/PostgreSQL` 应用。
+
+在一切工作开始前，需要先编辑好三个必要的文件。
 
-在一切工作开始前，需要先设置好三个必要的文件。  
 第一步，因为应用将要运行在一个满足所有环境依赖的 Docker 容器里面，那么我们可以通过编辑 `Dockerfile` 文件来指定 Docker 容器要安装内容。内容如下：
 
 ```docker
-FROM python:2.7
+FROM python:3
 ENV PYTHONUNBUFFERED 1
 RUN mkdir /code
 WORKDIR /code
@@ -14,16 +17,16 @@ ADD requirements.txt /code/
 RUN pip install -r requirements.txt
 ADD . /code/
 ```
-以上内容指定应用将使用安装了 Python 以及必要依赖包的镜像。更多关于如何编写 Dockerfile 文件的信息可以查看 [镜像创建](../image/create.md#利用 Dockerfile 来创建镜像) 和 [Dockerfile 使用](../dockerfile/README.md)。
 
-第二步，在 `requirements.txt` 文件里面写明需要安装的具体依赖包名 。
+以上内容指定应用将使用安装了 Python 以及必要依赖包的镜像。更多关于如何编写 `Dockerfile` 文件的信息可以查看 [镜像创建](../image/create.md#利用 Dockerfile 来创建镜像) 和 [ Dockerfile 使用](../dockerfile/README.md)。
+
+第二步，在 `requirements.txt` 文件里面写明需要安装的具体依赖包名。
 
 ```bash
-Django
+Django>=1.8,<2.0
 psycopg2
 ```
 
-就是这么简单。  
 第三步，`docker-compose.yml` 文件将把所有的东西关联起来。它描述了应用的构成（一个 web 服务和一个数据库）、使用的 Docker 镜像、镜像之间的连接、挂载到容器的卷，以及服务开放的端口。
 
 ```yaml
@@ -32,9 +35,10 @@ services:
 
   db:
     image: postgres
+
   web:
     build: .
-    command: python manage.py runserver 0.0.0.0:8000
+    command: python3 manage.py runserver 0.0.0.0:8000
     volumes:
       - .:/code
     ports:
@@ -42,14 +46,16 @@ services:
     links:
       - db
 ```
+
 查看 [`docker-compose.yml` 章节](yml_ref.md) 了解更多详细的工作机制。
 
-现在我们就可以使用 `docker-compose run` 命令启动一个 Django 应用了。
+现在我们就可以使用 `docker-compose run` 命令启动一个 `Django` 应用了。
 
 ```bash
 $ docker-compose run web django-admin.py startproject django_example .
 ```
-Compose 会先使用 `Dockerfile` 为 web 服务创建一个镜像，接着使用这个镜像在容器里运行 `django-admin.py startproject django_example . ` 指令。
+
+Compose 会先使用 `Dockerfile` 为 web 服务创建一个镜像，接着使用这个镜像在容器里运行 `django-admin.py startproject composeexample` 指令。
 
 这将在当前目录生成一个 Django 应用。
 
@@ -57,12 +63,19 @@ Compose 会先使用 `Dockerfile` 为 web 服务创建一个镜像，接着使
 $ ls
 Dockerfile       docker-compose.yml          django_example       manage.py       requirements.txt
 ```
-首先，我们要为应用设置好数据库的连接信息。用以下内容替换 `django_example/settings.py` 文件中 `DATABASES = ...` 定义的节点内容。
+
+如果你的系统是 Linux,记得更改文件权限。
 
 ```bash
+sudo chown -R $USER:$USER .
+```
+
+首先，我们要为应用设置好数据库的连接信息。用以下内容替换 `django_example/settings.py` 文件中 `DATABASES = ...` 定义的节点内容。
+
+```python
 DATABASES = {
     'default': {
-        'ENGINE': 'django.db.backends.postgresql_psycopg2',
+        'ENGINE': 'django.db.backends.postgresql',
         'NAME': 'postgres',
         'USER': 'postgres',
         'HOST': 'db',
@@ -70,28 +83,36 @@ DATABASES = {
     }
 }
 ```
-这些信息是在 [postgres](https://registry.hub.docker.com/_/postgres/) Docker 镜像固定设置好的。  
+
-然后，运行 `docker-compose up` ：
+这些信息是在 [postgres](https://store.docker.com/images/postgres/) 镜像固定设置好的。然后，运行 `docker-compose up` ：
 
 ```bash
-Recreating myapp_db_1...
+$ docker-compose up
-Recreating myapp_web_1...
-Attaching to myapp_db_1, myapp_web_1
-myapp_db_1 |
-myapp_db_1 | PostgreSQL stand-alone backend 9.1.11
-myapp_db_1 | 2014-01-27 12:17:03 UTC LOG:  database system is ready to accept connections
-myapp_db_1 | 2014-01-27 12:17:03 UTC LOG:  autovacuum launcher started
-myapp_web_1 | Validating models...
-myapp_web_1 |
-myapp_web_1 | 0 errors found
-myapp_web_1 | January 27, 2014 - 12:12:40
-myapp_web_1 | Django version 1.6.1, using settings 'django_example.settings'
-myapp_web_1 | Starting development server at http://0.0.0.0:8000/
-myapp_web_1 | Quit the server with CONTROL-C.
-```
-这个 web 应用已经开始在你的 docker 守护进程里监听着 5000 端口了。
 
-你还可以在 Docker 上运行其它的管理命令，例如对于同步数据库结构这种事，在运行完 `docker-compose up` 后，在另外一个终端运行以下命令即可：
+django_db_1 is up-to-date
+Creating django_web_1 ...
+Creating django_web_1 ... done
+Attaching to django_db_1, django_web_1
+db_1   | The files belonging to this database system will be owned by user "postgres".
+db_1   | This user must also own the server process.
+db_1   |
+db_1   | The database cluster will be initialized with locale "en_US.utf8".
+db_1   | The default database encoding has accordingly been set to "UTF8".
+db_1   | The default text search configuration will be set to "english".
+
+web_1  | Performing system checks...
+web_1  |
+web_1  | System check identified no issues (0 silenced).
+web_1  |
+web_1  | November 23, 2017 - 06:21:19
+web_1  | Django version 1.11.7, using settings 'django_example.settings'
+web_1  | Starting development server at http://0.0.0.0:8000/
+web_1  | Quit the server with CONTROL-C.
+```
+
+这个 `Django` 应用已经开始在你的 Docker 守护进程里监听着 `8000` 端口了。打开 `127.0.0.1:8000` 即可看到 Django 欢迎页面。
+
+你还可以在 Docker 上运行其它的管理命令，例如对于同步数据库结构这种事，在运行完 `docker-compose up` 后，在另外一个终端进入文件夹运行以下命令即可：
 
 ```bash
 $ docker-compose run web python manage.py syncdb

compose/install.md

@@ -6,7 +6,31 @@ Compose 可以通过 Python 的包管理工具 pip 进行安装，也可以直
 
 前两种方式是传统方式，适合本地环境下安装使用；最后一种方式则不破坏系统环境，更适合云计算场景。
 
+Docker for macOS 、Docker for Windows 自带 `docker-compose` 二进制文件，安装 Docker 之后可以直接使用。
+
+```bash
+$ docker-compose --version
+
+docker-compose version 1.17.1, build 6d101fb
+```
+
+Linux 系统请使用以下介绍的方法安装。
+
+### 二进制包
+
+官方定义编译好二进制包，供大家使用。这些发布的二进制包可以在 [https://github.com/docker/compose/releases](https://github.com/docker/compose/releases) 页面下载。
+
+这些二进制文件，下载后直接放到执行路径下，并添加执行权限即可。
+
+```bash
+$ 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 a+x /usr/local/bin/docker-compose
+```
+
 ### PIP 安装
+
+*注：* `x86_64` 架构的 Linux 建议按照上边的方法下载二进制包进行安装，如果您的架构是 `ARM` (例如，树莓派)，再使用 pip 安装。
+
 这种方式是将 Compose 当作一个 Python 应用来从 pip 源中安装。
 
 执行安装命令：
@@ -16,81 +40,20 @@ $ sudo pip install -U docker-compose
 ```
 
 可以看到类似如下输出，说明安装成功。
+
 ```bash
 Collecting docker-compose
-  Downloading docker-compose-1.8.0.tar.gz (149kB): 149kB downloaded
+  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
 ```
 
-安装成功后，可以查看 `docker-compose` 命令的用法。
+### bash 补全命令
-```bash
-$ docker-compose -h
-Define and run multi-container applications with Docker.
-
-Usage:
-  docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
-  docker-compose -h|--help
-
-Options:
-  -f, --file FILE           Specify an alternate compose file (default: docker-compose.yml)
-  -p, --project-name NAME   Specify an alternate project name (default: directory name)
-  --x-networking            (EXPERIMENTAL) Use new Docker networking functionality.
-                            Requires Docker 1.9 or later.
-  --x-network-driver DRIVER (EXPERIMENTAL) Specify a network driver (default: "bridge").
-                            Requires Docker 1.9 or later.
-  --verbose                 Show more output
-  -v, --version             Print version and exit
-
-Commands:
-  build              Build or rebuild services
-  help               Get help on a command
-  kill               Kill containers
-  logs               View output from containers
-  pause              Pause services
-  port               Print the public port for a port binding
-  ps                 List containers
-  pull               Pulls service images
-  restart            Restart services
-  rm                 Remove stopped containers
-  run                Run a one-off command
-  scale              Set number of containers for a service
-  start              Start services
-  stop               Stop services
-  unpause            Unpause services
-  up                 Create and start containers
-  migrate-to-labels  Recreate containers to add labels
-  version            Show the Docker-Compose version information
-```
-
-之后，可以添加 bash 补全命令。
 
 ```bash
 $ curl -L https://raw.githubusercontent.com/docker/compose/1.8.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 和 macOS 平台上。
-
-```bash
-$ sudo curl -L https://github.com/docker/compose/releases/download/1.8.0/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
-$ sudo chmod a+x /usr/local/bin/docker-compose
-```
-
-可以使用 `docker-compose version` 命令来查看版本信息，以测试是否安装成功。
-
-```bash
-$ docker-compose version
-docker-compose version 1.8.0, build 94f7016
-docker-py version: 1.9.0
-CPython version: 2.7.6
-OpenSSL version: OpenSSL 1.0.1f 6 Jan 2014
-```
-
 ### 容器中执行
 
 Compose 既然是一个 Python 应用，自然也可以直接用容器来执行它。
@@ -149,13 +112,14 @@ exec docker run --rm $DOCKER_RUN_OPTIONS $DOCKER_ADDR $COMPOSE_OPTIONS $VOLUMES
 可以看到，它其实是下载了 `docker/compose` 镜像并运行。
 
 ### 卸载
+
 如果是二进制包方式安装的，删除二进制文件即可。
 
 ```bash
 $ sudo rm /usr/local/bin/docker-compose
 ```
 
-如果是通过 python pip 工具安装的，则可以执行如下命令删除。
+如果是通过 python pip 安装的，则执行如下命令即可删除。
 
 ```bash
 $ sudo pip uninstall docker-compose

compose/introduction.md

@@ -6,15 +6,16 @@ Compose 项目是 Docker 官方的开源项目，负责实现对 Docker 容器
 
 其代码目前在 [https://github.com/docker/compose](https://github.com/docker/compose) 上开源。
 
-Compose 定位是 “定义和运行多个 Docker 容器的应用（Defining and running multi-container Docker applications）”，其前身是开源项目 Fig，目前仍然兼容 Fig 格式的模板文件。
+Compose 定位是 「定义和运行多个 Docker 容器的应用（Defining and running multi-container Docker applications）」，其前身是开源项目 Fig。
 
-通过第一部分中的介绍，我们知道使用一个 Dockerfile 模板文件，可以让用户很方便的定义一个单独的应用容器。然而，在日常工作中，经常会碰到需要多个容器相互配合来完成某项任务的情况。例如要实现一个 Web 项目，除了 Web 服务容器本身，往往还需要再加上后端的数据库服务容器，甚至还包括负载均衡容器等。
+通过第一部分中的介绍，我们知道使用一个 `Dockerfile` 模板文件，可以让用户很方便的定义一个单独的应用容器。然而，在日常工作中，经常会碰到需要多个容器相互配合来完成某项任务的情况。例如要实现一个 Web 项目，除了 Web 服务容器本身，往往还需要再加上后端的数据库服务容器，甚至还包括负载均衡容器等。
 
 Compose 恰好满足了这样的需求。它允许用户通过一个单独的 `docker-compose.yml` 模板文件（YAML 格式）来定义一组相关联的应用容器为一个项目（project）。
 
 Compose 中有两个重要的概念：
 
 * 服务(service)：一个应用的容器，实际上可以包括若干运行相同镜像的容器实例。
+
 * 项目(project)：由一组关联的应用容器组成的一个完整业务单元，在 `docker-compose.yml` 文件中定义。
 
 Compose 的默认管理对象是项目，通过子命令对项目中的一组容器进行便捷地生命周期管理。

compose/rails.md

@@ -1,7 +1,8 @@
 ## 使用 Rail
 
-我们现在将使用 Compose 配置并运行一个 Rails/PostgreSQL 应用。
+本小节内容适合 Ruby 开发人员阅读。
 
+我们现在将使用 Compose 配置并运行一个 Rails/PostgreSQL 应用。
 
 在一切工作开始前，需要先设置好三个必要的文件。  
 首先，因为应用将要运行在一个满足所有环境依赖的 Docker 容器里面，那么我们可以通过编辑 `Dockerfile` 文件来指定 Docker 容器要安装内容。内容如下：
@@ -32,6 +33,7 @@ services:
     image: postgres
     ports:
       - "5432"
+      
   web:
     build: .
     command: bundle exec rackup -p 3000

compose/usage.md

@@ -4,6 +4,7 @@
 首先介绍几个术语。
 
 * 服务 (service)：一个应用容器，实际上可以运行多个相同镜像的实例。
+
 * 项目 (project)：由一组关联的应用容器组成的一个完整业务单元。
 
 可见，一个项目可以由多个服务（容器）关联而成，Compose 面向项目进行管理。
@@ -144,11 +145,12 @@ backend web_backends
     http-check expect status 200
 ```
 ### docker-compose.yml
-编写 docker-compose.yml 文件，这个是 Compose 使用的主模板文件。内容十分简单，指定 3 个 web 容器，以及 1 个 haproxy 容器。
+编写 `docker-compose.yml` 文件，这个是 Compose 使用的主模板文件。内容十分简单，指定 3 个 web 容器，以及 1 个 haproxy 容器。
 
 ```yaml
 version: "3"
 services:
+
   weba:
     build: ./web
     expose:
@@ -169,10 +171,6 @@ services:
     volumes:
         - ./haproxy:/haproxy-override
         - ./haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
-    links:
-        - weba
-        - webb
-        - webc
     ports:
         - "80:80"
         - "70:70"
@@ -182,7 +180,7 @@ services:
 ```
 
 ### 运行 compose 项目
-现在 compose-haproxy-web 目录结构如下：
+现在 `compose-haproxy-web` 目录结构如下：
 ```bash
 compose-haproxy-web
 ├── docker-compose.yml
@@ -206,5 +204,3 @@ Attaching to composehaproxyweb_webb_1, composehaproxyweb_webc_1, composehaproxyw
 此时访问本地的 80 端口，会经过 haproxy 自动转发到后端的某个 web 容器上，刷新页面，可以观察到访问的容器地址的变化。
 
 访问本地 70 端口，可以查看到 haproxy 的统计信息。
-
-当然，还可以使用 consul、etcd 等实现服务发现，这样就可以避免手动指定后端的 web 容器了，更为灵活。

compose/wordpress.md

@@ -1,90 +1,47 @@
-## 使用 Wordpress
+## 使用 WordPress
+
+本小节内容适合 PHP 开发人员阅读。
 
 Compose 可以很便捷的让 Wordpress 运行在一个独立的环境中。
 
-首先下载 Wordpress 到当前目录：
+### 创建空文件夹
 
-```bash
+假设新建一个名为 `wordpress` 的文件夹，然后进入这个文件夹。
-wordpress.org/latest.tar.gz | tar -xvzf -
-```
-这将会创建一个叫 wordpress 目录，你也可以重命名成你想要的名字。在目录里面，创建一个 `Dockerfile` 文件，定义应用的运行环境：
 
-```docker
+### 创建 `docker-compose.yml` 文件
-FROM orchardup/php5
-ADD . /code
-```
-以上内容告诉 Docker 创建一个包含 PHP 和 Wordpress 的镜像。更多关于如何编写 Dockerfile 文件的信息可以查看 [镜像创建](../image/create.md#利用 Dockerfile 来创建镜像) 和 [Dockerfile 使用](../dockerfile/README.md)。
 
-
+`docker-compose.yml` 文件将开启一个 `wordpress` 服务和一个独立的 `MySQL` 实例：
-下一步，`docker-compose.yml` 文件将开启一个 web 服务和一个独立的 MySQL 实例：
 
 ```yaml
 version: "3"
 services:
 
-  web:
-    build: .
-    command: php -S 0.0.0.0:8000 -t /code
-    ports:
-      - "8000:8000"
-    links:
-      - db
-    volumes:
-      - .:/code
    db:
-    image: orchardup/mysql
+     image: mysql:5.7
+     volumes:
+       - db_data:/var/lib/mysql
+     restart: always
      environment:
+       MYSQL_ROOT_PASSWORD: somewordpress
        MYSQL_DATABASE: wordpress
-```
+       MYSQL_USER: wordpress
-要让这个应用跑起来还需要两个文件。
+       MYSQL_PASSWORD: wordpress
-第一个，`wp-condocker-compose.php` ，它是一个标准的 Wordpress 配置文件，有一点需要修改的是把数据库的配置指向 `db` 容器。
 
-```php
+   wordpress:
-<?php
+     depends_on:
-define('DB_NAME', 'wordpress');
+       - db
-define('DB_USER', 'root');
+     image: wordpress:latest
-define('DB_PASSWORD', '');
+     ports:
-define('DB_HOST', "db:3306");
+       - "8000:80"
-define('DB_CHARSET', 'utf8');
+     restart: always
-define('DB_COLLATE', '');
+     environment:
-
+       WORDPRESS_DB_HOST: db:3306
-define('AUTH_KEY',         'put your unique phrase here');
+       WORDPRESS_DB_USER: wordpress
-define('SECURE_AUTH_KEY',  'put your unique phrase here');
+       WORDPRESS_DB_PASSWORD: wordpress
-define('LOGGED_IN_KEY',    'put your unique phrase here');
+volumes:
-define('NONCE_KEY',        'put your unique phrase here');
+    db_data:
-define('AUTH_SALT',        'put your unique phrase here');
-define('SECURE_AUTH_SALT', 'put your unique phrase here');
-define('LOGGED_IN_SALT',   'put your unique phrase here');
-define('NONCE_SALT',       'put your unique phrase here');
-
-$table_prefix  = 'wp_';
-define('WPLANG', '');
-define('WP_DEBUG', false);
-
-if ( !defined('ABSPATH') )
-    define('ABSPATH', dirname(__FILE__) . '/');
-
-require_once(ABSPATH . 'wp-settings.php');
-```
-第二个，`router.php` ，它告诉 PHP 内置的服务器怎么运行 Wordpress:
-
-```php
-<?php
-
-$root = $_SERVER['DOCUMENT_ROOT'];
-chdir($root);
-$path = '/'.ltrim(parse_url($_SERVER['REQUEST_URI'])['path'],'/');
-set_include_path(get_include_path().':'.__DIR__);
-if(file_exists($root.$path))
-{
-    if(is_dir($root.$path) && substr($path,strlen($path) - 1, 1) !== '/')
-        $path = rtrim($path,'/').'/index.php';
-    if(strpos($path,'.php') === false) return false;
-    else {
-        chdir(dirname($root.$path));
-        require_once $root.$path;
-    }
-}else include_once 'index.php';
 ```
 
-这些配置文件就绪后，在你的 Wordpress 目录里面执行 `docker-compose up` 指令，Compose 就会拉取镜像再创建我们所需要的镜像，然后启动 web 和数据库容器。 接着访问 docker 守护进程监听的 8000 端口就能看你的 Wordpress 网站了。
+### 构建并运行项目
+
+运行 `docker-compose up -d` Compose 就会拉取镜像再创建我们所需要的镜像，然后启动 `wordpress` 和数据库容器。 接着浏览器访问 `127.0.0.1:8000` 端口就能看到 WordPress 安装界面了。

compose/yaml_file.md

@@ -4,23 +4,9 @@
 
 默认的模板文件名称为 `docker-compose.yml`，格式为 YAML 格式。
 
-在旧版本（版本 1）中，其中每个顶级元素为服务名称，次级元素为服务容器的配置信息，例如
-
 ```yaml
-webapp:
+version: "3"
-  image: examples/web
-  ports:
-    - "80:80"
-  volumes:
-    - "/data"
-```
 
-版本 2 扩展了 Compose 的语法，同时尽量保持跟版本 1 的兼容，除了可以声明网络和存储信息外，最大的不同一是添加了版本信息，另一个是需要将所有的服务放到 `services` 根下面。
-
-例如，上面例子改写为版本 2，内容为
-
-```yaml
-version: "2"
 services:
   webapp:
     image: examples/web
@@ -30,7 +16,6 @@ services:
       - "/data"
 ```
 
-
 注意每个服务都必须通过 `image` 指令指定镜像或 `build` 指令（需要 Dockerfile）等来自动构建生成镜像。
 
 如果使用 `build` 指令，在 `Dockerfile` 中设置的选项(例如：`CMD`, `EXPOSE`, `VOLUME`, `ENV` 等) 将会自动被获取，无需在 `docker-compose.yml` 中再次设置。
@@ -41,7 +26,7 @@ services:
 
 指定 `Dockerfile` 所在文件夹的路径（可以是绝对路径，或者相对 docker-compose.yml 文件的路径）。 `Compose` 将会利用它自动构建这个镜像，然后使用这个镜像。
 
-```
+```yaml
 build: /path/to/build/dir
 ```
 
@@ -50,14 +35,14 @@ build: /path/to/build/dir
 
 例如，让容器拥有所有能力可以指定为：
 
-```yml
+```yaml
 cap_add:
   - ALL
 ```
 
 去掉 NET_ADMIN 能力可以指定为：
 
-```yml
+```yaml
 cap_drop:
   - NET_ADMIN
 ```
@@ -66,24 +51,23 @@ cap_drop:
 
 覆盖容器启动后默认执行的命令。
 
-```bash
+```yaml
 command: echo "hello world"
 ```
 
 ### `cgroup_parent`
-指定父 cgroup 组，意味着将继承该组的资源限制。
+指定父 `cgroup` 组，意味着将继承该组的资源限制。
 
 例如，创建了一个 cgroup 组名称为 `cgroups_1`。
 
-```yml
+```yaml
 cgroup_parent: cgroups_1
 ```
 
 ### `container_name`
 指定容器名称。默认将会使用 `项目名称_服务名称_序号` 这样的格式。
 
-例如：
+```yaml
-```yml
 container_name: docker-web-container
 ```
 
@@ -92,44 +76,41 @@ container_name: docker-web-container
 ### `devices`
 指定设备映射关系。
 
-例如：
+```yaml
-```yml
 devices:
   - "/dev/ttyUSB1:/dev/ttyUSB0"
 ```
 
+### `depends_on`
+
 ### `dns`
 
-自定义 DNS 服务器。可以是一个值，也可以是一个列表。
+自定义 `DNS` 服务器。可以是一个值，也可以是一个列表。
 
-```bash
+```yaml
 dns: 8.8.8.8
+```
+
+```yaml
 dns:
   - 8.8.8.8
-  - 9.9.9.9
+  - 114.114.114.114
 ```
 
 ### `dns_search`
 
-配置 DNS 搜索域。可以是一个值，也可以是一个列表。
+配置 `DNS` 搜索域。可以是一个值，也可以是一个列表。
 
-```bash
+```yaml
 dns_search: example.com
+```
+
+```yaml
 dns_search:
   - domain1.example.com
   - domain2.example.com
 ```
 
-### `dockerfile`
-如果需要指定额外的编译镜像的 Dockefile 文件，可以通过该指令来指定。
-
-例如
-```yml
-dockerfile: Dockerfile-alternate
-```
-
-注意，该指令不能跟 `image` 同时使用，否则 Compose 将不知道根据哪个指令来生成最终的服务镜像。
-
 ### `env_file`
 从文件中获取环境变量，可以为单独的文件路径或列表。
 
@@ -159,16 +140,13 @@ PROG_ENV=development
 
 只给定名称的变量会自动获取运行 Compose 主机上对应变量的值，可以用来防止泄露不必要的数据。
 
-例如
+```yaml
-```yml
 environment:
   RACK_ENV: development
   SESSION_SECRET:
 ```
 
-或者
+```yaml
-
-```yml
 environment:
   - RACK_ENV=development
   - SESSION_SECRET
@@ -179,9 +157,7 @@ environment:
 `http://yaml.org/type/bool.html` 中给出了这些特定词汇，包括
 
 ```bash
- y|Y|yes|Yes|YES|n|N|no|No|NO
+y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF
-|true|True|TRUE|false|False|FALSE
-|on|On|ON|off|Off|OFF
 ```
 
 ### `expose`
@@ -190,54 +166,16 @@ environment:
 
 仅可以指定内部端口为参数
 
-```bash
+```yaml
 expose:
  - "3000"
  - "8000"
 ```
 
-### `extends`
-基于其它模板文件进行扩展。
-
-例如我们已经有了一个 webapp 服务，定义一个基础模板文件为 `common.yml`。
-```bash
-# common.yml
-webapp:
-  build: ./webapp
-  environment:
-    - DEBUG=false
-    - SEND_EMAILS=false
-```
-
-再编写一个新的 `development.yml` 文件，使用 `common.yml` 中的 webapp 服务进行扩展。
-```bash
-# development.yml
-web:
-  extends:
-    file: common.yml
-    service: webapp
-  ports:
-    - "8000:8000"
-  links:
-    - db
-  environment:
-    - DEBUG=true
-db:
-  image: postgres
-```
-后者会自动继承 common.yml 中的 webapp 服务及环境变量定义。
-
-使用 extends 需要注意：
-
-* 要避免出现循环依赖，例如 `A 依赖 B，B 依赖 C，C 反过来依赖 A` 的情况。
-* extends 不会继承 links 和 volumes_from 中定义的容器和数据卷资源。
-
-一般的，推荐在基础模板中只定义一些可以共享的镜像和环境变量，在扩展模板中具体指定应用变量、链接、数据卷等信息。
-
 ### `external_links`
 链接到 docker-compose.yml 外部的容器，甚至 并非 `Compose` 管理的外部容器。参数格式跟 `links` 类似。
 
-```
+```yaml
 external_links:
  - redis_1
  - project_db_1:mysql
@@ -247,25 +185,27 @@ external_links:
 ### `extra_hosts`
 类似 Docker 中的 `--add-host` 参数，指定额外的 host 名称映射信息。
 
-例如：
+```yaml
-```yml
 extra_hosts:
  - "googledns:8.8.8.8"
  - "dockerhub:52.1.157.61"
 ```
 
 会在启动后的服务容器中 `/etc/hosts` 文件中添加如下两条条目。
+
 ```bash
 8.8.8.8 googledns
 52.1.157.61 dockerhub
 ```
 
+### `healthcheck`
+
 ### `image`
 
 指定为镜像名称或镜像 ID。如果镜像在本地不存在，`Compose` 将会尝试拉去这个镜像。
 
 例如：
-```bash
+```yaml
 image: ubuntu
 image: orchardup/postgresql
 image: a4bc65fd
@@ -273,7 +213,7 @@ image: a4bc65fd
 
 ### `labels`
 为容器添加 Docker 元数据（metadata）信息。例如可以为容器添加辅助说明信息。
-```yml
+```yaml
 labels:
   com.startupteam.description: "webapp for a startup team"
   com.startupteam.department: "devops department"
@@ -301,12 +241,12 @@ links:
 
 被链接容器中相应的环境变量也将被创建。
 
-### `log_driver`
+### `logging`
 类似 Docker 中的 `--log-driver` 参数，指定日志驱动类型。
 
 目前支持三种日志驱动类型。
 
-```yml
+```yaml
 log_driver: "json-file"
 log_driver: "syslog"
 log_driver: "none"
@@ -315,18 +255,17 @@ log_driver: "none"
 ### `log_opt`
 日志驱动的相关参数。
 
-例如
+```yaml
-```yml
 log_driver: "syslog"
 log_opt:
   syslog-address: "tcp://192.168.0.42:123"
 ```
 
-### `net`
+### `networks`
 
-设置网络模式。使用和 `docker client` 的 `--net` 参数一样的值。
+设置网络模式。使用和 `docker run` 的 `--net` 参数一样的值。
 
-```bash
+```yaml
 net: "bridge"
 net: "none"
 net: "container:[name or id]"
@@ -336,7 +275,7 @@ net: "host"
 ### `pid`
 跟主机系统共享进程命名空间。打开该选项的容器之间，以及容器和宿主机系统之间可以通过进程 ID 来相互访问和操作。
 
-```bash
+```yaml
 pid: "host"
 ```
 
@@ -347,7 +286,7 @@ pid: "host"
 
 使用宿主：容器 `（HOST:CONTAINER）`格式，或者仅仅指定容器的端口（宿主将会随机选择端口）都可以。
 
-```
+```yaml
 ports:
  - "3000"
  - "8000:8000"
@@ -362,7 +301,7 @@ ports:
 指定容器模板标签（label）机制的默认属性（用户、角色、类型、级别等）。
 
 例如配置标签的用户名和角色名。
-```yml
+```yaml
 security_opt:
     - label:user:USER
     - label:role:ROLE
@@ -373,7 +312,7 @@ security_opt:
 
 例如，指定最大进程数为 65535，指定文件句柄数为 20000（软限制，应用可以随时修改，不能超过硬限制） 和 40000（系统硬限制，只能 root 用户提高）。
 
-```yml
+```yaml
   ulimits:
     nproc: 65535
     nofile:
@@ -385,110 +324,78 @@ security_opt:
 
 数据卷所挂载路径设置。可以设置宿主机路径 （`HOST:CONTAINER`） 或加上访问模式 （`HOST:CONTAINER:ro`）。
 
-该指令中路径支持相对路径。例如
+该指令中路径支持相对路径。
 
-```yml
+```yaml
 volumes:
  - /var/lib/mysql
  - cache/:/tmp/cache
  - ~/configs:/etc/configs/:ro
 ```
 
-### `volumes_driver`
-较新版本的 Docker 支持数据卷的插件驱动。
-
-用户可以先使用第三方驱动创建一个数据卷，然后使用名称来访问它。
-
-此时，可以通过 `volumes_driver` 来指定驱动。
-
-```yml
-volume_driver: mydriver
-```
-
-### `volumes_from`
-
-从另一个服务或容器挂载它的数据卷。
-
-```bash
-volumes_from:
- - service_name
- - container_name
-```
-
 ### 其它指令
 
-此外，还有包括 `cpu_shares, cpuset, domainname, entrypoint, hostname, ipc, mac_address, mem_limit, memswap_limit, privileged, read_only, restart, stdin_open, tty, user, working_dir` 等指令，基本跟 docker-run 中对应参数的功能一致。
+此外，还有包括 `domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir` 等指令，基本跟 `docker run` 中对应参数的功能一致。
 
-例如，指定使用 cpu 核 0 和 核 1，只用 50% 的 CPU 资源：
+指定服务容器启动后执行的入口文件。
-```yml
+```yaml
-cpu_shares: 73
-cpuset: 0,1
-```
-
-指定服务容器启动后执行的命令。
-```yml
 entrypoint: /code/entrypoint.sh
 ```
 
 指定容器中运行应用的用户名。
-```yml
+```yaml
 user: nginx
 ```
 
 指定容器中工作目录。
-```yml
+```yaml
 working_dir: /code
 ```
 
 指定容器中搜索域名、主机名、mac 地址等。
-```yml
+```yaml
 domainname: your_website.com
 hostname: test
 mac_address: 08-00-27-00-0C-0A
 ```
 
 指定容器中
-```yml
+```yaml
 ipc: host
 ```
 
-指定容器中内存和内存交换区限制都为 1G。
-```yml
-mem_limit: 1g
-memswap_limit: 1g
-```
-
 允许容器中运行一些特权命令。
-```yml
+```yaml
 privileged: true
 ```
 
 指定容器退出后的重启策略为始终重启。该命令对保持服务始终运行十分有效，在生产环境中推荐配置为 `always` 或者 `unless-stopped`。
-```yml
+```yaml
 restart: always
 ```
 
 以只读模式挂载容器的 root 文件系统，意味着不能对容器内容进行修改。
-```yml
+```yaml
 read_only: true
 ```
 
 打开标准输入，可以接受外部输入。
-```yml
+```yaml
 stdin_open: true
 ```
 
 模拟一个假的远程控制台。
-```yml
+```yaml
 tty: true
 ```
 
 ### 读取环境变量
-从 1.5.0 版本开始，Compose 模板文件支持动态读取主机的系统环境变量。
+
+Compose 模板文件支持动态读取主机的系统环境变量。
 
 例如，下面的 Compose 文件将从运行它的环境中读取变量 ${MONGO_VERSION} 的值，并写入执行的指令中。
 
-```yml
+```yaml
 db:
   image: "mongo:${MONGO_VERSION}"
 ```

revision.md

@@ -16,7 +16,7 @@
   * 增加 Dockerfile `multistage builds` 多阶段构建 `Dcoker 17.05` 新增特性
   * 更新 `Docker 网络` 一节
   * 更新 `Docker Machine` 基于 0.13.0 版本
-  * 更新 `Docker Compose` 基于 3.4 文件格式
+  * 更新 `Docker Compose` 基于 3 文件格式
   * 删除 Docker Swarm 相关内容，替换为 `Swarm mode` `Docker 1.12.0` 新增特性
   * 精简 `Docker Registry` 一节
   * 删除 `docker run` `--link` 参数