Шпаргалка по Dockerfile

EXPOSE

EXPOSE <port> [<port>...]

Инструкция EXPOSE указывает Docker что контейнер слушает определенные порты после запуска. EXPOSE не делает порты контейнера доступными для хоста. Для этого, вы должны использовать флаг -p (что бы открыть диапазон портов) или флаг -P что бы открыть все порты из EXPOSE. Можно задать один номер порта и пробросить его на другой внешний порт.

Docker поддерживает создание сетей без необходимости открытия портов.

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

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

ADD test relativeDir/       # adds "test" to `WORKDIR`/relativeDir/
ADD test /absoluteDir/   # adds "test" to /absoluteDir/

COPY hom* /mydir/      # adds all files starting with "hom"
COPY hom?.txt /mydir/  # ? is replaced with any single character, e.g., "home.txt"

COPY test relativeDir/   # adds "test" to `WORKDIR`/relativeDir/
COPY test /absoluteDir/  # adds "test" to /absoluteDir/

docker run -i -t --rm -p 80:80 nginx

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

$ docker run -it --rm --name test  top -H
top - 08:25:00 up  7:27,  0 users,  load average: 0.00, 0.01, 0.05
Threads:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
%Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
KiB Mem:   2056668 total,  1616832 used,   439836 free,    99352 buffers
KiB Swap:  1441840 total,        0 used,  1441840 free.  1324440 cached Mem

  PID USER      PR  NI    VIRT    RES    SHR S %CPU %MEM     TIME+ COMMAND
    1 root      20   0   19744   2336   2080 R  0.0  0.1   0:00.04 top

$ docker exec -it test ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  2.6  0.1  19752  2352 ?        Ss+  08:24   0:00 top -b -H
root         7  0.0  0.1  15572  2164 ?        R+   08:25   0:00 ps aux

FROM debian:stable
RUN apt-get update && apt-get install -y --force-yes apache2
EXPOSE 80 443
VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"]
ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]

#!/bin/bash
set -e

if [ "$1" = 'postgres' ]; then
    chown -R postgres "$PGDATA"

    if [ -z "$(ls -A "$PGDATA")" ]; then
        gosu postgres initdb
    fi

    exec gosu postgres "$@"
fi

exec "$@"

#!/bin/sh
# Note: I've written this using sh so it works in the busybox container too

# USE the trap if you need to also do manual cleanup after the service is stopped,
#     or need to start multiple services in the one container
trap "echo TRAPed signal" HUP INT QUIT TERM

# start service in background here
/usr/sbin/apachectl start

echo "[hit enter key to exit] or run 'docker stop <container>'"
read

# stop service and clean up here
echo "stopping apache"
/usr/sbin/apachectl stop

echo "exited $0"

$ docker exec -it test ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.1  0.0   4448   692 ?        Ss+  00:42   0:00 /bin/sh /run.sh 123 cmd cmd2
root        19  0.0  0.2  71304  4440 ?        Ss   00:42   0:00 /usr/sbin/apache2 -k start
www-data    20  0.2  0.2 360468  6004 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k start
www-data    21  0.2  0.2 360468  6000 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k start
root        81  0.0  0.1  15572  2140 ?        R+   00:44   0:00 ps aux

$ docker top test
PID                 USER                COMMAND
10035               root                {run.sh} /bin/sh /run.sh 123 cmd cmd2
10054               root                /usr/sbin/apache2 -k start
10055               33                  /usr/sbin/apache2 -k start
10056               33                  /usr/sbin/apache2 -k start

$ /usr/bin/time docker stop test
test
real    0m 0.27s
user    0m 0.03s
sys 0m 0.03s

FROM ubuntu
ENTRYPOINT exec top -b

$ docker run -it --rm --name test top
Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached
CPU:   5% usr   0% sys   0% nic  94% idle   0% io   0% irq   0% sirq
Load average: 0.08 0.03 0.05 2/98 6
  PID  PPID USER     STAT   VSZ %VSZ %CPU COMMAND
    1     0 root     R     3164   0%   0% top -b

$ /usr/bin/time docker stop test
test
real    0m 0.20s
user    0m 0.02s
sys 0m 0.04s

FROM ubuntu
ENTRYPOINT top -b
CMD --ignored-param1

$ docker run -it --name test top --ignored-param2
Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached
CPU:   9% usr   2% sys   0% nic  88% idle   0% io   0% irq   0% sirq
Load average: 0.01 0.02 0.05 2/101 7
  PID  PPID USER     STAT   VSZ %VSZ %CPU COMMAND
    1     0 root     S     3168   0%   0% /bin/sh -c top -b cmd cmd2
    7     1 root     R     3164   0%   0% top -b

$ docker exec -it test ps aux
PID   USER     COMMAND
    1 root     /bin/sh -c top -b cmd cmd2
    7 root     top -b
    8 root     ps aux

$ /usr/bin/time docker stop test
test
real    0m 10.19s
user    0m 0.04s
sys 0m 0.03s

VOLUME

VOLUME ["/data"]

Инструкция VOLUME создает точку монтирования с заданным именем и помечает его как внешний смонтированный том из базового хоста или контейнера. Можно использовать JSON массив, VOLUME ["/var/log/"], или текстовую строку с несколькими аргументами, например VOLUME /var/log или VOLUME /var/log /var/db. 

Команда docker run инициализирует новый том с любыми данными которые существуют в указанном месте в пределах базового образа. К примеру, рассмотрим следующий фрагмент кода из Dockerfile:

FROM ubuntu
RUN mkdir /myvol
RUN echo "hello world" > /myvol/greeting
VOLUME /myvol

В результате запуска образа собранного из данного Dockerfile командой docker run, будет создана новая точка монтирования /myvol и в ней будет создан файл greeting.

Примечание: Если в процессе каких либо шагов сборки будут изменены данные после объявления тома, то эти изменения будут потеряны.

Примечание: Список обрабатывается как JSON массив, что подразумевает обязательное заключение слов в двойные кавычки (") и ни в коем случае одинарные (').

USER

USER daemon

Инструкция USER устанавливает имя пользователя (UID) от имени которого будет запущен образ, а также инструкции RUN, CMD и ENTRYPOINT содержащиеся в Dockerfile.

WORKDIR

WORKDIR /path/to/workdir

Инструкция WORKDIR устанавливает рабочий каталог для всех инструкций RUN, CMD, ENTRYPOINT, COPY и ADD которые будут выполнены в Dockerfile. Если WORKDIR не задана, то она будет создана даже если в Dockerfile нет ни одной инструкции для которой это необходимо.

Инструкция может быть использована несколько раз в одном Dockerfile. Если указывается относительный путь, он будет определен относительно предыдущего значения WORKDIR. К примеру:

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

В результате команда pwd из Dockerfile вернет значение /a/b/c.

Инструкция WORKDIR может использовать переменные окружения заданные через ENV. Вы можете использовать переменные окружения явно заданные в Dockerfile. К примеру:

ENV DIRPATH /path
WORKDIR $DIRPATH/$DIRNAME
RUN pwd

В результате команда pwd в этом Dockerfile вернет /path/$DIRNAME

ARG

ARG <name>[=<default value>]

Инструкция ARG задает переменные которые пользователь передает сборщику образа docker build с помощью флага --build-arg <varname>=<value>. Если пользователь указывает аргумент сборки, который не был определен в Dockerfile, сборка выдает ошибку.

One or more build-args were not consumed, failing build.

Автор Dockerfile может задать одну переменную задав ARG один раз или несколько переменных использовав ARGнесколько раз. Рассмотрим пример корректного Dockerfile:

FROM busybox
ARG user1
ARG buildno
...

Автор Dockerfile может опционально задать значение по умолчанию для переменной с помощью инструкции ARG:

FROM busybox
ARG user1=someuser
ARG buildno=1
...

Если ARG имеет значение по умолчанию и значение данной переменной не задано при сборке, сборщик использует значение по умолчанию.

Задание переменной с помощью инструкции ARG вступает в силу начинаю со строки на которой она была определена в Dockerfile, а не с момента использования в командной строке или где-то еще. Например рассмотрим следующий Dockerfile:

1 FROM busybox
2 USER ${user:-some_user}
3 ARG user
4 USER $user
...

Далее произведем сборку вызвав команду:

$ docker build --build-arg user=what_user Dockerfile

Инструкция USER в строке 2 принимает значение some_user поскольку переменная user задается только в 3 строке. Инструкция USER в строке 4 принимает значение what_user поскольку переменной user было задано значение what_user. До определения с помощью инструкции ARG, любое использование переменной возвращает пустую строку.

Предупреждение: Не рекомендуется использовать в переменных сборки секретные ключи например от github, учетные данные пользователя и т. д. Значение переменных сборки доступны любому пользователю образа с помощью команды docker history.

Вы можете использовать инструкции ARG или ENV для задания переменных доступных в инструкции RUN. Переменные окружения заданные с помощью ENV всегда заменяют переменные с тем же именем заданные инструкцией ARG. Рассмотрим Dockerfile с инструкциями ENV и ARG.

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER v1.0.0
4 RUN echo $CONT_IMG_VER

Затем запустим сборку образа следующей командой:

$ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile

В данном случае, инструкция RUN использует v1.0.0 вместо значения ARG заданного в строке пользователемv2.0.1. Это поведение похоже на поведение shell скриптов где локальные переменные переопределяют переменные переданные в качестве аргументов или унаследованные от окружения.

Использовав пример выше, но с другой спецификацией ENV вы можете создать более полезные взаимодействия между инструкциями ARG и ENV:

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0}
4 RUN echo $CONT_IMG_VER

В отличие от инструкции ARG, значения ENV всегда присутствуют в созданном образе. Рассмотрим сборку без флага the --build-arg:

$ docker build Dockerfile

В данном примере Dockerfile, переменная CONT_IMG_VER сохранится в образе, но ее значение будет равно v1.0.0 поскольку оно задано по умолчанию в строке 3 инструкцией ENV.

Техника замены переменных в данном примере позволяет вам передавать аргументы из командной строки и сохранять их в конечном образе с помощью инструкции ENV. Замена переменных поддерживается для ограниченного числа инструкций Dockerfile.

Docker имеет набор предустановленных переменных ARG которые вы можете задавать без предварительной инструкции ARG в Dockerfile.

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy
• FTP_PROXY
• ftp_proxy
• NO_PROXY
• no_proxy

Для этого, просто передайте нужный аргумент в командной строке с помощью флага --build-arg <varname>=<value>.

Влияние на кэш сборки

Переменные ARG не сохраняются в собранном образе в отличае от ENV переменных. Однако, ARG переменные влияют на кэш сборки аналогичным образом. Если Dockerfile определяет ARG переменную чье значение отличается от предыдущей сборки, кэш не будет использован. В частности, все инструкции RUN следующие после ARG и использующие данную переменную (так же как и в случае с переменными окружения) не будут использовать кэш.

Для примера, рассмотрим два следующих Dockerfile:

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 RUN echo $CONT_IMG_VER

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 RUN echo hello

Если задать --build-arg CONT_IMG_VER=<value> в командной строке, в обоих случаях, строка 2 не вызывает промах кэша, в отличие от строки 3. В случае где команда RUN зависит от CONT_IMG_VER=<value>, если <value> изменится, мы получаем промах кеша.

Рассмотрим другой пример с такой же командной строкой:

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER $CONT_IMG_VER
4 RUN echo $CONT_IMG_VER

В данном примере, промах кэша происходит в строке 3. Это происходит по тому что значение переменной в ENV зависит от переменной ARG и эта переменная меняется через командную строку. В этом примере, команда ENV включает значение переменной в образ.

Если инструкция ENV заменяет значение переменной в инструкции ARG с тем же именем, как в этом Dockerfile:

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER hello
4 RUN echo $CONT_IMG_VER

Строка 3 не вызывает промаха кэша по тому что значение CONT_IMG_VER является константой (hello). В результате, переменные окружения и значения используемые в RUN (строка 4) не меняются от сборки к сборке.

ONBUILD

ONBUILD [INSTRUCTION]

Инструкция ONBUILD добавляет к образу триггерную инструкцию, которая выполняется в последнюю очередь если образ используется в качестве базового для другой сборки. Триггер будет выполнен в дочернем контексте сборки, так если бы инструкция была вставлена сразу после инструкции FROM дочернего Dockerfile.

Любая инструкция сборки может быть установлена в качестве триггера.

Это полезно если вы собираете образ который будет использоваться в качестве базового для сборки другого образа, например вы можете изменить переменные окружения или сделать демон конфигурация которого может быть изменена пользователем.

К примеру, если ваш образ является многократно используемым Python сборщиком приложения, которому требуется исходный код в определенном каталоге, для скрипта-сборщика запускаемого в конце. Вы не можете вызвать ADD и RUN как обычно, по тому что у вас еще нет доступа как исходному коду приложения, и он может отличаться для каждой сборки. Вы могли бы просто предоставить разработчикам приложения шаблонный Dockerfile для вставки в их приложение, но это не эффективно, может спровоцировать ошибки и усложняет обновление.

В качестве решения следует использовать ONBUILD для регистрации дополнительных инструкций для отложенного запуска, при следующем шаге сборки.

Как это работает:

1. Когда докер встречает инструкцию ONBUILD, сборщик добавляет триггер в метаданные образа. Инструкция не оказывает влияния на текущую сборку.
2. В конце сборки, список всех триггеров сохраняется в манифесте образа, в ключе OnBuild. Список можно посмотреть с помощью команды docker inspect.
3. Позже образ может быть использован в качестве базового для новой сборки, с помощью инструкции FROM. Как часть обработки инструкции FROM, сборщик ищет ONBUILD триггеры и выполняет их в том же порядке в котором они были добавлены. Если один из триггеров вызывает ошибку, инструкция FROM обрывается и вызывает ошибку сборки. Если все триггеры отработали, инструкция FROM завершается и сборка продолжается как обычно.
4. Триггеры очищаются в финальном образе после окончания сборки. Другими словами, дочерние образы не унаследуют триггеры прародителей.

Для примера можно добавить что ни будь вроде этого:

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

Предупреждение: Цепи инструкций ONBUILD ONBUILD не допускаются.

Предупреждение: Инструкция ONBUILD не поддерживает FROM или MAINTAINER.

STOPSIGNAL

STOPSIGNAL signal

Инструкция STOPSIGNAL устанавливает сигнал системного вызова, который будет отправлен для завершения контейнера. Сигнал может быть натуральным числом, которое соответствует позиции в таблице системных вызовов ядра, например 9 или именем сигнала в формате SIGNAME, например SIGKILL.

HEALTHCHECK

Инструкция HEALTHCHECK имеет две формы:

• HEALTHCHECK [OPTIONS] CMD command (проверяет состояние контейнера выполняя внутри него команду)
• HEALTHCHECK NONE (отключает любые проверки состояния из базового образа)

Инструкция HEALTHCHECK указывает Docker как проверить работает ли контейнер. Данная функция может помочь в выявлении ситуаций когда веб-сервер вошел в бесконечный цикл и не принимает соединения, в то время как его процесс все еще работает.

Когда у контейнера задана проверка на работоспособность, он имеет дополнительный статус состояния. Этот статус изначально равен starting. Всякий раз когда проверка состояния проходит успешно, он становится равен healthy (вне зависимости от предыдущего состояния). После определенного числа неудачных проверок статус изменяется на unhealthy.

Перед CMD можно задать следующие опции:

• --interval=DURATION (по умолчанию: 30s)
• --timeout=DURATION (по умолчанию: 30s)
• --retries=N (по умолчанию: 3)

Проверка работоспособности стартует первый раз спустя заданное время после запуска контейнера, а затем повторяется спустя тот же промежуток времени после того как предыдущая проверка была завершена.

Если проверка занимает больше времени чем установлено в timeout, то она считается неудачной.

Параметр retries отвечает за количество неудачных проверок необходимое для смены статуса контейнера на unhealthy.

Можно задать только одну инструкцию HEALTHCHECK в Dockerfile. Если указано несколько HEALTHCHECK, только последняя будет работать.

Команда после ключевого слова CMD может быть либо командой оболочки (например HEALTHCHECK CMD /bin/check-running) или выполнить массив (по аналогии с другими командами Dockerfile; для большей информации читайте документацию по ENTRYPOINT).

Статус завершения команды указывает на состояние контейнера. Возможные значения:

• 0: success - контейнер исправен и готов к использованию
• 1: unhealthy - контейнер работает неправильно
• 2: reserved - не используйте данный код выхода

Например, чтобы проверить каждые пять минут или около того, что веб-сервер способен обслуживать главную страницу сайта в течение трех секунд:

HEALTHCHECK --interval=5m --timeout=3s \
  CMD curl -f http://localhost/ || exit 1

Что бы помочь в отладке, любой исходящий текст (в кодировке UTF-8) который возвращают команды в stdout или stderr будет сохранен в статусе состояния и может быть запрошен командой docker inspect. Такой вывод должен быть коротким (только первые 4096 байт сохраняются на текущий момент).

Когда статус состояния контейнера изменяется, событие health_status генерируется с новым статусом.

Функция HEALTHCHECK была добавлена в Docker 1.12.

SHELL

SHELL ["executable", "parameters"]

Инструкция SHELL позволяет заменить стандартную оболочку для выполнения команд на пользовательскую. Оболочкой по умолчанию в Linux является ["/bin/sh", "-c"], а в Windows ["cmd", "/S", "/C"]. Инструкция SHELL записывается в JSON формате в Dockerfile.

Инструкция SHELL в частности полезна в Windows где есть две совершенно разных оболочки: cmd и powershell, а также альтернативные включая sh.

Инструкция SHELL может использоваться несколько раз. Каждая инструкция SHELL заменяет предыдущую инструкцию SHELL, и влияет на все последующие инструкции. К примеру:

FROM windowsservercore

# Executed as cmd /S /C echo default
RUN echo default

# Executed as cmd /S /C powershell -command Write-Host default
RUN powershell -command Write-Host default

# Executed as powershell -command Write-Host hello
SHELL ["powershell", "-command"]
RUN Write-Host hello

# Executed as cmd /S /C echo hello
SHELL ["cmd", "/S"", "/C"]
RUN echo hello

Следующие инструкции могут быть затронуты командой SHELL при использовании shell формы в Dockerfile: RUN, CMD и ENTRYPOINT.

Следующий пример представляет собой общий шаблон для Windows который может быть упрощен с помощью инструкции SHELL:

...
RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
...

Команда выполняемая docker будет выглядеть так:

cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"

Это не эффективно по двум причинам. Во-первых, вызывается не обязательная команда cmd.exe (т. е. оболочка). Во-вторых, каждая инструкция RUN в shell форме требует ставить перед командой powershell -command.

Есть два механизма позволяющих упростить решение. Одно из них, это использование JSON формы для инструкции RUN:

...
RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""]
...

В то время как JSON форма является однозначной и не использует не обязательный cmd.exe, но эта форма записи достаточно избыточна из-за необходимости использовать двойные кавычки и экранирование. Альтернытивным решением является использование инструкции SHELL и shell формы команд, что делает синтаксис более естественным для пользователей Windows, особенно при комбинировании с директивой парсера escape:

# escape=`

FROM windowsservercore
SHELL ["powershell","-command"]
RUN New-Item -ItemType Directory C:\Example
ADD Execute-MyCmdlet.ps1 c:\example\
RUN c:\example\Execute-MyCmdlet -sample 'hello world'
В результате получаем:

PS E:\docker\build\shell> docker build -t shell .
Sending build context to Docker daemon 3.584 kB
Step 1 : FROM windowsservercore
 ---> 5bc36a335344
Step 2 : SHELL powershell -command
 ---> Running in 87d7a64c9751
 ---> 4327358436c1
Removing intermediate container 87d7a64c9751
Step 3 : RUN New-Item -ItemType Directory C:\Example
 ---> Running in 3e6ba16b8df9

    Directory: C:\

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----         6/2/2016   2:59 PM                Example

 ---> 1f1dfdcec085
Removing intermediate container 3e6ba16b8df9
Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\
 ---> 6770b4c17f29
Removing intermediate container b139e34291dc
Step 5 : RUN c:\example\Execute-MyCmdlet -sample 'hello world'
 ---> Running in abdcf50dfd1f
Hello from Execute-MyCmdlet.ps1 - passed hello world
 ---> ba0e25255fda
Removing intermediate container abdcf50dfd1f
Successfully built ba0e25255fda
PS E:\docker\build\shell>

Инструкция SHELL также может быть использована для изменения режима работы оболочки. Например, использовав SHELL cmd /S /C /V:ON|OFF в Windows можно разрешить или запретить отложенное расширение переменных среды.

Инструкция SHELL также может быть использована в Linux для переключения на альтернативные оболочки вроде zsh, csh, tcsh и д.т.

Инструкция SHELL была добавлена в Docker 1.12.

Примеры Dockerfile

Ниже вы можете увидеть некоторые примеры синтаксиса Dockerfile.

# Nginx
#
# VERSION               0.0.1

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

LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0"
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.