Как написать dockerfile

Время на прочтение
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-файлы.

Докер билдит контейнер автоматически с помощью. docker build, получая инструкции из Dockerfile и используя context.

Контекст сборки — это набор файлов в указанном месте PATH или URL. PATH — это каталог в вашей локальной файловой системе. URL-адрес — это расположение репозитория Git. Контекст сборки обрабатывается рекурсивно. Таким образом, PATH включает любые подкаталоги, а URL-адрес включает репозиторий и его подмодули.

Сборка выполняется демоном Docker, а не интерфейсом командной строки. Первое, что делает процесс сборки, это отправляет весь контекст (рекурсивно) демону. В большинстве случаев лучше начать с пустого каталога в качестве контекста и хранить файл Dockerfile в этом каталоге. Добавьте только те файлы, которые необходимы для создания Dockerfile. Не используйте свой корневой каталог / в качестве PATH для вашего контекста сборки, так как это приводит к тому, что сборка передает все содержимое вашего жесткого диска демону Docker.

Можно использовать флаг -f, чтобы указать на Dockerfile в любом месте вашей файловой системы.

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

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

docker build -t shykes/myapp .

# for multyple repositories
docker build -t shykes/myapp:1.0.2 -t shykes/myapp:latest .

Перед запуском инструкции докер валидирует Dockerfile и поднимает ошибку, если синтаксис некорректен. Инструкции Dockerfile выполняются демоном одна за одной. Каждая инструкция запускается независимо и вызывает создание нового образа, поэтому RUN cd /tmp не окажет никакого влияния на следующие инструкции.

Когда это возможно, Docker использует кэш сборки, чтобы значительно ускорить процесс сборки Docker. На это указывает сообщение CACHED в выводе консоли. Опция --cache-from также позволяет вам использовать кеш сборки, который распространяется через реестр образов.

Buildkit

BuildKit может:

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

BuildKit включается установкой DOCKER_BUILDKIT=1 через CLI перед выполнением docker build .

С Buildkit можно использовать syntax. Директива синтаксиса определяет расположение синтаксиса Dockerfile, который используется для создания Dockerfile.

Пользовательские реализации Dockerfile позволяют:

• Автоматически получать исправления ошибок без обновления демона Docker
• Быть уверенным, что все пользователи используют одну и ту же реализацию для создания вашего Dockerfil
• Использовать новейшие функции без обновления демона Docker
• Тестировать новые функции или сторонние функции до их интеграции в демоне Docker.
• Использовать альтернативные определения сборки или создайте свои собственные.

Формат Dockerfile

• Инструкции не чувствительна к регистру, при этом есть соглашение писать прописными
• Dockerfile должен начинаться с инструкции FROM (это может быть после директив синтаксического анализатора, комментариев и глобальных ARG.)
• коментарии начинаются с #, если это не валидные директивы дял парсера

• директивы парсера не обязательны и влияют на то как обрабатываются последующие строки. Пишутся как комментарии специального типа в виде # directive=value. Директивы не отображаются при сборке и одна директива используется только однажды. После обработки комментария, пустой строки или инструкции по сборщику Docker больше не ищет директивы синтаксического анализатора, поэтому они должны быть как можно выше в Dockerfile. Директивы не чувствительны к регистру.

    # directive=value1
    # directive=value2
  
    FROM ImageName
  

• escape директива устанавливает символ, используемый для экранирования символов в Dockerfile. Если он не указан, управляющим символом по умолчанию является .

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

Переменные, заданные в инструкции ENV могут использоваться в некоторых инструкциях Dockerfile. Синтаксис: $variable_name или ${variable_name}. Кроме того, поддерживается некоторое количество модификаторов bash:

• ${variable:-word} указывает, что если переменная установлена, результатом будет это значение. Если переменная не установлена, результатом будет word.
• ${variable:+word} указывает, что если переменная установлена, результатом будет word, в противном случае результатом будет пустая строка.

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

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

Переменные поддерживаются в след.инструкциях:

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

.dockerignore file

.dockerignore просматривается перед отправкой контекста дкмону. Влияет на инструкции ADD и COPY

Больше подробностей

Инеструкции

FROM

FROM [--platform=<platform>] <image> [AS <name>]

# or
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]

# or
FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]

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

• Перед FROM можно использовать только инструкцию ARG
• FROM может появляться несколько раз в одном Dockerfile для создания нескольких образов или использования одного этапа сборки в качестве зависимости для другого. Просто запишите идентификатор последнего изображения, выведенный фиксацией, перед каждой новой инструкцией FROM. Каждая инструкция FROM очищает любое состояние, созданное предыдущими инструкциями.
• При желании можно дать имя новому этапу сборки, добавив имя AS в инструкцию FROM. Это имя можно использовать в последующих инструкциях FROM и COPY --from=<name> для ссылки на образ, созданный на этом этапе.
• Значения тега или дайджеста являются необязательными. Если вы опустите любой из них, построитель по умолчанию примет последний тег. Билдер возвращает ошибку, если не может найти значение тега.
• Необязательный флаг --platform можно использовать для указания платформы образа в случае, если FROM ссылается на многоплатформенный образ

ARG, объявленная перед FROM, находится вне этапа сборки, поэтому ее нельзя использовать ни в одной инструкции после FROM. Чтобы использовать значение по умолчанию ARG, объявленное перед первым FROM, используйте инструкцию ARG без значения внутри этапа сборки

ARG VERSION=latest
FROM busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version

RUN

Два формата:

• RUN <command> (форма оболочки, команда запускается в оболочке, которая по умолчанию /bin/sh -c в Linux или cmd /S /C в Windows)
• RUN ["executable", "param1", "param2"] (exec form)

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

Форма exec позволяет выполнять команды с использованием базового образа, который не содержит указанный исполняемый файл оболочки. Дефолтный shell можно задать через команду SHELL

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

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

Через exec можно задать другую оболочку

RUN ["/bin/bash", "-c", "echo hello"]

Форма exec анализируется как массив JSON, что означает, что вы должны использовать двойные кавычки (“) вокруг слов, а не одинарные кавычки (‘).

В отличие от shell формы, форма exec не вызывает командную оболочку. Это означает, что нормальной обработки оболочки не происходит. Например, RUN [ "echo", "$HOME" ] не будет выполнять подстановку переменных в $HOME. Если вам нужна обработка оболочки, то либо используйте форму оболочки, либо запустите оболочку напрямую, например: RUN [ "sh", "-c", "echo $HOME" ]. При использовании формы exec и непосредственном выполнении оболочки, как и в случае с формой оболочки, расширение переменной среды выполняет оболочка, а не docker.

Кэш для инструкций RUN не становится недействительным автоматически во время следующей сборки. Кэш для такой инструкции, как RUN apt-get dist-upgrade -y, будет повторно использован во время следующей сборки. Кэш для инструкций RUN можно сделать недействительным с помощью флага --no-cache, например, docker build --no-cache.

CMD

Три формы:

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

В Dockerfile может быть только одна инструкция CMD. Если вы укажете более одного CMD, вступит в силу только последний CMD.

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

В отличие от shell формы, форма exec не вызывает командную оболочку. Это означает, что нормальной обработки оболочки не происходит.

Не путайте RUN с CMD. RUN фактически запускает команду и фиксирует результат; CMD ничего не выполняет во время сборки, но указывает запланированную команду для образа.

LABEL

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

Инструкция LABEL добавляет к образу метаданные. LABEL — это пара ключ-значение. Чтобы включить пробелы в значение LABEL, используйте кавычки и обратную косую черту, как при синтаксическом анализе командной строки. Можно задать любое количество меток для образа.

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

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

Метки родителей наследуются. Если метка уже есть — используется последняя.

MAINTAINER (deprecated)

EXPOSE

EXPOSE <port> [<port>/<protocol>...]

Открывает порты между контейнерами в сети в рантайм. Можно задать TCP или UDP.

Инструкция EXPOSE фактически не публикует порт. Он функционирует как тип документации между человеком, который создает образ, и человеком, который запускает контейнер, о том, какие порты предназначены для публикации. Чтобы фактически опубликовать порт при запуске контейнера, используйте флаг -p при запуске docker, чтобы опубликовать и сопоставить один или несколько портов, или флаг -P, чтобы опубликовать все открытые порты и сопоставить их с внешними портами.

ENV

Инструкция ENV устанавливает для переменной среды <key> значение <value>. Это значение будет в среде исполнения для всех последующих инструкций на этапе сборки и во многих случаях может быть заменено. Значение будет интерпретировано, поэтому символы кавычек будут удалены, если они не экранированы. Как и при синтаксическом анализе командной строки, для включения пробелов в значения можно использовать кавычки и обратную косую черту.

ENV MY_NAME="John Doe"
ENV MY_DOG=Rex The Dog
ENV MY_CAT=fluffy

ENV MY_NAME="John Doe" MY_DOG=Rex The Dog 
    MY_CAT=fluffy

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

Если переменные нужны только при сборке — рассмотирте вариант установления их только для исполняемой команды

RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ...

# or
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y ...

ADD

Две формы:

ADD [--chown=<user>:<group>] <src>... <dest>
ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]

Последняя форма требуется для путей, содержащих пробелы.

Инструкция ADD копирует новые файлы, каталоги или URL-адреса удаленных файлов из <src> и добавляет их в файловую систему образа по пути <dest>. Можно указать несколько ресурсов <src>, но если они являются файлами или каталогами, их пути интерпретируются как относительные к источнику контекста сборки. Каждый <src> может содержать подстановочные знаки, и сопоставление будет выполняться с использованием правил Go’s filepath.Match.

<dest> — это абсолютный путь или путь относительно WORKDIR, в который будет скопирован источник внутри целевого контейнера.

Пример для <WORKDIR>/relativeDir/:

ADD test.txt relativeDir/

Пример для /absoluteDir/:

ADD test.txt /absoluteDir/

Все новые файлы и каталоги создаются с UID и GID, равными 0, если только необязательный флаг --chown не указывает данное имя пользователя, имя группы или комбинацию UID/GID для запроса конкретного владельца добавленного контента.

ADD --chown=55:mygroup files* /somedir/
ADD --chown=bin files* /somedir/
ADD --chown=1 files* /somedir/
ADD --chown=10:11 files* /somedir/

Правила для ADD:

• Путь <src> должен находиться внутри контекста сборки; вы не можете ДОБАВИТЬ ../something/something, потому что первым шагом сборки docker является отправка каталога контекста (и подкаталогов) демону docker.
• Если <src> является URL-адресом, а <dest> не заканчивается косой чертой, то файл загружается с URL-адреса и копируется в <dest>.
• Если <src> является URL-адресом, а <dest> заканчивается косой чертой, то имя файла выводится из URL-адреса, и файл загружается в <dest>/<filename>. Например, ADD http://example.com/foobar/ создаст файл /foobar. URL-адрес должен иметь нетривиальный путь, чтобы в этом случае можно было обнаружить подходящее имя файла (http://example.com не будет работать).
• Если <src> является каталогом, копируется все содержимое каталога, включая метаданные файловой системы. Сам каталог не копируется.
• Если <src> является локальным tar-архивом в распознаваемом формате сжатия (identity, gzip, bzip2 или xz), то он распаковывается как каталог. Ресурсы с удаленных URL-адресов не распаковываются. Когда каталог копируется или распаковывается, он ведет себя так же, как tar -x.
• Если <src> является файлом любого другого типа, он копируется отдельно вместе со своими метаданными. В этом случае, если <dest> заканчивается косой чертой /, он будет считаться каталогом, а содержимое <src> будет записано в <dest>/base(<src>).
• Если указано несколько ресурсов <src>, либо напрямую, либо из-за использования подстановочного знака, то <dest> должен быть каталогом, и он должен заканчиваться косой чертой /.
• Если <dest> не заканчивается косой чертой, он будет считаться обычным файлом, а содержимое <src> будет записано в <dest>.
• Если <dest> не существует, он создается вместе со всеми отсутствующими каталогами на его пути.

COPY

Две формы

COPY [--chown=<user>:<group>] <src>... <dest>
COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]

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

Инструкция COPY копирует новые файлы или каталоги из <src> и добавляет их в файловую систему контейнера по пути <dest>.

При желании COPY принимает флаг --from=<name>, который можно использовать для установки исходного местоположения на предыдущую стадию сборки (созданную с помощью FROM .. AS <name>), которая будет использоваться вместо контекста сборки, отправленного пользователем. В случае, если этап сборки с указанным именем не может быть найден, вместо него делается попытка использовать образ с таким же именем.

Правила:

• Путь <src> должен находиться внутри контекста сборки; вы не можете Ккопировать ../something/something, потому что первым шагом сборки docker является отправка каталога контекста (и подкаталогов) демону docker.
• Если <src> является каталогом, копируется все содержимое каталога, включая метаданные файловой системы. Сам каталог не копируется, только его содержимое.
• Если <src> является файлом любого другого типа, он копируется отдельно вместе со своими метаданными. В этом случае, если <dest> заканчивается косой чертой /, он будет считаться каталогом, а содержимое <src> будет записано в <dest>/base(<src>).
• Если указано несколько ресурсов <src>, либо напрямую, либо из-за использования подстановочного знака, то <dest> должен быть каталогом, и он должен заканчиваться косой чертой /.
• Если <dest> не заканчивается косой чертой, он будет считаться обычным файлом, а содержимое <src> будет записано в <dest>.
• Если <dest> не существует, он создается вместе со всеми отсутствующими каталогами на его пути.

Разница между ADD и COPY в том, что ADD умеет скачивать удаленные файлы и умеет разворачимвать архивы.

ENTRYPOINT

Две формы:

# exec
ENTRYPOINT ["executable", "param1", "param2"]

# shell
ENTRYPOINT command param1 param2

ENTRYPOINT позволяет настроить контейнер, который будет работать как исполняемый файл. Например, следующий код запускает nginx с содержимым по умолчанию, прослушивая порт 80:

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

Аргументы командной строки для запуска docker run <image> будут добавлены после всех элементов в форме exec ENTRYPOINT и переопределят все элементы, указанные с помощью CMD. Это позволяет передавать аргументы в точку входа, т.е. docker run <image> -d передаст аргумент -d в точку входа. Вы можете переопределить инструкцию ENTRYPOINT, используя флаг docker run --entrypoint.

Shell форма предотвращает использование любых аргументов командной строки CMD или команд запуска, но имеет тот недостаток, что ваша ENTRYPOINT будет запущена как подкоманда /bin/sh -c, которая не передает сигналы. Это означает, что исполняемый файл не будет иметь PID 1 контейнера и не будет получать сигналы Unix, поэтому ваш исполняемый файл не получит SIGTERM от docker stop <container>.

Всегда применяется только последняя инструкция ENTRYPOINT

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

Вы можете указать простую строку для ENTRYPOINT, и она будет выполняться в /bin/sh -c. Эта форма будет использовать обработку оболочки для замены переменных среды оболочки и игнорировать любые аргументы командной строки CMD или docker run. Чтобы гарантировать, что docker stop будет правильно сигнализировать о любом длительно работающем исполняемом файле ENTRYPOINT, вам нужно не забыть запустить его с помощью exec. Пример

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

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

В таблице ниже показано, какая команда выполняется для разных комбинаций ENTRYPOINT/CMD:

VOLUME

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

Команда docker run инициализирует только что созданный том любыми данными, которые существуют в указанном месте в базовом образе.

• Тома в контейнерах на базе Windows: при использовании контейнеров на базе Windows место назначения тома внутри контейнера должно быть одним из: несуществующий или пустой каталог или диск, отличный от C:
• Изменение тома из Dockerfile: если какие-либо шаги сборки изменят данные внутри тома после его объявления, эти изменения будут отменены.
• Форматирование JSON: список анализируется как массив JSON. Вы должны заключать слова в двойные кавычки (“”), а не в одинарные кавычки (‘).
• Каталог хоста объявляется во время выполнения контейнера: каталог хоста (точка монтирования) по своей природе зависит от хоста. Это делается для сохранения переносимости образа, поскольку нельзя гарантировать, что данный каталог хоста будет доступен на всех хостах. По этой причине вы не можете смонтировать каталог хоста из Dockerfile. Инструкция VOLUME не поддерживает указание параметра host-dir. Вы должны указать точку монтирования при создании или запуске контейнера.

USER

USER <user>[:<group>]

# or
USER <UID>[:<GID>]

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

WORKDIR

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

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

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

WORKDIR поддерживает переменные

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

Дефолтный WORKDIR — /. Поэтому, чтобы избежать непреднамеренных операций в неизвестных каталогах, лучше всего указать свой WORKDIR явно.

ARG

ARG <name>[=<default value>]

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

FROM busybox
ARG user1
ARG buildno
# ...

Можно присваивать дефолтные значения

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

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

FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

FROM busybox
ARG SETTINGS
RUN ./run/other $SETTINGS

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

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=v1.0.0 # this used
RUN echo $CONT_IMG_VER

# solution
FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
RUN echo $CONT_IMG_VER

В отличие от инструкции ARG значения ENV всегда сохраняются в собраном образе.

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

Predefined ARGs:

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

Для buildkit бекенда доступны Automatic platform ARGs in the global scope

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

ONBUILD

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

STOPSIGNAL

Инструкция STOPSIGNAL устанавливает сигнал системного вызова, который будет отправлен контейнеру для выхода. Этот сигнал может быть именем сигнала в формате SIG<NAME>, например, SIGKILL, или числом без знака, которое соответствует положению в таблице системных вызовов ядра, например 9. По умолчанию используется значение SIGTERM, если оно не определено.

Сигнал остановки образа по умолчанию может быть переопределен для каждого контейнера с помощью флага --stop-signal при запуске и создании докера.

HEALTHCHECK

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

Два формата:

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

SHELL

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

Dockerfile best practices

Create ephemeral containers

Образ, определенный вашим Dockerfile, должен генерировать как можно более эфемерные контейнеры. Под «эфемерным» мы подразумеваем, что контейнер можно остановить и уничтожить, а затем перестроить и заменить с абсолютно минимальной настройкой и конфигурацией. См. раздел «Процессы»

Understand build context

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

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

Pipe Dockerfile through stdin

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

Build an image using a Dockerfile from stdin, without sending build context

Build from a local build context, using a Dockerfile from stdin

Build from a remote build context, using a Dockerfile from stdin

Exclude with .dockerignore

Чтобы исключить файлы, не относящиеся к сборке (без реструктуризации исходного репозитория), используйте файл .dockerignore. Этот файл поддерживает шаблоны исключения, аналогичные файлам .gitignore.

Use multi-stage builds

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

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

Например, если ваша сборка содержит несколько слоев, вы можете упорядочить их от менее часто изменяемых (чтобы обеспечить возможность повторного использования кэша сборки) к более часто изменяемым:

• Установите инструменты, необходимые для создания вашего приложения
• Установите или обновите зависимости библиотеки
• Создайте свое приложение

Пример

# syntax=docker/dockerfile:1
FROM golang:1.16-alpine AS build

# Install tools required for project
# Run `docker build --no-cache .` to update dependencies
RUN apk add --no-cache git
RUN go get github.com/golang/dep/cmd/dep

# List project dependencies with Gopkg.toml and Gopkg.lock
# These layers are only re-built when Gopkg files are updated
COPY Gopkg.lock Gopkg.toml /go/src/project/
WORKDIR /go/src/project/
# Install library dependencies
RUN dep ensure -vendor-only

# Copy the entire project and build it
# This layer is rebuilt when a file changes in the project directory
COPY . /go/src/project/
RUN go build -o /bin/project

# This results in a single layer image
FROM scratch
COPY --from=build /bin/project /bin/project
ENTRYPOINT ["/bin/project"]
CMD ["--help"]

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

На самом деле было очень распространено иметь один файл Dockerfile для разработки (который содержал все необходимое для создания вашего приложения) и урезанный файл для использования в производстве, который содержал только ваше приложение и именно то, что было необходимо для его запуска. Это называется «шаблон строителя». Поддерживать два файла Dockerfile не идеально.

Такой искусственный подход показан тут — команда RUN сжата с помощью && что делает ее подверженной ошибкам

# syntax=docker/dockerfile:1
FROM golang:1.16
WORKDIR /go/src/github.com/alexellis/href-counter/
COPY app.go ./
RUN go get -d -v golang.org/x/net/html 
  && CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

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

# syntax=docker/dockerfile:1
FROM golang:1.16
WORKDIR /go/src/github.com/alexellis/href-counter/
RUN go get -d -v golang.org/x/net/html
COPY app.go ./
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=0 /go/src/github.com/alexellis/href-counter/app ./
CMD ["./app"]

Теперь нужен только один Dockerfile, не нужно разделять build-скрипты.

Конечным результатом является то же крошечное производственное изображение, что и раньше, со значительным снижением сложности. Вам не нужно создавать какие-либо промежуточные образы и вообще не нужно извлекать какие-либо артефакты в вашу локальную систему.

Как это работает? Вторая инструкция FROM запускает новую стадию сборки с образцом alpine:latest в качестве основы. Строка COPY --from=0 копирует только созданный артефакт из предыдущего этапа в этот новый этап. Go SDK и любые промежуточные артефакты остаются позади и не сохраняются в конечном образе.

Хорошей практикой является создание именванных build-этапов

# syntax=docker/dockerfile:1
FROM golang:1.16 AS builder
WORKDIR /go/src/github.com/alexellis/href-counter/
RUN go get -d -v golang.org/x/net/html
COPY app.go    ./
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /go/src/github.com/alexellis/href-counter/app ./
CMD ["./app"]

Кроме того, можно останавливаться на специфическом этапе сборки

docker build --target builder -t alexellis2/href-counter:latest .

Это открывает путь к следующим опциям:

• Отладка определенного этапа сборки
• Использование этапа отладки со всеми включенными символами или инструментами отладки, а также этапа “бережливой” стадии сборки.
• Использование этапа тестирования, на котором ваше приложение заполняется тестовыми данными, но сборка для производства производится с использованием другого этапа, который использует реальные данные.

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

COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf

Наконец, предыдущзий этап можно использовать в качестве следующего

# syntax=docker/dockerfile:1
FROM alpine:latest AS builder
RUN apk --no-cache add build-base

FROM builder AS build1
COPY source1.cpp source.cpp
RUN g++ -o /binary source.cpp

FROM builder AS build2
COPY source2.cpp source.cpp
RUN g++ -o /binary source.cpp

Don’t install unnecessary packages

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

Decouple applications

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

Ограничение каждого контейнера одним процессом — хорошее эмпирическое правило, но это не жесткое правило. Например, не только контейнеры могут быть порождены процессом инициализации, некоторые программы могут порождать дополнительные процессы по собственному желанию. Например, Celery может порождать несколько рабочих процессов, а Apache может создавать по одному процессу на каждый запрос.

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

Minimize the number of layers

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

• Только инструкции RUN, COPY, ADD создают слои. Другие инструкции создают временные промежуточные образы и не увеличивают размер сборки.
• По возможности используйте многоэтапные сборки и копируйте в окончательный образ только те артефакты, которые вам нужны. Это позволяет включать инструменты и информацию об отладке на промежуточных этапах сборки без увеличения размера конечного образа.

Sort multi-line arguments

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

RUN
apt-get update && apt-get install -y 
  bzr 
  cvs 
  git 
  mercurial 
  subversion 
  && rm -rf /var/lib/apt/lists/*

Leverage build cache

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

Если вы вообще не хотите использовать кеш, вы можете использовать параметр —-no-cache=true в команде сборки docker. Однако, если вы разрешаете Docker использовать свой кеш, важно понимать, когда он может и не может найти подходящее изображение. Основные правила, которым следует Docker, изложены ниже:

• Начиная с родительского образа, который уже находится в кэше, следующая инструкция сравнивается со всеми дочерними образами, полученными из этого базового образа, чтобы определить, был ли один из них создан с использованием той же самой инструкции. В противном случае кеш становится недействительным.
• В большинстве случаев достаточно просто сравнить инструкцию в Dockerfile с одним из дочерних образов. Однако некоторые инструкции требуют дополнительного изучения и пояснений.
• Для инструкций ADD и COPY проверяется содержимое файла(ов) в образе и для каждого файла вычисляется контрольная сумма. В этих контрольных суммах время последнего изменения и последнего доступа к файлу (файлам) не учитывается. Во время поиска в кэше контрольная сумма сравнивается с контрольной суммой в существующих образах. Если что-то изменилось в файле (файлах), например, содержимое и метаданные, кэш становится недействительным.
• Помимо команд ADD и COPY, проверка кеша не просматривает файлы в контейнере, чтобы определить совпадение с кешем. Например, при обработке команды RUN apt-get -y update файлы, обновленные в контейнере, не проверяются на наличие попадания в кэш. В этом случае для поиска соответствия используется только сама командная строка.
• Как только кеш становится недействительным, все последующие команды Dockerfile генерируют новые изображения, а кеш не используется.

Dockerfile instructions

FROM

По возможности используйте текущие официальные изображения в качестве основы для ваших изображений. Мы рекомендуем образ Alpine, так как он строго контролируется и имеет небольшой размер (в настоящее время менее 6 МБ), но при этом является полноценным дистрибутивом Linux.

LABEL

Docker object labels

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

Начиная с Docker 1.10 рекомендуется комбинировать всю информацию в одну метку

# Set multiple labels on one line
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"

# or
# Set multiple labels at once, using line-continuation characters to break long lines
LABEL vendor=ACME Incorporated 
      com.example.is-beta= 
      com.example.is-production="" 
      com.example.version="0.0.1-beta" 
      com.example.release-date="2015-02-12"

RUN

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

apt-get

Вероятно, наиболее распространенным вариантом использования RUN является apt-get. Поскольку он устанавливает пакеты, у команды RUN apt-get есть несколько ошибок, на которые следует обратить внимание.

Всегда комбинируйте RUN apt-get update с apt-get install в одном операторе RUN.

RUN apt-get update && apt-get install -y 
    package-bar 
    package-baz 
    package-foo  
    && rm -rf /var/lib/apt/lists/*

Использование только apt-get update в операторе RUN вызывает проблемы с кэшированием, и последующие инструкции по установке apt-get не выполняются. Использование RUN apt-get update && apt-get install -y гарантирует, что ваш файл Dockerfile установит последние версии пакетов без дальнейшего кодирования или ручного вмешательства.

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

RUN apt-get update && apt-get install -y 
    aufs-tools 
    automake 
    build-essential 
    curl 
    dpkg-sig 
    libcap-dev 
    libsqlite3-dev 
    mercurial 
    reprepro 
    ruby1.9.1 
    ruby1.9.1-dev 
    s3cmd=1.1.* 
 && rm -rf /var/lib/apt/lists/*

rm -rf /var/lib/apt/lists/* это уменьшает размер изображения, поскольку кеш apt не хранится в слое. Поскольку инструкция RUN начинается с обновления apt-get, кэш пакетов всегда обновляется перед установкой apt-get. Официальные образы Debian и Ubuntu автоматически запускают apt-get clean, поэтому явный вызов не требуется.

Using pipes

Некоторые команды RUN зависят от возможности передавать вывод одной команды в другую с помощью символа вертикальной черты |

Docker выполняет эти команды с помощью интерпретатора /bin/sh -c, который оценивает только код выхода последней операции в канале, чтобы определить успех.

Если вы хотите, чтобы команда завершилась ошибкой из-за ошибки на любом этапе конвейера, добавьте set -o pipefail &&, чтобы гарантировать, что непредвиденная ошибка предотвратит непреднамеренное успешное выполнение сборки.

# no pipe
RUN wget -O - https://some.site | wc -l > /number

# pipe
RUN set -o pipefail && wget -O - https://some.site | wc -l > /number

CMD

Инструкцию CMD следует использовать для запуска программного обеспечения, содержащегося в вашем образе, вместе с любыми аргументами. CMD почти всегда следует использовать в форме CMD ["исполняемый", "param1", "param2"…]. Таким образом, если образ предназначен для службы, такой как Apache и Rails, вы должны запустить что-то вроде CMD ["apache2","-DFOREGROUND"]. Действительно, такая форма инструкции рекомендуется для любого сервисного образа.

В большинстве других случаев CMD должна иметь интерактивную оболочку, такую как bash, python и perl. Например, CMD ["perl", "-de0"], CMD ["python"] или CMD ["php", "-a"]. Использование этой формы означает, что когда вы выполняете что-то вроде docker run -it python, вы попадаете в пригодную для использования оболочку, готовую к работе. CMD редко следует использовать в манере CMD ["param", "param"] в сочетании с ENTRYPOINT, если только вы и ваши предполагаемые пользователи уже не знакомы с тем, как работает ENTRYPOINT.

EXPOSE

Инструкция EXPOSE указывает порты, на которых контейнер прослушивает соединения. Следовательно, вы должны использовать общий, традиционный порт для вашего приложения. Например, изображение, содержащее веб-сервер Apache, будет использовать EXPOSE 80, а изображение, содержащее MongoDB, будет использовать EXPOSE 27017 и так далее.

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

ENV

Чтобы упростить запуск нового программного обеспечения, вы можете использовать ENV для обновления переменной среды PATH для программного обеспечения, которое устанавливает ваш контейнер. Например, ENV PATH=/usr/local/nginx/bin:$PATH гарантирует, что CMD ["nginx"] просто работает.

Инструкция ENV также полезна для предоставления необходимых переменных среды, специфичных для служб, которые вы хотите контейнеризовать, таких как PGDATA Postgres.

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

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

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

Каждая строка ENV создает новый промежуточный уровень, как команды RUN. Это означает, что даже если вы сбросите переменную среды в будущем слое, она все равно сохранится в этом слое, и ее значение может быть сброшено. Чтобы предотвратить это и действительно сбросить переменную среды, используйте команду RUN с командами оболочки, чтобы устанавливать, использовать и сбрасывать переменную на одном уровне

ADD or COPY

Хотя ADD и COPY функционально схожи, обычно предпочтение отдается COPY. Это потому, что он более прозрачен, чем ADD. COPY поддерживает только базовое копирование локальных файлов в контейнер, в то время как ADD имеет некоторые функции (например, локальное извлечение tar и удаленную поддержку URL), которые не сразу очевидны. Следовательно, лучшим применением для ADD является автоматическое извлечение локального tar-файла в образ.

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

COPY requirements.txt /tmp/
RUN pip install --requirement /tmp/requirements.txt
COPY . /tmp/

В примере выше это приводит к меньшему количеству инвалидаций кеша для шага RUN, чем если бы вы поместили COPY . /tmp/` перед ним.

Поскольку размер изображения имеет значение, использование ADD для получения пакетов с удаленных URL-адресов настоятельно не рекомендуется; вместо этого вы должны использовать curl или wget. Таким образом, вы можете удалить файлы, которые вам больше не нужны, после того, как они были извлечены, и вам не нужно добавлять еще один слой в ваше изображение. Например, вам следует избегать таких действий, как:

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

# right
RUN mkdir -p /usr/src/things 
    && curl -SL https://example.com/big.tar.xz 
    | tar -xJC /usr/src/things 
    && make -C /usr/src/things all

ENTRYPOINT

Лучшее использование для ENTRYPOINT — установить основную команду образа, позволяя этому образу запускаться, как если бы это была эта команда (и затем использовать CMD в качестве флагов по умолчанию).

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

Пример:

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

COPY ./docker-entrypoint.sh /
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["postgres"]

VOLUME

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

USER

Если служба может работать без привилегий, используйте USER, чтобы изменить пользователя без полномочий root. Избегайте установки или использования sudo, так как он имеет непредсказуемое поведение TTY и переадресации сигналов, что может вызвать проблемы. Если вам абсолютно необходима функциональность, аналогичная sudo, например инициализация демона с правами root, но запуск его без полномочий root, рассмотрите возможность использования «gosu».

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

WORKDIR

Для ясности и надежности вы всегда должны использовать абсолютные пути для вашего WORKDIR. Кроме того, вы должны использовать WORKDIR вместо множащихся инструкций, таких как RUN cd … && do-something, которые трудно читать, устранять неполадки и поддерживать.

ONBUILD

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

Сборка Docker выполняет команды ONBUILD перед любой командой в дочернем файле Docker.

ONBUILD полезен для образов, которые собираются ИЗ заданного образа. Например, вы могли бы использовать ONBUILD для образа языкового стека, который создает произвольное пользовательское программное обеспечение, написанное на этом языке.

Образы, созданные с помощью ONBUILD, должны иметь отдельный тег, например: ruby:1.9-onbuild или ruby:2.0-onbuild.

Будьте осторожны, добавляя ADD или COPY в ONBUILD. Образ «onbuild» приводит к катастрофическому сбою, если в контексте новой сборки отсутствует добавляемый ресурс. Добавление отдельного тега, как рекомендовано выше, помогает смягчить это, позволяя автору Dockerfile сделать выбор.

Смотри еще:

• dockerfile references
• Best practices for writing Dockerfiles
• [docker]
• [docker-compose]

Примечание: Не путайте RUN и CMD. RUN выполняет команду и делает коммит результата; CMD ничего не выполняет во время сборки, но задает команду которая будет выполнена при запуске образа.

EXPOSE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#!/bin/bash
set -e

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

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

    exec gosu postgres "$@"
fi

exec "$@"

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

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

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

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

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

echo "exited $0"

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

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

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

FROM ubuntu
ENTRYPOINT exec top -b

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

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

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

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

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

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

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

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

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

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

USER

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

WORKDIR

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

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

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

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

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

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

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

ARG

ARG <name>[=<default value>]

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

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

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

FROM busybox
ARG user1
ARG buildno
...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ docker build Dockerfile

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

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

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

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

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

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

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

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 RUN echo $CONT_IMG_VER

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 RUN echo hello

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

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

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

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

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

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

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

ONBUILD

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

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

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

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

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

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

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

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

STOPSIGNAL

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

HEALTHCHECK

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SHELL

SHELL ["executable", "parameters"]

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

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

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

FROM windowsservercore

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

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

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

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

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

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

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

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

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

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

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

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

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

# escape=`

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

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

    Directory: C:

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

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

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

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

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

Примеры Dockerfile

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

# Nginx
#
# VERSION               0.0.1

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

LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0"
RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server

# Firefox over VNC
#
# VERSION               0.3

FROM ubuntu

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

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

# Multiple images example
#
# VERSION               0.1

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

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

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