Dockerfile 文件介绍 (整理）

概述

• Docker 可以通过 Dockerfile 的内容来自动构建镜像。
  Dockerfile 是一个包含创建镜像所有命令的文本文件，通过 docker build 命令可以根据 Dockerfile 的内容构建镜像。

一、基本结构：

• Dockerfile 由一行行命令语句组成，并且支持以 # 开头的注释行。 一般分为四部分：
  1、基础镜像信息
  2、维护者信息
  3、镜像操作指令
  4、容器启动时执行指令

# This dockerfile uses the ubuntu image            
# VERSION 2 - EDITION 1
# Author: docker_user
# Command format: Instruction [arguments / command] .. 

# Base image to use, this must be set as the first line
FROM ubuntu        # 基础镜像信息

# Maintainer: docker_user <docker_user at email.com> (@docker_user)
MAINTAINER docker_user docker_user@email.com        # 维护者信息

# Commands to update the image            # 镜像操作指令
RUN echo "deb http://archive.ubuntu.com/ubuntu/ raring main universe" >> /etc/apt/sources.list
RUN apt-get update && apt-get install -y nginx
RUN echo "\ndaemon off;" >> /etc/nginx/nginx.conf

# Commands when creating a new container
CMD /usr/sbin/nginx        # 容器启动时执行指令

• 其中，一开始必须指明所基于的镜像名称，接下来推荐说明维护者信息。后面则是镜像操作指令，例如 RUN 指令，RUN 指令将对镜像执行跟随的命令。每运行一条 RUN 指令，镜像添加新的一层，并提交。最后是 CMD 指令，来指定运行容器时的操作命令。

# Nginx
#
# VERSION               0.0.1

FROM      ubuntu
MAINTAINER Victor Vieux <victor@docker.com>

RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server

# Firefox over VNC
#
# VERSION               0.3

FROM ubuntu

# Install vnc, xvfb in order to create a 'fake' display and firefox
RUN apt-get update && apt-get install -y x11vnc xvfb firefox
RUN mkdir /.vnc
# Setup a password
RUN x11vnc -storepasswd 1234 ~/.vnc/passwd
# Autostart firefox (might not be the best way, but it does the trick)
RUN bash -c 'echo "firefox" >> /.bashrc'

EXPOSE 5900
CMD    ["x11vnc", "-forever", "-usepw", "-create"]

# Multiple images example
#
# VERSION               0.1

FROM ubuntu
RUN echo foo > bar
# Will output something like ===> 907ad6c2736f

FROM ubuntu
RUN echo moo > oink
# Will output something like ===> 695d7793cbe4

# You᾿ll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with
# /oink.

二、指令

• 指令的一般格式为 INSTRUCTION arguments，指令包括 FROM、MAINTAINER、RUN 等，指令名称必须全部大写。

  1. FROM               # 基础镜像，一切从这里开始构建
  2. MAINTAINER         # 镜像作者：姓名+邮箱
  3. RUN                # 镜像构建的时候需要运行的命令
  4. ADD                # 步骤。（tomcat镜像的压缩包就是一种添加内容）
  5. WORKDIR            # 镜像的工作目录
  6. VOLUME             # 挂载的目录
  7. EXPOSE             # 暴露端口配置
  8. CMD                # 指定这个容器启动的时候要运行的命令，只有最后一个会生效，可被替代 （替换）
  9. ENTRYPOINT         # 指定这个容器启动的时候要运行的命令，可以直接追加命令 （追加）
  10. ONBUILD           # 当构建一个被继承 DockerFile ，这个时候就会运行 ONBUILD 的指令，是一种触发指令
  11. COPY              # 类似ADD命令，将我们的文件拷贝到镜像中
  12. ENV               # 构建的时候设置环境变量

2.1 FROM

• 格式为 FROM <image> 或 FROM <image>:<tag>。
  1、FROM 指定构建镜像的基础源镜像，如果本地没有指定的镜像，则会自动从 Docker 的公共库 pull 镜像下来。
  2、FROM 必须是 Dockerfile 中非注释行的第一个指令，即一个 Dockerfile 从 FROM 语句开始。
  3、FROM 可以在一个 Dockerfile 中出现多次，如果有需求在一个 Dockerfile 中创建多个镜像。
  4、如果 FROM 语句没有指定镜像标签，则默认使用 latest 标签。

2.2 MAINTAINER

• 格式为 MAINTAINER <name>，指定维护者信息。

2.3 RUN

• 格式为 RUN <command> 或 RUN ["executable", "param1", "param2"]。
  1、前者将在 shell 终端中运行命令，即 /bin/sh -c；后者则使用 exec 执行。指定使用其它终端可以通过第二种方式实现，例如 RUN ["/bin/bash", "-c", "echo hello"]。
  2、每条 RUN 指令将在当前镜像基础上执行指定命令，并提交为新的镜像。当命令较长时可以使用\ 来换行。
  3、RUN 产生的缓存在下一次构建的时候是不会失效的，会被重用，可以使用 --no-cache 选项，即 docker build --no-cache，如此便不会缓存。

2.4 CMD

• 支持三种格式

CMD ["executable","param1","param2"]    # 使用 exec 执行，推荐方式；
CMD command param1 param2    # 在 /bin/sh 中执行，提供给需要交互的应用；
CMD ["param1","param2"]     # 提供给 ENTRYPOINT 的默认参数；

1、指定启动容器时执行的命令，每个 Dockerfile 只能有一条 CMD 命令。如果指定了多条命令，只有最后一条会被执行。
2、如果用户启动容器时候指定了运行的命令，则会覆盖掉 CMD 指定的命令。

CMD 会在启动容器的时候执行，build 时不执行，而 RUN 只是在构建镜像的时候执行，后续镜像构建完成之后，启动容器就与 RUN 无关了，这个初学者容易弄混这个概念，这里简单注解一下。

2.5 EXPOSE

• 格式为 EXPOSE <port> [<port>...]。
  告诉 Docker 服务端容器暴露的端口号，供互联系统使用。在启动容器时需要通过 -P，Docker 主机会自动分配一个端口转发到指定的端口。

2.6 ENV

• 格式为 ENV <key> <value>。

ENV <key> <value>       # 只能设置一个变量
ENV <key>=<value> ...   # 允许一次设置多个变量

ENV myName="John Doe" myDog=Rex\ The\ Dog \
    myCat=fluffy
# 等同于
ENV myName John Doe
ENV myDog Rex The Dog
ENV myCat fluffy

• 指定一个环境变量，会被后续 RUN 指令使用，并在容器运行时保持。例如：

ENV PG_MAJOR 9.3
ENV PG_VERSION 9.3.4
RUN curl -SL http://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress && …
ENV PATH /usr/local/postgres-$PG_MAJOR/bin:$PATH

2.7 ADD

• 格式为 ADD <src> <dest>。
  该命令将复制指定的 <src> 到容器中的 <dest>。
  其中 <src> 可以是 Dockerfile 所在目录的一个相对路径；
  也可以是一个 URL；
  还可以是一个 tar 文件（自动解压为目录）。
• 支持通过 GO 的正则模糊匹配

ADD hom* /mydir/        # adds all files starting with "hom"
ADD hom?.txt /mydir/    # ? is replaced with any single character

• 路径必须是绝对路径，如果不存在，会自动创建对应目录
• 路径必须是 Dockerfile 所在路径的相对路径
• 如果是一个目录，只会复制目录下的内容，而目录本身则不会被复制

2.8 COPY

• 格式为 COPY <src> <dest>。
  复制本地主机的 <src>（为 Dockerfile 所在目录的相对路径）到容器中的 <dest>。
  当使用本地目录为源目录时，推荐使用 COPY。

2.9 ENTRYPOINT

• 两种格式：

ENTRYPOINT ["executable", "param1", "param2"]
ENTRYPOINT command param1 param2（shell中执行）。

• Exec form ENTRYPOINT 示例

FROM ubuntu
ENTRYPOINT ["top", "-b"]
CMD ["-c"]

• Shell form ENTRYPOINT 示例
  这种方式会在 /bin/sh -c中执行，会忽略任何 CMD 或者 docker run 命令行选项，为了确保 docker stop 能够停止长时间运行 ENTRYPOINT 的容器，确保执行的时候使用 exec 选项。

FROM ubuntu
ENTRYPOINT exec top -b

• 如果在 ENTRYPOINT忘记使用 exec 选项，则可以使用 CMD 补上:

FROM ubuntu
ENTRYPOINT top -b
CMD --ignored-param1 # --ignored-param2 ... --ignored-param3 ... 依此类推

• 配置容器启动后执行的命令，并且不可被 docker run 提供的参数覆盖。
• 每个 Dockerfile 中只能有一个 ENTRYPOINT，当指定多个时，只有最后一个起效。

2.10 VOLUME

• 格式为 VOLUME ["<路径1>", "<路径2>"...] 或 VOLUME <路径>
  创建一个可以从本地主机或其他容器挂载的挂载点，一般用来存放数据库和需要保持的数据等。

VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"]

2.11 USER

• 格式为 USER daemon。
  指定运行容器时的用户名或 UID，后续的 RUN 、CMD、ENTRYPOINT也会使用指定用户。
• 当服务不需要管理员权限时，可以通过该命令指定运行用户。并且可以在之前创建所需要的用户，例如：

RUN groupadd -r postgres && useradd -r -g postgres postgres

• 要临时获取管理员权限可以使用 gosu，而不推荐 sudo。

2.12 WORKDIR

• 格式为 WORKDIR /path/to/workdir。
  为后续的 RUN、CMD、ENTRYPOINT 指令配置工作目录。
  可以使用多个 WORKDIR 指令，后续命令如果参数是相对路径，则会基于之前命令指定的路径。例如：

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

• 则最终路径为 /a/b/c。
• WORKDIR 指令可以在 ENV 设置变量之后调用环境变量:

ENV DIRPATH /path
ENV DIRNAME test
WORKDIR $DIRPATH/$DIRNAME

• 最终路径则为 /path/test

2.13 ONBUILD

• 格式为 ONBUILD [INSTRUCTION]。
• 配置当所创建的镜像，作为其它新创建镜像的基础镜像时，所执行的操作指令。
  例如，Dockerfile 使用如下的内容创建了镜像 image-A。

[...]
ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
[...]

• 如果基于 image-A 创建新的镜像时，新的 Dockerfile 中使用 FROM image-A指定基础镜像时，会自动执行 ONBUILD 指令内容，等价于在后面添加了两条指令。

FROM image-A

#Automatically run the following
ADD . /app/src
RUN /usr/local/bin/python-build --dir /app/src

• 使用 ONBUILD 指令的镜像，推荐在标签中注明，例如 ruby:1.9-onbuild。

3、创建镜像

• 编写完成 Dockerfile 之后，可以通过 docker build 命令来创建镜像。

[root@VM-0-6-centos ~]# docker build --help

Usage:  docker build [OPTIONS] PATH | URL | -

Build an image from a Dockerfile

Options:
      --add-host list           Add a custom host-to-IP mapping (host:ip)
      --build-arg list          Set build-time variables
      --cache-from strings      Images to consider as cache sources
      --cgroup-parent string    Optional parent cgroup for the container
      --compress                Compress the build context using gzip
      --cpu-period int          Limit the CPU CFS (Completely Fair Scheduler) period
      --cpu-quota int           Limit the CPU CFS (Completely Fair Scheduler) quota
  -c, --cpu-shares int          CPU shares (relative weight)
      --cpuset-cpus string      CPUs in which to allow execution (0-3, 0,1)
      --cpuset-mems string      MEMs in which to allow execution (0-3, 0,1)
      --disable-content-trust   Skip image verification (default true)
  -f, --file string             Name of the Dockerfile (Default is 'PATH/Dockerfile')
      --force-rm                Always remove intermediate containers
      --iidfile string          Write the image ID to the file
      --isolation string        Container isolation technology
      --label list              Set metadata for an image
  -m, --memory bytes            Memory limit
      --memory-swap bytes       Swap limit equal to memory plus swap: '-1' to enable unlimited swap
      --network string          Set the networking mode for the RUN instructions during build (default "default")
      --no-cache                Do not use cache when building the image
      --pull                    Always attempt to pull a newer version of the image
  -q, --quiet                   Suppress the build output and print image ID on success
      --rm                      Remove intermediate containers after a successful build (default true)
      --security-opt strings    Security options
      --shm-size bytes          Size of /dev/shm
  -t, --tag list                Name and optionally a tag in the 'name:tag' format
      --target string           Set the target build stage to build.
      --ulimit ulimit           Ulimit options (default [])

• 基本的格式为 docker build [选项] 路径，该命令将读取指定路径下（包括子目录）的 Dockerfile，并将该路径下所有内容发送给 Docker 服务端，由服务端来创建镜像。
• 因此一般建议放置 Dockerfile 的目录为空目录。也可以通过 .dockerignore 文件（每一行添加一条匹配模式）来让 Docker 忽略路径下的目录和文件。
• 要指定镜像的标签信息，可以通过 -t 选项，例如：

[root@VM-0-6-centos ~]# docker build -t nginx:v3 .        # 未尾的 . 不能省略

注：最后的 .代表本次执行的上下文路径，不能省略

4. 补充

• 使用.dockerignore文件：相关连接
  为了在 docker build 过程中更快上传和更加高效，应该使用一个 .dockerignore 文件用来排除构建镜像时不需要的文件或目录。例如,除非 . Git 在构建过程中需要用到，否则你应该将它添加到 .dockerignore 文件中，这样可以节省很多时间。

• 避免安装不必要的软件包
  为了降低复杂性、依赖性、文件大小以及构建时间，应该避免安装额外的或不必要的包。例如，不需要在一个数据库镜像中安装一个文本编辑器。

• 每个容器都只跑一个进程
  在大多数情况下，一个容器应该只单独跑一个程序。解耦应用到多个容器使其更容易横向扩展和重用。如果一个服务依赖另外一个服务，可以参考 Linking Containers Together 。

• 最小化层
  我们知道每执行一个指令，都会有一次镜像的提交，镜像是分层的结构，对于Dockerfile，应该找到可读性和最小化层之间的平衡。

• 多行参数排序
  如果可能，通过字母顺序来排序，这样可以避免安装包的重复并且更容易更新列表，另外可读性也会更强，添加一个空行使用\换行:

RUN apt-get update && apt-get install -y \
  bzr \
  cvs \
  git \
  mercurial \
  subversion

• 创建缓存
  镜像构建过程中会按照 Dockerfile 的顺序依次执行，每执行一次指令 Docker 会寻找是否有存在的镜像缓存可复用，如果没有则创建新的镜像。如果不想使用缓存，则可以在 docker build 时添加 --no-cache = true 选项。

• 从基础镜像开始就已经在缓存中了，下一个指令会对比所有的子镜像寻找是否执行相同的指令，如果没有则缓存失效。在大多数情况下只对比 Dockerfile 指令和子镜像就足够了。ADD 和 COPY 指令除外，执行 ADD 和 COPY 时存放到镜像的文件也是需要检查的，完成一个文件的校验之后再利用这个校验在缓存中查找，如果检测的文件改变则缓存失效。RUN apt-get -y update 命令只检查命令是否匹配，如果匹配就不会再执行更新了。

  为了有效地利用缓存，你需要保持你的 Dockerfile 一致，并且尽量在末尾修改。

• Dockerfile 指令

  1. FROM: 只要可能就使用官方镜像库作为基础镜像
  2. RUN: 为保持可读性、方便理解、可维护性，把长或者复杂的 RUN 语句使用\分隔符分成多行
     • 不建议 RUN apt-get update 独立成行，否则如果后续包有更新，那么也不会再执行更新
     • 避免使用 RUN apt-get upgrade 或者 dist-upgrade ，很多必要的包在一个非privileged 权限的容器里是无法升级的。如果知道某个包更新，使用 apt-get install -y xxx
     • 标准写法
       RUN apt-get update && apt-get install -y package-bar package-foo
     • 例子:

       RUN apt-get update && apt-get install -y \
           aufs-tools \
           automake \
           btrfs-tools \
           build-essential \
           curl \
           dpkg-sig \
           git \
           iptables \
           libapparmor-dev \
           libcap-dev \
           libsqlite3-dev \
           lxc=1.0* \
           mercurial \
           parallel \
           reprepro \
           ruby1.9.1 \
           ruby1.9.1-dev \
           s3cmd=1.1.0*
       

  3. CMD: 推荐使用 CMD [“executable”, “param1”, “param2”…] 这种格式，CMD [“param”, “param”]则配合 ENTRYPOINT 使用
  4. EXPOSE: Dockerfile 指定要公开的端口，使用 docker run 时指定映射到宿主机的端口即可
  5. ENV: 为了使新的软件更容易运行，可以使用 ENV 更新 PATH 变量。如 ENV PATH /usr/local/nginx/bin:$PATH 确保 CMD ["nginx"] 即可运行
     ENV也可以这样定义变量：

       ENV PG_MAJOR 9.3
       ENV PG_VERSION 9.3.4
       RUN curl -SL http://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress && …
       ENV PATH /usr/local/postgres-$PG_MAJOR/bin:$PATH
     

  6. ADD or COPY: ADD 比 COPY 多一些特性「tar 文件自动解包和支持远程 URL」，不推荐添加远程 URL

     • 不推荐这种方式:

       ADD http://example.com/big.tar.xz /usr/src/things/
       RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things
       RUN make -C /usr/src/things all
       

     • 推荐使用 curl 或者 wget 替换，使用如下方式:

       RUN mkdir -p /usr/src/things \
         && curl -SL http://example.com/big.tar.gz \
         | tar -xJC /usr/src/things \
         && make -C /usr/src/things all
       

     • 如果不需要添加 tar 文件，推荐使用 COPY 。