Как написать докер файл

Время на прочтение
12 мин

Количество просмотров 466K

В переводе третьей части серии материалов, посвящённых Docker, мы продолжим вдохновляться выпечкой, а именно — бубликами. Нашей сегодняшней основной темой будет работа с файлами Dockerfile. Мы разберём инструкции, которые используются в этих файлах.

→ Часть 1: основы
→ Часть 2: термины и концепции
→ Часть 3: файлы Dockerfile
→ Часть 4: уменьшение размеров образов и ускорение их сборки
→ Часть 5: команды
→ Часть 6: работа с данными

Бублики — это инструкции в файле Dockerfile

Образы Docker

Вспомните о том, что контейнер Docker — это образ Docker, вызванный к жизни. Это — самодостаточная операционная система, в которой имеется только самое необходимое и код приложения.

Образы Docker являются результатом процесса их сборки, а контейнеры Docker — это выполняющиеся образы. В самом сердце Docker находятся файлы Dockerfile. Подобные файлы сообщают Docker о том, как собирать образы, на основе которых создаются контейнеры.

Каждому образу Docker соответствует файл, который называется Dockerfile. Его имя записывается именно так — без расширения. При запуске команды docker build для создания нового образа подразумевается, что Dockerfile находится в текущей рабочей директории. Если этот файл находится в каком-то другом месте, его расположение можно указать с использованием флага -f.

Контейнеры, как мы выяснили в первом материале этой серии, состоят из слоёв. Каждый слой, кроме последнего, находящегося поверх всех остальных, предназначен только для чтения. Dockerfile сообщает системе Docker о том, какие слои и в каком порядке надо добавить в образ.

Каждый слой, на самом деле, это всего лишь файл, который описывает изменение состояния образа в сравнении с тем состоянием, в котором он пребывал после добавления предыдущего слоя. В Unix, кстати, практически всё что угодно — это файл.

Базовый образ — это то, что является исходным слоем (или слоями) создаваемого образа. Базовый образ ещё называют родительским образом.

Базовый образ — это то, с чего начинается образ Docker

Когда образ загружается из удалённого репозитория на локальный компьютер, то физически скачиваются лишь слои, которых на этом компьютере нет. Docker стремится экономить пространство и время путём повторного использования существующих слоёв.

Файлы Dockerfile

В файлах Dockerfile содержатся инструкции по созданию образа. С них, набранных заглавными буквами, начинаются строки этого файла. После инструкций идут их аргументы. Инструкции, при сборке образа, обрабатываются сверху вниз. Вот как это выглядит:

FROM ubuntu:18.04
COPY . /app

Слои в итоговом образе создают только инструкции FROM, RUN, COPY, и ADD. Другие инструкции что-то настраивают, описывают метаданные, или сообщают Docker о том, что во время выполнения контейнера нужно что-то сделать, например — открыть какой-то порт или выполнить какую-то команду.

Здесь мы исходим из предположения, в соответствии с которым используется образ Docker, основанный на Unix-подобной ОС. Конечно, тут можно воспользоваться и образом, основанным на Windows, но использование Windows — это менее распространённая практика, работать с такими образами сложнее. В результате, если у вас есть такая возможность, пользуйтесь Unix.

Для начала приведём список инструкций Dockerfile с краткими комментариями.

Дюжина инструкций Dockerfile

1. FROM — задаёт базовый (родительский) образ.
2. LABEL — описывает метаданные. Например — сведения о том, кто создал и поддерживает образ.
3. ENV — устанавливает постоянные переменные среды.
4. RUN — выполняет команду и создаёт слой образа. Используется для установки в контейнер пакетов.
5. COPY — копирует в контейнер файлы и папки.
6. ADD — копирует файлы и папки в контейнер, может распаковывать локальные .tar-файлы.
7. CMD — описывает команду с аргументами, которую нужно выполнить когда контейнер будет запущен. Аргументы могут быть переопределены при запуске контейнера. В файле может присутствовать лишь одна инструкция CMD.
8. WORKDIR — задаёт рабочую директорию для следующей инструкции.
9. ARG — задаёт переменные для передачи Docker во время сборки образа.
10. ENTRYPOINT — предоставляет команду с аргументами для вызова во время выполнения контейнера. Аргументы не переопределяются.
11. EXPOSE — указывает на необходимость открыть порт.
12. VOLUME — создаёт точку монтирования для работы с постоянным хранилищем.

Теперь поговорим об этих инструкциях.

Инструкции и примеры их использования

▍Простой Dockerfile

Dockerfile может быть чрезвычайно простым и коротким. Например — таким:

FROM ubuntu:18.04

▍Инструкция FROM

Файл Dockerfile должен начинаться с инструкции FROM, или с инструкции ARG, за которой идёт инструкция FROM.

Ключевое слово FROM сообщает Docker о том, чтобы при сборке образа использовался бы базовый образ, который соответствует предоставленному имени и тегу. Базовый образ, кроме того, ещё называют родительским образом.

В этом примере базовый образ хранится в репозитории ubuntu. Ubuntu — это название официального репозитория Docker, предоставляющего базовую версию популярной ОС семейства Linux, которая называется Ubuntu.

Обратите внимание на то, что рассматриваемый Dockerfile включает в себя тег 18.04, уточняющий то, какой именно базовый образ нам нужен. Именно этот образ и будет загружен при сборке нашего образа. Если тег в инструкцию не включён, тогда Docker исходит из предположения о том, что требуется самый свежий образ из репозитория. Для того чтобы яснее выразить свои намерения, автору Dockerfile рекомендуется указывать то, какой именно образ ему нужен.

Когда вышеописанный Dockerfile используется на локальной машине для сборки образа в первый раз, Docker загрузит слои, определяемые образом ubuntu. Их можно представить наложенными друг на друга. Каждый следующий слой представляет собой файл, описывающий отличия образа в сравнении с тем его состоянием, в котором он был после добавления в него предыдущего слоя.

При создании контейнера слой, в который можно вносить изменения, добавляется поверх всех остальных слоёв. Данные, находящиеся в остальных слоях, можно только читать.

Структура контейнера (взято из документации)

Docker, ради эффективности, использует стратегию копирования при записи. Если слой в образе существует на предыдущем уровне и какому-то слою нужно произвести чтение данных из него, Docker использует существующий файл. При этом ничего загружать не нужно.

Когда образ выполняется, если слой нужно модифицировать средствами контейнера, то соответствующий файл копируется в самый верхний, изменяемый слой. Для того чтобы узнать подробности о стратегии копирования при записи, взгляните на этот материал из документации Docker.

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

▍Более сложный Dockerfile

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

FROM python:3.7.2-alpine3.8
LABEL maintainer="jeffmshale@gmail.com"
ENV ADMIN="jeff"
RUN apk update && apk upgrade && apk add bash
COPY . ./app
ADD https://raw.githubusercontent.com/discdiver/pachy-vid/master/sample_vids/vid1.mp4 
/my_app_directory
RUN ["mkdir", "/a_directory"]
CMD ["python", "./my_script.py"]

Возможно, на первый взгляд этот файл может показаться довольно сложным. Поэтому давайте с ним разберёмся.

Базой этого образа является официальный образ Python с тегом 3.7.2-alpine3.8. Проанализировав этот код можно увидеть, что данный базовый образ включает в себя Linux, Python, и, по большому счёту, этим его состав и ограничивается. Образы ОС Alpine весьма популярны в мире Docker. Дело в том, что они отличаются маленькими размерами, высокой скоростью работы и безопасностью. Однако образы Alpine не отличаются широкими возможностями, характерными для обычных операционных систем. Поэтому для того, чтобы собрать на основе такого образа что-то полезное, создателю образа нужно установить в него необходимые ему пакеты.

▍Инструкция LABEL

Метки

Инструкция LABEL (метка) позволяет добавлять в образ метаданные. В случае с рассматриваемым сейчас файлом, она включает в себя контактные сведения создателя образа. Объявление меток не замедляет процесс сборки образа и не увеличивает его размер. Они лишь содержат в себе полезную информацию об образе Docker, поэтому их рекомендуется включать в файл. Подробности о работе с метаданными в Dockerfile можно прочитать здесь.

▍Инструкция ENV

Окружающая среда

Инструкция ENV позволяет задавать постоянные переменные среды, которые будут доступны в контейнере во время его выполнения. В предыдущем примере после создания контейнера можно пользоваться переменной ADMIN.

Инструкция ENV хорошо подходит для задания констант. Если вы используете некое значение в Dockerfile несколько раз, скажем, при описании команд, выполняющихся в контейнере, и подозреваете, что, возможно, вам когда-нибудь придётся сменить его на другое, его имеет смысл записать в подобную константу.

Надо отметить, что в файлах Dockerfile часто существуют разные способы решения одних и тех же задач. Что именно использовать — это вопрос, на решение которого влияет стремление к соблюдению принятых в среде Docker методов работы, к обеспечению прозрачности решения и его высокой производительности. Например, инструкции RUN, CMD и ENTRYPOINT служат разным целям, но все они используются для выполнения команд.

▍Инструкция RUN

Инструкция RUN

Инструкция RUN позволяет создать слой во время сборки образа. После её выполнения в образ добавляется новый слой, его состояние фиксируется. Инструкция RUN часто используется для установки в образы дополнительных пакетов. В предыдущем примере инструкция RUN apk update && apk upgrade сообщает Docker о том, что системе нужно обновить пакеты из базового образа. Вслед за этими двумя командами идёт команда && apk add bash, указывающая на то, что в образ нужно установить bash.

То, что в командах выглядит как apk — это сокращение от Alpine Linux package manager (менеджер пакетов Alpine Linux). Если вы используете базовый образ какой-то другой ОС семейства Linux, тогда вам, например, при использовании Ubuntu, для установки пакетов может понадобиться команда вида RUN apt-get. Позже мы поговорим о других способах установки пакетов.

Инструкция RUN и схожие с ней инструкции — такие, как CMD и ENTRYPOINT, могут быть использованы либо в exec-форме, либо в shell-форме. Exec-форма использует синтаксис, напоминающий описание JSON-массива. Например, это может выглядеть так: RUN ["my_executable", "my_first_param1", "my_second_param2"].

В предыдущем примере мы использовали shell-форму инструкции RUN в таком виде: RUN apk update && apk upgrade && apk add bash.

Позже в нашем Dockerfile использована exec-форма инструкции RUN, в виде RUN ["mkdir", "/a_directory"] для создания директории. При этом, используя инструкцию в такой форме, нужно помнить о необходимости оформления строк с помощью двойных кавычек, как это принято в формате JSON.

▍Инструкция COPY

Инструкция COPY

Инструкция COPY представлена в нашем файле так: COPY . ./app. Она сообщает Docker о том, что нужно взять файлы и папки из локального контекста сборки и добавить их в текущую рабочую директорию образа. Если целевая директория не существует, эта инструкция её создаст.

▍Инструкция ADD

Инструкция ADD позволяет решать те же задачи, что и COPY, но с ней связана ещё пара вариантов использования. Так, с помощью этой инструкции можно добавлять в контейнер файлы, загруженные из удалённых источников, а также распаковывать локальные .tar-файлы.

В этом примере инструкция ADD была использована для копирования файла, доступного по URL, в директорию контейнера my_app_directory. Надо отметить, однако, что документация Docker не рекомендует использование подобных файлов, полученных по URL, так как удалить их нельзя, и так как они увеличивают размер образа.

Кроме того, документация предлагает везде, где это возможно, вместо инструкции ADD использовать инструкцию COPY для того, чтобы сделать файлы Dockerfile понятнее. Полагаю, команде разработчиков Docker стоило бы объединить ADD и COPY в одну инструкцию для того, чтобы тем, кто создаёт образы, не приходилось бы помнить слишком много инструкций.

Обратите внимание на то, что инструкция ADD содержит символ разрыва строки — . Такие символы используются для улучшения читабельности длинных команд путём разбиения их на несколько строк.

▍Инструкция CMD

Инструкция CMD

Инструкция CMD предоставляет Docker команду, которую нужно выполнить при запуске контейнера. Результаты выполнения этой команды не добавляются в образ во время его сборки. В нашем примере с помощью этой команды запускается скрипт my_script.py во время выполнения контейнера.

Вот ещё кое-что, что нужно знать об инструкции CMD:

• В одном файле Dockerfile может присутствовать лишь одна инструкция CMD. Если в файле есть несколько таких инструкций, система проигнорирует все кроме последней.
• Инструкция CMD может иметь exec-форму. Если в эту инструкцию не входит упоминание исполняемого файла, тогда в файле должна присутствовать инструкция ENTRYPOINT. В таком случае обе эти инструкции должны быть представлены в формате JSON.
• Аргументы командной строки, передаваемые docker run, переопределяют аргументы, предоставленные инструкции CMD в Dockerfile.

▍Ещё более сложный Dockerfile

Рассмотрим ещё один файл Dockerfile, в котором будут использованы некоторые новые команды.

FROM python:3.7.2-alpine3.8
LABEL maintainer="jeffmshale@gmail.com"
# Устанавливаем зависимости
RUN apk add --update git
# Задаём текущую рабочую директорию
WORKDIR /usr/src/my_app_directory
# Копируем код из локального контекста в рабочую директорию образа
COPY . .
# Задаём значение по умолчанию для переменной
ARG my_var=my_default_value
# Настраиваем команду, которая должна быть запущена в контейнере во время его выполнения
ENTRYPOINT ["python", "./app/my_script.py", "my_var"]
# Открываем порты
EXPOSE 8000
# Создаём том для хранения данных
VOLUME /my_volume

В этом примере, кроме прочего, вы можете видеть комментарии, которые начинаются с символа #.
Одно из основных действий, выполняемых средствами Dockerfile — это установка пакетов. Как уже было сказано, существуют различные способы установки пакетов с помощью инструкции RUN.

Пакеты в образ Alpine Docker можно устанавливать с помощью apk. Для этого, как мы уже говорили, применяется команда вида RUN apk update && apk upgrade && apk add bash.

Кроме того, пакеты Python в образ можно устанавливать с помощью pip, wheel и conda. Если речь идёт не о Python, а о других языках программирования, то при подготовке соответствующих образов могут использоваться и другие менеджеры пакетов.

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

Например, инструкцию RUN в Dockerfile можно использовать для установки списка пакетов с помощью pip. Если вы так поступаете — объедините все команды в одну инструкцию и разделите её символами разрыва строки с помощью символа . Благодаря такому подходу файлы будут выглядеть аккуратно и это приведёт к добавлению в образ меньшего количества слоёв, чем было бы добавлено при использовании нескольких инструкций RUN.

Кроме того, для установки нескольких пакетов можно поступить и по-другому. Их можно перечислить в файле и передать менеджеру пакетов этот файл с помощью RUN. Обычно таким файлам дают имя requirements.txt.

▍Инструкция WORKDIR

Рабочие директории

Инструкция WORKDIR позволяет изменить рабочую директорию контейнера. С этой директорией работают инструкции COPY, ADD, RUN, CMD и ENTRYPOINT, идущие за WORKDIR. Вот некоторые особенности, касающиеся этой инструкции:

• Лучше устанавливать с помощью WORKDIR абсолютные пути к папкам, а не перемещаться по файловой системе с помощью команд cd в Dockerfile.
• Инструкция WORKDIR автоматически создаёт директорию в том случае, если она не существует.
• Можно использовать несколько инструкций WORKDIR. Если таким инструкциям предоставляются относительные пути, то каждая из них меняет текущую рабочую директорию.

▍Инструкция ARG

Инструкция ARG позволяет задать переменную, значение которой можно передать из командной строки в образ во время его сборки. Значение для переменной по умолчанию можно представить в Dockerfile. Например: ARG my_var=my_default_value.

В отличие от ENV-переменных, ARG-переменные недоступны во время выполнения контейнера. Однако ARG-переменные можно использовать для задания значений по умолчанию для ENV-переменных из командной строки в процессе сборки образа. А ENV-переменные уже будут доступны в контейнере во время его выполнения. Подробности о такой методике работы с переменными можно почитать здесь.

▍Инструкция ENTRYPOINT

Пункт перехода в какое-то место

Инструкция ENTRYPOINT позволяет задавать команду с аргументами, которая должна выполняться при запуске контейнера. Она похожа на команду CMD, но параметры, задаваемые в ENTRYPOINT, не перезаписываются в том случае, если контейнер запускают с параметрами командной строки.

Вместо этого аргументы командной строки, передаваемые в конструкции вида docker run my_image_name, добавляются к аргументам, задаваемым инструкцией ENTRYPOINT. Например, после выполнения команды вида docker run my_image bash аргумент bash добавится в конец списка аргументов, заданных с помощью ENTRYPOINT. Готовя Dockerfile, не забудьте об инструкции CMD или ENTRYPOINT.

В документации к Docker есть несколько рекомендаций, касающихся того, какую инструкцию, CMD или ENTRYPOINT, стоит выбрать в качестве инструмента для выполнения команд при запуске контейнера:

• Если при каждом запуске контейнера нужно выполнять одну и ту же команду — используйте ENTRYPOINT.
• Если контейнер будет использоваться в роли приложения — используйте ENTRYPOINT.
• Если вы знаете, что при запуске контейнера вам понадобится передавать ему аргументы, которые могут перезаписывать аргументы, указанные в Dockerfile, используйте CMD.

В нашем примере использование инструкции ENTRYPOINT ["python", "my_script.py", "my_var"] приводит к тому, что контейнер, при запуске, запускает Python-скрипт my_script.py с аргументом my_var. Значение, представленное my_var, потом можно использовать в скрипте с помощью argparse. Обратите внимание на то, что в Dockerfile переменной my_var, до её использования, назначено значение по умолчанию с помощью ARG. В результате, если при запуске контейнера ему не передали соответствующее значение, будет применено значение по умолчанию.

Документация Docker рекомендует использовать exec-форму ENTRYPOINT: ENTRYPOINT ["executable", "param1", "param2"].

▍Инструкция EXPOSE

Инструкция EXPOSE

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

Для того чтобы открыть порт (или порты) и настроить перенаправление портов, нужно выполнить команду docker run с ключом -p. Если использовать ключ в виде -P (с заглавной буквой P), то открыты будут все порты, указанные в инструкции EXPOSE.

▍Инструкция VOLUME

Инструкция VOLUME

Инструкция VOLUME позволяет указать место, которое контейнер будет использовать для постоянного хранения файлов и для работы с такими файлами. Об этом мы ещё поговорим.

Итоги

Теперь вы знаете дюжину инструкций, применяемых при создании образов с помощью Dockerfile. Этим список таких инструкций не исчерпывается. В частности, мы не рассмотрели здесь такие инструкции, как USER, ONBUILD, STOPSIGNAL, SHELL и HEALTHCHECK. Вот краткий справочник по инструкциям Dockerfile.

Вероятно, файлы Dockerfile — это ключевой компонент экосистемы Docker, работать с которым нужно научиться всем, кто хочет уверенно чувствовать себя в этой среде. Мы ещё вернёмся к разговору о них в следующий раз, когда будем обсуждать способы уменьшения размеров образов.

Уважаемые читатели! Если вы пользуетесь Docker на практике, просим рассказать о том, как вы пишете Docker-файлы.

Dockerfile reference

Docker can build images automatically by reading the instructions from a
Dockerfile. A Dockerfile is a text document that contains all the commands a
user could call on the command line to assemble an image. Using docker build
users can create an automated build that executes several command-line
instructions in succession.

This page describes the commands you can use in a Dockerfile. When you are
done reading this page, refer to the Dockerfile Best
Practices for a tip-oriented guide.

Usage

The docker build command builds an image from
a Dockerfile and a context. The build’s context is the files at a specified
location PATH or URL. The PATH is a directory on your local filesystem.
The URL is a the location of a Git repository.

A context is processed recursively. So, a PATH includes any subdirectories and
the URL includes the repository and its submodules. A simple build command
that uses the current directory as context:

$ docker build .
Sending build context to Docker daemon  6.51 MB
...

The build is run by the Docker daemon, not by the CLI. The first thing a build
process does is send the entire context (recursively) to the daemon. In most
cases, it’s best to start with an empty directory as context and keep your
Dockerfile in that directory. Add only the files needed for building the
Dockerfile.

Warning: Do not use your root directory, /, as the PATH as it causes
the build to transfer the entire contents of your hard drive to the Docker
daemon.

To use a file in the build context, the Dockerfile refers to the file specified
in an instruction, for example, a COPY instruction. To increase the build’s
performance, exclude files and directories by adding a .dockerignore file to
the context directory. For information about how to create a .dockerignore
file see the documentation on this page.

Traditionally, the Dockerfile is called Dockerfile and located in the root
of the context. You use the -f flag with docker build to point to a Dockerfile
anywhere in your file system.

$ docker build -f /path/to/a/Dockerfile .

You can specify a repository and tag at which to save the new image if
the build succeeds:

$ docker build -t shykes/myapp .

To tag the image into multiple repositories after the build,
add multiple -t parameters when you run the build command:

$ docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest .

The Docker daemon runs the instructions in the Dockerfile one-by-one,
committing the result of each instruction
to a new image if necessary, before finally outputting the ID of your
new image. The Docker daemon will automatically clean up the context you
sent.

Note that each instruction is run independently, and causes a new image
to be created — so RUN cd /tmp will not have any effect on the next
instructions.

Whenever possible, Docker will re-use the intermediate images (cache),
to accelerate the docker build process significantly. This is indicated by
the Using cache message in the console output.
(For more information, see the Build cache section) in the
Dockerfile best practices guide:

$ docker build -t svendowideit/ambassador .
Sending build context to Docker daemon 15.36 kB
Step 0 : FROM alpine:3.2
 ---> 31f630c65071
Step 1 : MAINTAINER SvenDowideit@home.org.au
 ---> Using cache
 ---> 2a1c91448f5f
Step 2 : RUN apk update &&      apk add socat &&        rm -r /var/cache/
 ---> Using cache
 ---> 21ed6e7fbb73
Step 3 : CMD env | grep _TCP= | (sed 's/.*_PORT_([0-9]*)_TCP=tcp://(.*):(.*)/socat -t 100000000 TCP4-LISTEN:1,fork,reuseaddr TCP4:2:3 &/' && echo wait) | sh
 ---> Using cache
 ---> 7ea8aef582cc
Successfully built 7ea8aef582cc

When you’re done with your build, you’re ready to look into Pushing a
repository to its registry.

Format

Here is the format of the Dockerfile:

# Comment
INSTRUCTION arguments

The instruction is not case-sensitive, however convention is for them to
be UPPERCASE in order to distinguish them from arguments more easily.

Docker runs the instructions in a Dockerfile in order. The
first instruction must be `FROM` in order to specify the Base
Image from which you are building.

Docker will treat lines that begin with # as a
comment. A # marker anywhere else in the line will
be treated as an argument. This allows statements like:

# Comment
RUN echo 'we are running some # of cool things'

Here is the set of instructions you can use in a Dockerfile for building
images.

Environment replacement

Environment variables (declared with the ENV statement) can also be
used in certain instructions as variables to be interpreted by the
Dockerfile. Escapes are also handled for including variable-like syntax
into a statement literally.

Environment variables are notated in the Dockerfile either with
$variable_name or ${variable_name}. They are treated equivalently and the
brace syntax is typically used to address issues with variable names with no
whitespace, like ${foo}_bar.

The ${variable_name} syntax also supports a few of the standard bash
modifiers as specified below:

• ${variable:-word} indicates that if variable is set then the result
  will be that value. If variable is not set then word will be the result.
• ${variable:+word} indicates that if variable is set then word will be
  the result, otherwise the result is the empty string.

In all cases, word can be any string, including additional environment
variables.

Escaping is possible by adding a before the variable: $foo or ${foo},
for example, will translate to $foo and ${foo} literals respectively.

Example (parsed representation is displayed after the #):

FROM busybox
ENV foo /bar
WORKDIR ${foo}   # WORKDIR /bar
ADD . $foo       # ADD . /bar
COPY $foo /quux # COPY $foo /quux

Environment variables are supported by the following list of instructions in
the Dockerfile:

• ADD
• COPY
• ENV
• EXPOSE
• LABEL
• USER
• WORKDIR
• VOLUME
• STOPSIGNAL

as well as:

• ONBUILD (when combined with one of the supported instructions above)

Note:
prior to 1.4, ONBUILD instructions did NOT support environment
variable, even when combined with any of the instructions listed above.

Environment variable substitution will use the same value for each variable
throughout the entire command. In other words, in this example:

ENV abc=hello
ENV abc=bye def=$abc
ENV ghi=$abc

will result in def having a value of hello, not bye. However,
ghi will have a value of bye because it is not part of the same command
that set abc to bye.

.dockerignore file

Before the docker CLI sends the context to the docker daemon, it looks
for a file named .dockerignore in the root directory of the context.
If this file exists, the CLI modifies the context to exclude files and
directories that match patterns in it. This helps to avoid
unnecessarily sending large or sensitive files and directories to the
daemon and potentially adding them to images using ADD or COPY.

The CLI interprets the .dockerignore file as a newline-separated
list of patterns similar to the file globs of Unix shells. For the
purposes of matching, the root of the context is considered to be both
the working and the root directory. For example, the patterns
/foo/bar and foo/bar both exclude a file or directory named bar
in the foo subdirectory of PATH or in the root of the git
repository located at URL. Neither excludes anything else.

Here is an example .dockerignore file:

This file causes the following build behavior:

Rule	Behavior
*/temp*	Exclude files and directories whose names start with temp in any immediate subdirectory of the root. For example, the plain file /somedir/temporary.txt is excluded, as is the directory /somedir/temp.
*/*/temp*	Exclude files and directories starting with temp from any subdirectory that is two levels below the root. For example, /somedir/subdir/temporary.txt is excluded.
temp?	Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded.

Matching is done using Go’s
filepath.Match rules. A
preprocessing step removes leading and trailing whitespace and
eliminates . and .. elements using Go’s
filepath.Clean. Lines
that are blank after preprocessing are ignored.

Beyond Go’s filepath.Match rules, Docker also supports a special
wildcard string ** that matches any number of directories (including
zero). For example, **/*.go will exclude all files that end with .go
that are found in all directories, including the root of the build context.

Lines starting with ! (exclamation mark) can be used to make exceptions
to exclusions. The following is an example .dockerignore file that
uses this mechanism:

All markdown files except README.md are excluded from the context.

The placement of ! exception rules influences the behavior: the last
line of the .dockerignore that matches a particular file determines
whether it is included or excluded. Consider the following example:

    *.md
    !README*.md
    README-secret.md

No markdown files are included in the context except README files other than
README-secret.md.

Now consider this example:

    *.md
    README-secret.md
    !README*.md

All of the README files are included. The middle line has no effect because
!README*.md matches README-secret.md and comes last.

You can even use the .dockerignore file to exclude the Dockerfile
and .dockerignore files. These files are still sent to the daemon
because it needs them to do its job. But the ADD and COPY commands
do not copy them to the image.

Finally, you may want to specify which files to include in the
context, rather than which to exclude. To achieve this, specify * as
the first pattern, followed by one or more ! exception patterns.

Note: For historical reasons, the pattern . is ignored.

FROM

Or

Or

The FROM instruction sets the Base Image
for subsequent instructions. As such, a valid Dockerfile must have FROM as
its first instruction. The image can be any valid image – it is especially easy
to start by pulling an image from the Public Repositories.

• FROM must be the first non-comment instruction in the Dockerfile.

• FROM can appear multiple times within a single Dockerfile in order to create
  multiple images. Simply make a note of the last image ID output by the commit
  before each new FROM command.

• The tag or digest values are optional. If you omit either of them, the builder
  assumes a latest by default. The builder returns an error if it cannot match
  the tag value.

MAINTAINER

The MAINTAINER instruction allows you to set the Author field of the
generated images.

RUN

RUN has 2 forms:

• RUN <command> (shell form, the command is run in a shell — /bin/sh -c)
• RUN ["executable", "param1", "param2"] (exec form)

The RUN instruction will execute any commands in a new layer on top of the
current image and commit the results. The resulting committed image will be
used for the next step in the Dockerfile.

Layering RUN instructions and generating commits conforms to the core
concepts of Docker where commits are cheap and containers can be created from
any point in an image’s history, much like source control.

The exec form makes it possible to avoid shell string munging, and to RUN
commands using a base image that does not contain /bin/sh.

In the shell form you can use a (backslash) to continue a single
RUN instruction onto the next line. For example, consider these two lines:

RUN /bin/bash -c 'source $HOME/.bashrc ;
echo $HOME'

Together they are equivalent to this single line:

RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME'

Note:
To use a different shell, other than ‘/bin/sh’, use the exec form
passing in the desired shell. For example,
RUN ["/bin/bash", "-c", "echo hello"]

Note:
The exec form is parsed as a JSON array, which means that
you must use double-quotes («) around words not single-quotes (‘).

Note:
Unlike the shell form, the exec form does not invoke a command shell.
This means that normal shell processing does not happen. For example,
RUN [ "echo", "$HOME" ] will not do variable substitution on $HOME.
If you want shell processing then either use the shell form or execute
a shell directly, for example: RUN [ "sh", "-c", "echo", "$HOME" ].

The cache for RUN instructions isn’t invalidated automatically during
the next build. The cache for an instruction like
RUN apt-get dist-upgrade -y will be reused during the next build. The
cache for RUN instructions can be invalidated by using the --no-cache
flag, for example docker build --no-cache.

See the Dockerfile Best Practices
guide for more information.

The cache for RUN instructions can be invalidated by ADD instructions. See
below for details.

Known issues (RUN)

• Issue 783 is about file
  permissions problems that can occur when using the AUFS file system. You
  might notice it during an attempt to rm a file, for example.

  For systems that have recent aufs version (i.e., dirperm1 mount option can
  be set), docker will attempt to fix the issue automatically by mounting
  the layers with dirperm1 option. More details on dirperm1 option can be
  found at aufs man page

  If your system doesn’t have support for dirperm1, the issue describes a workaround.

CMD

The CMD instruction has three forms:

• CMD ["executable","param1","param2"] (exec form, this is the preferred form)
• CMD ["param1","param2"] (as default parameters to ENTRYPOINT)
• CMD command param1 param2 (shell form)

There can only be one CMD instruction in a Dockerfile. If you list more than one CMD
then only the last CMD will take effect.

The main purpose of a CMD is to provide defaults for an executing
container. These defaults can include an executable, or they can omit
the executable, in which case you must specify an ENTRYPOINT
instruction as well.

Note:
If CMD is used to provide default arguments for the ENTRYPOINT
instruction, both the CMD and ENTRYPOINT instructions should be specified
with the JSON array format.

Note:
The exec form is parsed as a JSON array, which means that
you must use double-quotes («) around words not single-quotes (‘).

Note:
Unlike the shell form, the exec form does not invoke a command shell.
This means that normal shell processing does not happen. For example,
CMD [ "echo", "$HOME" ] will not do variable substitution on $HOME.
If you want shell processing then either use the shell form or execute
a shell directly, for example: CMD [ "sh", "-c", "echo", "$HOME" ].

When used in the shell or exec formats, the CMD instruction sets the command
to be executed when running the image.

If you use the shell form of the CMD, then the <command> will execute in
/bin/sh -c:

FROM ubuntu
CMD echo "This is a test." | wc -

If you want to run your <command> without a shell then you must
express the command as a JSON array and give the full path to the executable.
This array form is the preferred format of CMD. Any additional parameters
must be individually expressed as strings in the array:

FROM ubuntu
CMD ["/usr/bin/wc","--help"]

If you would like your container to run the same executable every time, then
you should consider using ENTRYPOINT in combination with CMD. See
ENTRYPOINT.

If the user specifies arguments to docker run then they will override the
default specified in CMD.

Note:
don’t confuse RUN with CMD. RUN actually runs a command and commits
the result; CMD does not execute anything at build time, but specifies
the intended command for the image.

LABEL

LABEL <key>=<value> <key>=<value> <key>=<value> ...

The LABEL instruction adds metadata to an image. A LABEL is a
key-value pair. To include spaces within a LABEL value, use quotes and
backslashes as you would in command-line parsing. A few usage examples:

LABEL "com.example.vendor"="ACME Incorporated"
LABEL com.example.label-with-value="foo"
LABEL version="1.0"
LABEL description="This text illustrates 
that label-values can span multiple lines."

An image can have more than one label. To specify multiple labels,
Docker recommends combining labels into a single LABEL instruction where
possible. Each LABEL instruction produces a new layer which can result in an
inefficient image if you use many labels. This example results in a single image
layer.

LABEL multi.label1="value1" multi.label2="value2" other="value3"

The above can also be written as:

LABEL multi.label1="value1" 
      multi.label2="value2" 
      other="value3"

Labels are additive including LABELs in FROM images. If Docker
encounters a label/key that already exists, the new value overrides any previous
labels with identical keys.

To view an image’s labels, use the docker inspect command.

"Labels": {
    "com.example.vendor": "ACME Incorporated"
    "com.example.label-with-value": "foo",
    "version": "1.0",
    "description": "This text illustrates that label-values can span multiple lines.",
    "multi.label1": "value1",
    "multi.label2": "value2",
    "other": "value3"
},

EXPOSE

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

The EXPOSE instruction informs Docker that the container listens on the
specified network ports at runtime. EXPOSE does not make the ports of the
container accessible to the host. To do that, you must use either the -p flag
to publish a range of ports or the -P flag to publish all of the exposed
ports. You can expose one port number and publish it externally under another
number.

To set up port redirection on the host system, see using the -P
flag. The Docker network feature supports
creating networks without the need to expose ports within the network, for
detailed information see the overview of this
feature).

ENV

ENV <key> <value>
ENV <key>=<value> ...

The ENV instruction sets the environment variable <key> to the value
<value>. This value will be in the environment of all «descendant»
Dockerfile commands and can be replaced inline in
many as well.

The ENV instruction has two forms. The first form, ENV <key> <value>,
will set a single variable to a value. The entire string after the first
space will be treated as the <value> — including characters such as
spaces and quotes.

The second form, ENV <key>=<value> ..., allows for multiple variables to
be set at one time. Notice that the second form uses the equals sign (=)
in the syntax, while the first form does not. Like command line parsing,
quotes and backslashes can be used to include spaces within values.

For example:

ENV myName="John Doe" myDog=Rex The Dog 
    myCat=fluffy

and

ENV myName John Doe
ENV myDog Rex The Dog
ENV myCat fluffy

will yield the same net results in the final container, but the first form
is preferred because it produces a single cache layer.

The environment variables set using ENV will persist when a container is run
from the resulting image. You can view the values using docker inspect, and
change them using docker run --env <key>=<value>.

Note:
Environment persistence can cause unexpected side effects. For example,
setting ENV DEBIAN_FRONTEND noninteractive may confuse apt-get
users on a Debian-based image. To set a value for a single command, use
RUN <key>=<value> <command>.

ADD

ADD has two forms:

• ADD <src>... <dest>
• ADD ["<src>",... "<dest>"] (this form is required for paths containing
  whitespace)

The ADD instruction copies new files, directories or remote file URLs from <src>
and adds them to the filesystem of the container at the path <dest>.

Multiple <src> resource may be specified but if they are files or
directories then they must be relative to the source directory that is
being built (the context of the build).

Each <src> may contain wildcards and matching will be done using Go’s
filepath.Match rules. For example:

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

The <dest> is an absolute path, or a path relative to WORKDIR, into which
the source will be copied inside the destination container.

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

All new files and directories are created with a UID and GID of 0.

In the case where <src> is a remote file URL, the destination will
have permissions of 600. If the remote file being retrieved has an HTTP
Last-Modified header, the timestamp from that header will be used
to set the mtime on the destination file. However, like any other file
processed during an ADD, mtime will not be included in the determination
of whether or not the file has changed and the cache should be updated.

Note:
If you build by passing a Dockerfile through STDIN (docker build - < somefile), there is no build context, so the Dockerfile
can only contain a URL based ADD instruction. You can also pass a
compressed archive through STDIN: (docker build - < archive.tar.gz),
the Dockerfile at the root of the archive and the rest of the
archive will get used at the context of the build.

Note:
If your URL files are protected using authentication, you
will need to use RUN wget, RUN curl or use another tool from
within the container as the ADD instruction does not support
authentication.

Note:
The first encountered ADD instruction will invalidate the cache for all
following instructions from the Dockerfile if the contents of <src> have
changed. This includes invalidating the cache for RUN instructions.
See the Dockerfile Best Practices
guide for more information.

ADD obeys the following rules:

• The <src> path must be inside the context of the build;
  you cannot ADD ../something /something, because the first step of a
  docker build is to send the context directory (and subdirectories) to the
  docker daemon.

• If <src> is a URL and <dest> does not end with a trailing slash, then a
  file is downloaded from the URL and copied to <dest>.

• If <src> is a URL and <dest> does end with a trailing slash, then the
  filename is inferred from the URL and the file is downloaded to
  <dest>/<filename>. For instance, ADD http://example.com/foobar / would
  create the file /foobar. The URL must have a nontrivial path so that an
  appropriate filename can be discovered in this case (http://example.com
  will not work).

• If <src> is a directory, the entire contents of the directory are copied,
  including filesystem metadata.

Note:
The directory itself is not copied, just its contents.

• If <src> is a local tar archive in a recognized compression format
  (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources
  from remote URLs are not decompressed. When a directory is copied or
  unpacked, it has the same behavior as tar -x: the result is the union of:

  1. Whatever existed at the destination path and
  2. The contents of the source tree, with conflicts resolved in favor
     of «2.» on a file-by-file basis.

  Note:
  Whether a file is identified as a recognized compression format or not
  is done solely based on the contents of the file, not the name of the file.
  For example, if an empty file happens to end with .tar.gz this will not
  be recognized as a compressed file and will not generate any kind of
  decompression error message, rather the file will simply be copied to the
  destination.

• If <src> is any other kind of file, it is copied individually along with
  its metadata. In this case, if <dest> ends with a trailing slash /, it
  will be considered a directory and the contents of <src> will be written
  at <dest>/base(<src>).

• If multiple <src> resources are specified, either directly or due to the
  use of a wildcard, then <dest> must be a directory, and it must end with
  a slash /.

• If <dest> does not end with a trailing slash, it will be considered a
  regular file and the contents of <src> will be written at <dest>.

• If <dest> doesn’t exist, it is created along with all missing directories
  in its path.

COPY

COPY has two forms:

• COPY <src>... <dest>
• COPY ["<src>",... "<dest>"] (this form is required for paths containing
  whitespace)

The COPY instruction copies new files or directories from <src>
and adds them to the filesystem of the container at the path <dest>.

Multiple <src> resource may be specified but they must be relative
to the source directory that is being built (the context of the build).

Each <src> may contain wildcards and matching will be done using Go’s
filepath.Match rules. For example:

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

The <dest> is an absolute path, or a path relative to WORKDIR, into which
the source will be copied inside the destination container.

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

All new files and directories are created with a UID and GID of 0.

Note:
If you build using STDIN (docker build - < somefile), there is no
build context, so COPY can’t be used.

COPY obeys the following rules:

• The <src> path must be inside the context of the build;
  you cannot COPY ../something /something, because the first step of a
  docker build is to send the context directory (and subdirectories) to the
  docker daemon.

• If <src> is a directory, the entire contents of the directory are copied,
  including filesystem metadata.

Note:
The directory itself is not copied, just its contents.

• If <src> is any other kind of file, it is copied individually along with
  its metadata. In this case, if <dest> ends with a trailing slash /, it
  will be considered a directory and the contents of <src> will be written
  at <dest>/base(<src>).

• If multiple <src> resources are specified, either directly or due to the
  use of a wildcard, then <dest> must be a directory, and it must end with
  a slash /.

• If <dest> does not end with a trailing slash, it will be considered a
  regular file and the contents of <src> will be written at <dest>.

• If <dest> doesn’t exist, it is created along with all missing directories
  in its path.

ENTRYPOINT

ENTRYPOINT has two forms:

• ENTRYPOINT ["executable", "param1", "param2"]
  (exec form, preferred)
• ENTRYPOINT command param1 param2
  (shell form)

An ENTRYPOINT allows you to configure a container that will run as an executable.

For example, the following will start nginx with its default content, listening
on port 80:

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

Command line arguments to docker run <image> will be appended after all
elements in an exec form ENTRYPOINT, and will override all elements specified
using CMD.
This allows arguments to be passed to the entry point, i.e., docker run <image> -d
will pass the -d argument to the entry point.
You can override the ENTRYPOINT instruction using the docker run --entrypoint
flag.

The shell form prevents any CMD or run command line arguments from being
used, but has the disadvantage that your ENTRYPOINT will be started as a
subcommand of /bin/sh -c, which does not pass signals.
This means that the executable will not be the container’s PID 1 — and
will not receive Unix signals — so your executable will not receive a
SIGTERM from docker stop <container>.

Only the last ENTRYPOINT instruction in the Dockerfile will have an effect.

Exec form ENTRYPOINT example

You can use the exec form of ENTRYPOINT to set fairly stable default commands
and arguments and then use either form of CMD to set additional defaults that
are more likely to be changed.

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

When you run the container, you can see that top is the only process:

$ 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

To examine the result further, you can use docker exec:

$ 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

And you can gracefully request top to shut down using docker stop test.

The following Dockerfile shows using the ENTRYPOINT to run Apache in the
foreground (i.e., as PID 1):

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"]

If you need to write a starter script for a single executable, you can ensure that
the final executable receives the Unix signals by using exec and gosu
commands:

#!/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 "$@"

Lastly, if you need to do some extra cleanup (or communicate with other containers)
on shutdown, or are co-ordinating more than one executable, you may need to ensure
that the ENTRYPOINT script receives the Unix signals, passes them on, and then
does some more work:

#!/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 KILL 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"

If you run this image with docker run -it --rm -p 80:80 --name test apache,
you can then examine the container’s processes with docker exec, or docker top,
and then ask the script to stop Apache:

$ 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

Note: you can over ride the ENTRYPOINT setting using --entrypoint,
but this can only set the binary to exec (no sh -c will be used).

Note:
The exec form is parsed as a JSON array, which means that
you must use double-quotes («) around words not single-quotes (‘).

Note:
Unlike the shell form, the exec form does not invoke a command shell.
This means that normal shell processing does not happen. For example,
ENTRYPOINT [ "echo", "$HOME" ] will not do variable substitution on $HOME.
If you want shell processing then either use the shell form or execute
a shell directly, for example: ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ].
Variables that are defined in the Dockerfileusing ENV, will be substituted by
the Dockerfile parser.

Shell form ENTRYPOINT example

You can specify a plain string for the ENTRYPOINT and it will execute in /bin/sh -c.
This form will use shell processing to substitute shell environment variables,
and will ignore any CMD or docker run command line arguments.
To ensure that docker stop will signal any long running ENTRYPOINT executable
correctly, you need to remember to start it with exec:

FROM ubuntu
ENTRYPOINT exec top -b

When you run this image, you’ll see the single PID 1 process:

$ 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

Which will exit cleanly on docker stop:

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

If you forget to add exec to the beginning of your ENTRYPOINT:

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

You can then run it (giving it a name for the next step):

$ 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

You can see from the output of top that the specified ENTRYPOINT is not PID 1.

If you then run docker stop test, the container will not exit cleanly — the
stop command will be forced to send a SIGKILL after the timeout:

$ 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

Understand how CMD and ENTRYPOINT interact

Both CMD and ENTRYPOINT instructions define what command gets executed when running a container.
There are few rules that describe their co-operation.

1. Dockerfile should specify at least one of CMD or ENTRYPOINT commands.

2. ENTRYPOINT should be defined when using the container as an executable.

3. CMD should be used as a way of defining default arguments for an ENTRYPOINT command
   or for executing an ad-hoc command in a container.

4. CMD will be overridden when running the container with alternative arguments.

The table below shows what command is executed for different ENTRYPOINT / CMD combinations:

	No ENTRYPOINT	ENTRYPOINT exec_entry p1_entry	ENTRYPOINT [«exec_entry», «p1_entry»]
No CMD	error, not allowed	/bin/sh -c exec_entry p1_entry	exec_entry p1_entry
CMD [«exec_cmd», «p1_cmd»]	exec_cmd p1_cmd	/bin/sh -c exec_entry p1_entry exec_cmd p1_cmd	exec_entry p1_entry exec_cmd p1_cmd
CMD [«p1_cmd», «p2_cmd»]	p1_cmd p2_cmd	/bin/sh -c exec_entry p1_entry p1_cmd p2_cmd	exec_entry p1_entry p1_cmd p2_cmd
CMD exec_cmd p1_cmd	/bin/sh -c exec_cmd p1_cmd	/bin/sh -c exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd	exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd

VOLUME

The VOLUME instruction creates a mount point with the specified name
and marks it as holding externally mounted volumes from native host or other
containers. The value can be a JSON array, VOLUME ["/var/log/"], or a plain
string with multiple arguments, such as VOLUME /var/log or VOLUME /var/log /var/db. For more information/examples and mounting instructions via the
Docker client, refer to
Share Directories via Volumes
documentation.

The docker run command initializes the newly created volume with any data
that exists at the specified location within the base image. For example,
consider the following Dockerfile snippet:

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

This Dockerfile results in an image that causes docker run, to
create a new mount point at /myvol and copy the greeting file
into the newly created volume.

Note:
If any build steps change the data within the volume after it has been
declared, those changes will be discarded.

Note:
The list is parsed as a JSON array, which means that
you must use double-quotes («) around words not single-quotes (‘).

USER

The USER instruction sets the user name or UID to use when running the image
and for any RUN, CMD and ENTRYPOINT instructions that follow it in the
Dockerfile.

WORKDIR

The WORKDIR instruction sets the working directory for any RUN, CMD,
ENTRYPOINT, COPY and ADD instructions that follow it in the Dockerfile.
If the WORKDIR doesn’t exist, it will be created even if its not used in any
subsequent Dockerfile instruction.

It can be used multiple times in the one Dockerfile. If a relative path
is provided, it will be relative to the path of the previous WORKDIR
instruction. For example:

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

The output of the final pwd command in this Dockerfile would be
/a/b/c.

The WORKDIR instruction can resolve environment variables previously set using
ENV. You can only use environment variables explicitly set in the Dockerfile.
For example:

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

The output of the final pwd command in this Dockerfile would be
/path/$DIRNAME

ARG

ARG <name>[=<default value>]

The ARG instruction defines a variable that users can pass at build-time to
the builder with the docker build command using the --build-arg <varname>=<value> flag. If a user specifies a build argument that was not
defined in the Dockerfile, the build outputs an error.

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

The Dockerfile author can define a single variable by specifying ARG once or many
variables by specifying ARG more than once. For example, a valid Dockerfile:

FROM busybox
ARG user1
ARG buildno
...

A Dockerfile author may optionally specify a default value for an ARG instruction:

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

If an ARG value has a default and if there is no value passed at build-time, the
builder uses the default.

An ARG variable definition comes into effect from the line on which it is
defined in the Dockerfile not from the argument’s use on the command-line or
elsewhere. For example, consider this Dockerfile:

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

A user builds this file by calling:

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

The USER at line 2 evaluates to some_user as the user variable is defined on the
subsequent line 3. The USER at line 4 evaluates to what_user as user is
defined and the what_user value was passed on the command line. Prior to its definition by an
ARG instruction, any use of a variable results in an empty string.

Note: It is not recommended to use build-time variables for
passing secrets like github keys, user credentials etc.

You can use an ARG or an ENV instruction to specify variables that are
available to the RUN instruction. Environment variables defined using the
ENV instruction always override an ARG instruction of the same name. Consider
this Dockerfile with an ENV and ARG instruction.

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

Then, assume this image is built with this command:

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

In this case, the RUN instruction uses v1.0.0 instead of the ARG setting
passed by the user:v2.0.1 This behavior is similar to a shell
script where a locally scoped variable overrides the variables passed as
arguments or inherited from environment, from its point of definition.

Using the example above but a different ENV specification you can create more
useful interactions between ARG and ENV instructions:

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

Unlike an ARG instruction, ENV values are always persisted in the built
image. Consider a docker build without the —build-arg flag:

$ docker build Dockerfile

Using this Dockerfile example, CONT_IMG_VER is still persisted in the image but
its value would be v1.0.0 as it is the default set in line 3 by the ENV instruction.

The variable expansion technique in this example allows you to pass arguments
from the command line and persist them in the final image by leveraging the
ENV instruction. Variable expansion is only supported for a limited set of
Dockerfile instructions.

Docker has a set of predefined ARG variables that you can use without a
corresponding ARG instruction in the Dockerfile.

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

To use these, simply pass them on the command line using the --build-arg <varname>=<value> flag.

Impact on build caching

ARG variables are not persisted into the built image as ENV variables are.
However, ARG variables do impact the build cache in similar ways. If a
Dockerfile defines an ARG variable whose value is different from a previous
build, then a «cache miss» occurs upon its first usage, not its definition. In
particular, all RUN instructions following an ARG instruction use the ARG
variable implicitly (as an environment variable), thus can cause a cache miss.

For example, consider these two 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

If you specify --build-arg CONT_IMG_VER=<value> on the command line, in both
cases, the specification on line 2 does not cause a cache miss; line 3 does
cause a cache miss.ARG CONT_IMG_VER causes the RUN line to be identified
as the same as running CONT_IMG_VER=<value> echo hello, so if the <value>
changes, we get a cache miss.

Consider another example under the same command line:

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

In this example, the cache miss occurs on line 3. The miss happens because
the variable’s value in the ENV references the ARG variable and that
variable is changed through the command line. In this example, the ENV
command causes the image to include the value.

If an ENV instruction overrides an ARG instruction of the same name, like
this Dockerfile:

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

Line 3 does not cause a cache miss because the value of CONT_IMG_VER is a
constant (hello). As a result, the environment variables and values used on
the RUN (line 4) doesn’t change between builds.

ONBUILD

The ONBUILD instruction adds to the image a trigger instruction to
be executed at a later time, when the image is used as the base for
another build. The trigger will be executed in the context of the
downstream build, as if it had been inserted immediately after the
FROM instruction in the downstream Dockerfile.

Any build instruction can be registered as a trigger.

This is useful if you are building an image which will be used as a base
to build other images, for example an application build environment or a
daemon which may be customized with user-specific configuration.

For example, if your image is a reusable Python application builder, it
will require application source code to be added in a particular
directory, and it might require a build script to be called after
that. You can’t just call ADD and RUN now, because you don’t yet
have access to the application source code, and it will be different for
each application build. You could simply provide application developers
with a boilerplate Dockerfile to copy-paste into their application, but
that is inefficient, error-prone and difficult to update because it
mixes with application-specific code.

The solution is to use ONBUILD to register advance instructions to
run later, during the next build stage.

Here’s how it works:

1. When it encounters an ONBUILD instruction, the builder adds a
   trigger to the metadata of the image being built. The instruction
   does not otherwise affect the current build.
2. At the end of the build, a list of all triggers is stored in the
   image manifest, under the key OnBuild. They can be inspected with
   the docker inspect command.
3. Later the image may be used as a base for a new build, using the
   FROM instruction. As part of processing the FROM instruction,
   the downstream builder looks for ONBUILD triggers, and executes
   them in the same order they were registered. If any of the triggers
   fail, the FROM instruction is aborted which in turn causes the
   build to fail. If all triggers succeed, the FROM instruction
   completes and the build continues as usual.
4. Triggers are cleared from the final image after being executed. In
   other words they are not inherited by «grand-children» builds.

For example you might add something like this:

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

Warning: Chaining ONBUILD instructions using ONBUILD ONBUILD isn’t allowed.

Warning: The ONBUILD instruction may not trigger FROM or MAINTAINER instructions.

STOPSIGNAL

The STOPSIGNAL instruction sets the system call signal that will be sent to the container to exit.
This signal can be a valid unsigned number that matches a position in the kernel’s syscall table, for instance 9,
or a signal name in the format SIGNAME, for instance SIGKILL.

Dockerfile examples

Below you can see some examples of Dockerfile syntax. If you’re interested in
something more realistic, take a look at the list of Dockerization examples.

# 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.

Docker может создавать образы автоматически, читая инструкции из файла Dockerfile, по сути это текстовый документ, содержащий все команды, которые пользователь может вызвать в командной строке для сборки образа Images. С помощью команды docker build можно создать автоматизированную сборку, которая последовательно выполняет несколько инструкций командной строки.

Создавать новый образ есть смысл когда вы не можете найти подходящий для вашей задачи образ на hub.docker.com. Созданные образы можно также загружать на hub.docker.com и делать их доступными для других разработчиков.

Инструкции, при сборке образа обрабатываются сверху вниз. Слои в итоговом образе создают только инструкции FROM, RUN, COPY, ADD. Другие инструкции занимаются настройкой, описывают метаданные, или сообщают Docker о том, что во время выполнения контейнера нужно что-то сделать, например — открыть какой-то порт или выполнить какую-то команду.

Этапы создания

1. Необходимо создать докер файл это специальный файл с инструкциями для Docker по созданию нового образа, один докер файл для одного образа
2. Дальше докер файл помещают в корне папки приложения то есть если у вас уже есть папка в которой находится приложение тогда помещаете докер файл в корень проекта, это удобно тем что если вы например используете Git для контроля версии, Dockerfile всегда будет в вашем репозитории вместе с приложением
3. Каждая инструкция FROM, RUN, COPY, ADD в Dockerfile будет создавать новый слой в новом образе
4. При создании образа нужно указывать имя и тег для образа
5. На основании готового образа, создается контейнер

Типичный вид файла

Теперь давайте посмотрим как выглядит докер файл:

Это пример небольшого Dockerfile, в нём есть четыре инструкции:

• Инструкция FROM указывает на то, какой базовый образ будет использоваться для вашего образа, в данном примере базовый образ называется python а версия alpine
• Инструкция WORKDIR сдесь создаётся рабочая директория внутри образа. В данном примере указан путь /app и благодаря такой инструкции внутри образа будет создана папка. Рекомендуется всегда создавать папку внутри образа для вашего приложения, иначе можно например случайно перезаписать системные папки
• Инструкция COPY мы копируем все файлы из локальной текущей папки (первая точка) в папку указанную в директории WORKDIR (вторая точка). Когда необходимо скопировать файл с текущей папки на компьютере в папку внутри образа можно указывать в качестве целевой папке просто точку
• Инструкция CMD указывает, какая команда будет выполнена когда создается новый контейнер на основании уже созданного образа. В данном примере будет запущен процесс python и ему передаётся аргумент main.py. Иными словами мы запустим процесс python и он выполнит файл main.py, этот файл должен находиться в рабочей директории. Подразумевается что файл main.py мы скопируем с нашего компьютера на этапе инструкция COPY

Синтаксис файла Dockerfile

Работу с Dockerfile можно разбить на два этапа: описание инструкций и сборка образа. Набор инструкций — последовательность действий, чтобы собрать образ.

1. FROM установка родительского базового образа
2. RUN запуск команд терминала
3. COPY копирование файлов проекта
4. ADD копирует файлы по ссылке и распаковывавает локальные tar архивы
5. ENTRYPOINT предоставляет команду с аргументами для вызова во время выполнения контейнера, причем аргументы не переопределяются в командной строке пользователем
6. CMD предоставляет команду с аргументами для вызова во время выполнения контейнера, причем аргументы переопределяются в командной строке пользователем
7. ENV устанавливает постоянные переменные среды
8. WORKDIR задаёт рабочую папку проекта
9. USER задаёзапуск приложения от имени пользователя
10. EXPOSE указывает на необходимость открыть порт
11. ARG задаёт переменные для передачи Docker во время сборки образа
12. VOLUME создаёт точку монтирования для работы с постоянным хранилищем

FROM установка базового образа

Dockerfile обычно начинается с инструкции FROM. Эта инструкция задаёт базовый образ. В качестве базового образа может быть использован образ с чистой операционной системой, образ с уже установленной и настроенной платформой или вообще любой другой образ. Вот так можно установить Ubuntu 18.04 как базовый образ:

FROM ubuntu:18.04

Для установки Node.js alpine версии используют команду ниже:

FROM node

RUN запуск команд терминала

Инструкция RUN позволяет запускать команды терминала при сборке. Это самая используемая инструкция, ей можно создать папку, установить недостающие пакеты или запустить shell скрипт. Например, установим платформу Node.js поверх образа с чистой Ubuntu:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm

COPY копирование файлов проекта

Инструкции COPY позволяют перенести файлы с компьютера, который запускает сборку, внутрь образа. Например, перенесём все содержимое папки, где лежит Dockerfile в папку /app внутри образа:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
COPY . /app

ADD копирование файлов проекта

Инструкции ADD умеет скачивать файлы с сервера по ссылке и распаковывать tar-архивы.

Если собрать образ из этого Dockerfile и запустить контейнер, то окажется что команда ADD выкачала этот архив:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
ADD https://github.com/bessarabov/Moment/archive/1.3.1.tar.gz /app

В той же папке где лежит Dockerfile находится файл с архивом. Если собрать образ и запустить контейнер из этого образа то будет видно что ADD разархивировал этот tar.gz файл:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
ADD 1.3.1.tar.gz /app

Используйте COPY, она только копирует указанную папку во внутреннюю папку образа. Инструкция ADD слишком всемогущая и можно случайно использовать её неверно. Например, она может скачать файл из Интернета перед копированием или разархивировать архив.

ENTRYPOINT запуск приложения

После того как образ готов, необходимо запустить приложение, которое в нем содержится. Образы Docker задумывались как упаковка для приложения, поэтому нет ничего удивительного в существовании механизма запуска приложения при старте контейнера на основе собранного образа. Для этого используют инструкцию ENTRYPOINT. Инструкция используется для запуска приложения при старте контейнера. Вместе с командой запуска контейнера вы можете передавать параметры команде, которая прописана после ENTRYPOINT. Внутри контейнера можно запустить программу node и выполнить файл переданный через параметры /app/app.js:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
COPY . /app
ENTRYPOINT ["node", "/app/app.js"]

Есть две формы записи аргументов ENTRYPOINT: в виде строки и в виде массива строк. Первый вариант (так называемый shell режим) используется редко, поскольку не позволяет гибко настраивать работу образа. Обычно используется второй вариант (так называемый exec режим) — массив строк, который может состоять из команды и её параметров.

Используйте ENTRYPOINT, если вы не хотите, чтобы пользователь вашего образа переопределял поведение приложения в контейнере. Используйте CMD, если записываете команду по умолчанию, которую пользователь с лёгкостью может переопределить на этапе запуска контейнера.

CMD запуск приложения

Инструкция CMD делает практически то же самое, что и ENTRYPOINT. Обычно это также команда запуска приложения, она игнорируется в том случае, если пользователь вашего образа прописывает в явном виде, что и как запускать после запуска контейнера на основе образа. Часто CMD вообще используется для передачи параметров по умолчанию вашему приложению, которые пользователь может переопределить:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
COPY . /app
CMD ["node", "/app/app.js"]

Есть две формы записи аргументов CMD: в виде строки и в виде массива строк. Первый вариант (так называемый shell режим) используется редко, поскольку не позволяет гибко настраивать работу образа. Обычно используется второй вариант (так называемый exec режим) — массив строк, который может состоять из команды и её параметров. Среди аргументов инструкции CMD строка с командой может отсутствовать, если эта инструкция идёт после инструкции ENTRYPOINT. В этом случае строки массива рассматриваются как аргументы по умолчанию для команды, обозначенной в ENTRYPOINT.

Используйте ENTRYPOINT, если вы не хотите, чтобы пользователь вашего образа переопределял поведение приложения в контейнере. Используйте CMD, если записываете команду по умолчанию, которую пользователь с лёгкостью может переопределить на этапе запуска контейнера.

ENV переменные окружения

Переменные окружения задаются инструкцией ENV. Через переменные окружения передают ключи и пароли к сервисам, режим работы, другие секретные и не очень значения. Например, запуск приложения Node.js для конечного пользователя обозначается дополнительной инструкцией:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
COPY . /app
ENV NODE_ENV=production
CMD ["node", "/app/app.js"]

WORKDIR рабочая папка проекта

Инструкция WORKDIR задаёт рабочую папку приложения. Все инструкции в Dockerfile будут выполняться относительно неё. Устанавливать рабочую папку — хороший тон. Она позволяет явно указать место, где будет происходить вся работа. Добавим её в нашу конфигурацию:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
WORKDIR /app
COPY . .
ENV NODE_ENV=production
CMD ["node", "app.js"]

USER запуск от имени пользователя

Если приложение нужно запускать от имени пользователя системы, то используйте инструкцию USER с именем пользователя. Например, если вы хотите запускать приложение от имени пользователя node_user, то конфигурационный файл будет выглядеть так:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
WORKDIR /app
COPY . .
ENV NODE_ENV=production
USER node_user
CMD ["node", "app.js"]

EXPOSE проброска порта вовне

Для запуска веб-приложения на компьютере вы используете веб-сервер, запущенный локально. Обычно веб-приложение становится доступным по адресу http://localhost:8080. Цифры в конце означают порт, открытый для запросов со стороны браузера или других приложений. Чтобы открыть в браузере веб-приложение, запущенное внутри контейнера, нужно «пробросить» запросы от браузера внутрь контейнера, а ответ от веб-приложения из контейнера наружу. Для этого используется перенаправление пакетов в виртуальном сетевом окружении.

EXPOSE незаменим, когда в образе находится база данных и нам нужен доступ к ней вне контейнера. Запись EXPOSE 8080 означает, что на компьютере, на котором запущен Docker, веб-приложение будет доступно по адресу http://localhost:8080:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
WORKDIR /app
COPY . .
ENV NODE_ENV=production
USER node_user
EXPOSE 8080
CMD ["node", "app.js"]

ARG Аргументы командной строки

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

Передавать данные можно с помощью аргументов команды docker build на этапе сборки образа. Во время сборки эти аргументы можно использовать как переменные, достаточно их определить инструкцией ARG. Можно задать и значения по умолчанию на тот случай, если пользователь не укажет нужные аргументы. Например, передать имя пользователя внутрь контейнера можно следующим образом:

docker build --build-arg user=node_user .

В Dockerfile надо будет добавить соответствующие инструкции:

FROM ubuntu:18.04
RUN sudo apt update && sudo apt install nodejs && sudo apt install npm
WORKDIR /app
COPY . .
ENV NODE_ENV=production
# Значение по умолчанию 'deploy' (можно не указывать)
ARG user=deploy
USER $user
EXPOSE 8080
CMD ["node", "app.js"]

Важно, что так не следует передавать секретные данные, поскольку их можно будет увидеть в истории Docker: docker history. Для безопасной передачи секретных данных лучше использовать тома Docker.

VOLUME точка монтирования для работы с постоянным хранилищем

Инструкция VOLUME добавляет тома в образ, том это папка в одном или более контейнерах, проброшенная через Union File System (UFS). Тома могут быть расшарены или повторно использованы между контейнерами. Команда VOLUME используется для организации доступа вашего контейнера к директории на хосте (тоже самое, что и монтирование директории), команда определяет где контейнер будет хранить постоянные данные и получать к ним доступ:

VOLUME ["/opt/project"]

В примере выше создается точка монтирования /opt/project для любого контейнера, созданного из образа.

Многоступенчатая сборка образа

С точки зрения оптимизации сборки, уменьшения размера образа и ускорения приложения, образ можно собирать в несколько этапов. Например, с помощью платформы Node.js произвести сборку веб-приложения на первом этапе, а на втором — запустить готовый бандл с помощью веб-сервера. Операция копирования из первого промежуточного образа во второй целевой пройдёт совершенно незаметно. После сборки образ будет занимать мало дискового пространства, в нем будет все самое необходимое для работы веб-приложения:

# Сборка проекта на платформе Node.js
FROM node:lts-alpine as build-stage
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Запуск приложения на сервере
FROM nginx:stable-alpine as production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Имя промежуточного образа build-stage служит для передачи результата работы первой стадии сборки.

Рекомендации по сборке

Для того чтобы использовать образы эффективнее, необходимо следовать рекомендациям от команды Docker:

1. Нужно создавать образы так, чтобы жизненным циклом контейнера можно было удобно управлять. Образ не должен хранить внутреннее состояние. Данные внутрь образа можно передать на этапе сборки с помощью аргументов командной строки, а на этапе работы контейнера можно пользоваться томами Docker
2. Необходимо понимать контекст запуска веб-приложения: папка проекта, удалённый ресурс (remote source) или репозиторий
3. Надо понимать, что Dockerfile может запускаться вне контекста через стандартный поток ввода
4. Используйте файл .dockerignore для того, чтобы в образ попадали только нужные файлы и папки. От всего лишнего лучше избавиться на этапе сборки
5. Используйте сборку приложения в несколько стадий. Это позволит существенно уменьшить размер образа
6. Не устанавливайте то, что не будете использовать в образе
7. Необходимо разделять приложения на обособленные части, которые способны выполняться независимо. Этот процесс носит название декаплинга (Decoupling)
8. Минимизируйте количество слоёв в образе. Это повышает производительность образа как при сборке, так и при работе контейнера
9. Если параметры инструкции записываются в несколько строк (с помощью символа переноса строки ) необходимо выстраивать аргументы в алфавитном порядке. Это повышает читаемость файла и упрощает отладку
10. Используйте кэш Docker только для тех слоёв, которые будут нужны для сборки других образов. Для этого достаточно добавить параметр --no-cache=true в команду сборки docker build

Сборка образа

Образ Docker можно собрать тремя способами, чаще всего используется первый способ с указанием пути:

1. Указав путь к папке PATH
2. Указав путь к репозиторию URL
3. Используя стандартный поток ввода –

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

docker build .

Если вы хотите добавить определённое имя созданному образу то нужно использовать опцию -t. Если тег не указан, Docker сам подставит тег latest:

docker build . -t my_calendar:4.1.3

После создания образа, можно создавать контейнер используя указанное ранее имя образа my_calendar.

Использование нескольких Dockerfile

Иногда возникает необходимость использования нескольких вариантов сборок в одном проекте. В этом случае не обойтись без нескольких файлов с инструкциями. При сборке можно указать другое имя для файла конфигурации или относительный путь внутри PATH, нужно использовать флаг -f:

docker build -f containers/dockerfile-mode-1 .

Точно так же можно указать относительный путь для проекта или репозитория по некоторому URL. Например, Docker может скачать не только репозиторий GitHub, но и произвольный архив с проектом, распаковать его и собрать образ (поддерживаются архивы форматов bzip2, gzip, xz):

docker build -f ctx/Dockerfile http://server/ctx.tar.gz

Файлы и папки проекта, исполняемый файл приложения, архив или репозиторий Git составляют контекст образа. Но Docker позволяет собирать образы без контекста из стандартного потока ввода. Собрать такой образ можно командой:

docker build - < Dockerfile

Исключение файлов из сборки .dockerignore

Если вам не нужно включать в образ какие-то папки или файлы из контекста, добавьте в папку файл исключений .dockerignore. В этом файле перечисляются в отдельных строках все пути или маски путей, которые не должны быть помещены в образ. Пример файла:

# Комментарий
*/temp*
*/*/temp*
temp?

• */temp позволяет не включать в образ файлы или папки, имена которых начинаются на temp, и которые находятся в любой папке первого уровня например, /somedir/temporary.txt или /somedir/temp
• */*/temp* делает то же, но для папок второго уровня
• temp? позволяет не включать в образ файлы и папки из корневой папки образа, имена которых начинаются на temp и состоят из пяти символов, последний из которых может быть любым

Это третья часть серии статей про Docker и она всецело посвящена Docker-файлам. В первой части основные концепции Docker объясняются на простых примерах из жизни. Во второй статье — краткий обзор экосистемы Docker.

Docker-образ создаётся во время сборки, а Docker-контейнер — во время запуска приложения.

Docker-файл — сердце Docker’а. Он указывает Docker’у как построить образ, который будет использоваться при создании контейнера.

Каждый Docker-образ содержит файл с именем Dockerfile (он без расширения). При вызове docker build предполагается, что Dockerfile будет находиться в текущей рабочей директории. Но с помощью флага -f можно указать другое расположение.

Контейнер состоит из ряда слоёв. Все слои доступны только для чтения, кроме последнего — он располагается над остальными. Docker-файл указывает порядок добавления слоёв.

Каждый слой — это просто файл с изменением предыдущего слоя. В Unix практически всё является файлом.
Базовый слой, его ещё называют родительским, — это начальный слой.

При загрузке Docker-образа из удалённого репозитория скачиваются только отсутствующие у вас слои. Docker экономит место и время, повторно используя уже существующие слои.

Инструкция Docker-файла — слово в верхнем регистре, которое стоит перед аргументом какой-либо команды. Каждая строка в Docker-файле может содержать инструкцию, все они обрабатываются сверху вниз. Инструкции выглядят так:

FROM ubuntu:18.04
COPY . /app

И только инструкции FROM, RUN, COPY и ADD создают слои в конечном образе. Другие инструкции производят настройку, добавляют метаданные или же просто говорят Docker’у сделать что-либо во время запуска (например открыть порт или выполнить команду).

Эта статья предполагает использование Unix Docker-образа. Вы, конечно, можете использовать и Windows Docker-образ, но он медленнее, менее удобный и, вообще, его не часто применяют. Так что, пользуйтесь Unix по возможности.

Несколько Docker-инструкций

• FROM — задаёт родительский (главный) образ;
• LABEL — добавляет метаданные для образа. Хорошее место для размещения информации об авторе;
• ENV — создаёт переменную окружения;
• RUN — запускает команды, создаёт слой образа. Используется для установки пакетов и библиотек внутри контейнера;
• COPY  — копирует файлы и директории в контейнер;
• ADD  — делает всё то же, что и инструкция COPY. Но ещё может распаковывать локальные .tar файлы;
• CMD — указывает команду и аргументы для выполнения внутри контейнера. Параметры могут быть переопределены. Использоваться может только одна инструкция CMD;
• WORKDIR — устанавливает рабочую директорию для инструкции CMD и ENTRYPOINT;
• ARG — определяет переменную для передачи Docker’у во время сборки;
• ENTRYPOINT — предоставляет команды и аргументы для выполняющегося контейнера. Суть его несколько отличается от CMD, о чём мы поговорим ниже;
• EXPOSE — открывает порт;
• VOLUME — создаёт точку подключения директории для добавления и хранения постоянных данных.

Инструкции и примеры к ним

Docker-файл чисто теоретически может содержать только одну строчку:

FROM ubuntu:18.04

FROM

Docker-файл должен начинаться с инструкции FROM или ARG, за которой следует FROM. Команда FROM говорит Docker’у использовать базовый образ, который соответствует репозиторию и тегу.

В этом примере хранилище образов — Ubuntu. Ubuntu — название официального Docker-репозитория, в котором и содержится данная ОС.

Заметьте, что этот Docker-файл содержит тег для базового образа: 18.04, который указывает Docker’у, какую именно версию образа нужно использовать. Если тег не указан, по умолчанию берётся последняя версия образа. Но лучше всё же указывать тег базового образа. Когда Docker-файл, приведённый выше, используется для создания локального Docker-образа впервые, он загружает слои, указанные в образе Ubuntu.

При создании Docker-контейнера, вы помещаете наверх слой, который впоследствии можно будет изменить.

Когда образ запущен, и нужно произвести некоторые изменения, файл копируется на верхний слой, доступный для редактирования. Узнать, как это делается, можно здесь.

Подробнее про Docker-файл

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

FROM python:3.7.2-alpine3.8
LABEL maintainer="jeffmshale@gmail.com"
ENV ADMIN="jeff"

RUN apk update && apk upgrade && apk add bash

COPY . ./app

ADD https://raw.githubusercontent.com/discdiver/pachy-vid/master/sample_vids/vid1.mp4 
/my_app_directory

RUN ["mkdir", "/a_directory"]

CMD ["python", "./my_script.py"]

Но что же это всё обозначает?

В роли базового образа выступает официальный Python-образ с тегом 3.7.2-alpine3.8. Как вы можете увидеть из исходников, образ включает в себя Linux, Python и ничего более. Alpine-образы очень популярны, потому что они маленькие, быстрые и безопасные. Однако Alpine-образы не поставляются сразу со всеми компонентами, характерными для вашей ОС. Некоторые пакеты вам придётся установить самостоятельно.

LABEL

Следующая инструкция — LABEL. LABEL добавляет метаданные к образу, предоставляет контактную информацию. Она не замедляет процесс запуска и не занимает много места, наоборот, обеспечивает образ полезной информацией, так что обязательно используйте её. Больше про LABEL читайте здесь.

ENV

ENV создаёт переменную окружения, которая становится доступной во время запуска контейнера. В примере выше вы могли видеть использование переменной ADMIN при создании контейнера.

ENV удобна для обозначения констант. Если константа используется в нескольких местах файла Dockerfile, и вам понадобится изменить её значение позднее, это можно будет сделать в одном месте.

Docker-файл зачастую предоставляет несколько путей решения одной задачи. Будет хорошо, если в вашем решении будет учитываться баланс Docker-соглашений, прозрачность и скорость. К примеру, RUN, CMD и ENTRYPOINT служат различным целям и могут использоваться для выполнения команд.

RUN

RUN создаёт слой во время запуска. Docker фиксирует состояние образа после каждой инструкции RUN.

Чаще всего используется для установки нужных пакетов внутрь контейнера. В примере выше RUN apk update && apk upgrade говорит Docker’у обновить пакеты из базового образа. && apk add bash указывает на то, что для базового образа нужно установить bash.

apk — это сокращение от Alpine Linux package manager. Если вы используете базовый образ не Alpine Linux, то установка пакетов производится командой RUN apt-get.

RUN и её родственные инструкции: CMD, ENTRYPOINT — могут быть как форме оболочки, так и в форме shell-скрипта. Во втором случае используют JSON-синтаксис: RUN ["my_executable", "my_first_param1", "my_second_param2"]. А в примере выше использовалась форма оболочки: RUN apk update && apk upgrade && apk add bash.

Позднее в вашем Docker-файле вы будете создавать новую директорию, используя ["mkdir", "/a_directory"]. Не забывайте, что в JSON нужно использовать двойные кавычки!

COPY

Инструкция COPY . ./app говорит Docker’у, что нужно скопировать файлы и папки из вашей локальной сборки в рабочую директорию образа. COPY создаст все нужные папки, если они отсутствуют.

ADD

ADD делает то же самое, что и COPY, но с двумя отличиями. ADD может загружать файлы по URL, а также извлекать локальные TAR-файлы.

В примере выше ADD копировала файлы по URL внутрь директории контейнера. Но официальныя документация не рекомендует использовать ADD так, потому что потом вы попросту не сможете удалить файлы. А дополнительные файлы увеличивают размер образа.

Ещё официальная документация для ясности рекомендует использовать, когда это возможно, COPY вместе ADD. Жаль только, что в Docker’е невозможно использовать ADD и COPY в одной команде.

Заметьте, инструкция содержит символ . Это нужно для лучшей читаемости — так вы разбиваете длинную инструкцию на несколько строк.

CMD

CMD — инструкция для запуска чего-либо во время запуска самого контейнера. По ходу сборки она не фиксирует никакого результата. В примере выше во время сборки запускался скрипт my_script.py.

Ещё пара моментов о CMD:

• Только одна CMD-инструкция на весь Docker-файл. Иначе все кроме последней будут проигнорированы;
• CMD может включать исполняемый файл;
• Если же CMD не содержит никакого файла, обязательно должна быть инструкция ENTRYPOINT. В этом случает обе инструкции должны быть в формате JSON;
• Аргументы командной строки для запуска Docker переопределяют аргументы, предоставленные CMD в Docker-файле.

Готовы к большему?

В следующем примере представлены ещё несколько Docker-инструкций:

FROM python:3.7.2-alpine3.8
LABEL maintainer="jeffmshale@gmail.com"

# Install dependencies
RUN apk add --update git

# Set current working directory
WORKDIR /usr/src/my_app_directory

# Copy code from your local context to the image working directory
COPY . .

# Set default value for a variable
ARG my_var=my_default_value

# Set code to run at container run time
ENTRYPOINT ["python", "./app/my_script.py", "my_var"]

# Expose our port to the world
EXPOSE 8000

# Create a volume for data storage
VOLUME /my_volume

В Docker-файле вы можете добавлять комментарии. Комментарии начинаются со знака #.

Обычно установка пакетов — приоритетная задача для Docker’а. Как говорилось ранее, есть несколько способов загрузки пакетов при помощи инструкции RUN.

Для Alpine Docker-образа вы используете apk. apk для типичной Linux-сборки — apt-get. Например, пакеты для базового Ubuntu-образа могут быть установлены и обновлены так: RUN apt-get update && apt-get install my_package.

В дополнение к apk и apt-get, Python-пакеты могут быть установлены через pip, wheel и conda. Методы варьируются в зависимости от языка.

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

Можно использовать RUN вместе с pip и списком нужных пакетов. Для этого объедините команды установки пакетов в одну инструкцию и разделите их символом продолжения строки (). Этот метод позволяет улучшить читаемость и уменьшить количество слоев (из-за отсутствия возможности использовать несколько RUN инструкций).

Также вы можете запустить установщик, указав ему файл, содержащий все зависимости для вашего образа. Обычно он называется requirements.txt.

WORKDIR

Меняет текущую рабочую директорию в контейнере для инструкций: COPY, ADD, RUN и ENTRYPOINT.

Несколько замечаний:

• Предпочтительно задать абсолютный путь с помощью WORKDIR, а не перемещаться по файловой системе с помощью команд cd в Docker-файле;
• WORKDIR автоматически создаёт директорию, если её ещё нет;
• Можно использовать несколько WORKDIR-инструкций. Если используются относительные пути — каждая инструкция поменяет рабочую директорию.

ARG

Определяет переменную для передачи из командной строки в образ. Для ARG можно указать значение по умолчанию: ARG my_var=my_default_value.

В отличие от ENV-переменных, ARG-переменные не доступны для запущенных контейнеров. Однако вы можете использовать их для установки дефолтных значений для ENV-переменных, когда вы создаёте образ. И затем ENV-переменные сохраняются. Больше про это вы найдёте здесь.

ENTRYPOINT

ENTRYPOINT тоже позволяет вам задавать дефолтные команды и аргументы во время запуска контейнера. Она похожа на CMD, но параметры ENTRYPOINT не переопределяются, если контейнер запущен с параметрами командной строки.

Вместо этого аргументы командной строки, передаваемые docker run myimagename, добавляются к аргументам инструкции ENTRYPOINT. Например, docker run my_image bash добавляет аргумент bash в конец, ко всем другим аргументам ENTRYPOINT.

Docker-файл обязательно должен содержать либо CMD-инструкцию, либо ENTRYPOINT-инструкцию.
В официальной документации есть несколько советов, которые помогут сделать выбор между CMD и ENTRYPOINT для начальной команды:

• Если вам нужно запускать одну и туже команду несколько раз, выбирайте ENTRYPOINT;
• Используйте ENTRYPOINT, когда ваш контейнер выступает в роли исполняющейся программы;
• При наличии дополнительных дефолтных аргументов, которые могут быть изменены через командную строку, лучше подойдёт CMD.

В примере выше, ENTRYPOINT ["python", "my_script.py", "my_var"] запускает в контейнере Python-скрипт my_script.py с аргументом my_var. Затем переменная my_var может быть использована в my_script argparse. Заметьте, у my_var есть дефолтное значение, ранее установленное в Docker-файле при помощи ARG. Так что, если аргумент не будет задан через командную строку, возьмётся его значение по умолчанию.

Как правило, Docker рекомендует вам использовать исполняемую форму с JSON-синтаксисом ENTRYPOINT ["executable", "param1", "param2"].

EXPOSE

Инструкция EXPOSE показывает, какой порт пробрасывать из контейнера.

Используйте команду docker run с флагом -p для пробрасывания и сопоставления нескольких портов во время запуска. Флаг в верхнем регистре -P будет пробрасывать все открытые порты.

VOLUME

VOLUME определяет, где контейнер будет хранить постоянные данные и получать к ним доступ.

Заключение

В этой статье не были упомянуты такие инструкции, как USER, ONBUILD, STOPSIGNAL, SHELL, и HEALTHCHECK, информацию про них вы сможете найти здесь.

Перевод статьи «Learn Enough Docker to be Useful»