Как называется инструкция сборки образа docker

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

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

В переводе третьей части серии материалов, посвящённых 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-файлы.

Примечание: Не путайте 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.

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 и состоят из пяти символов, последний из которых может быть любым

Опорные статьи:

https://habr.com/ru/post/253877/

https://tproger.ru/translations/docker-terms/

https://tproger.ru/translations/docker-instuction/

https://xakep.ru/2015/06/01/docker-usage/

https://xakep.ru/2015/06/04/docker-faq/

Официальная документация:

https://docs.docker.com/

https://docs.docker.com/develop/develop-images/dockerfile_best-practices/

Для обычного бытового использования Docker интересен тем, что позволяет собирать программы без смешивания их пакетов с системными и запускать изолированно в контейнере. Это особенно важно при использовании дистрибутивов с длительным сроком поддержки (LTS).

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

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

Основы использования Docker.

Установка:

sudo apt install docker.io

Базовая проверка работоспособности docker:

sudo docker run hello-world

В выводе должно оказаться нечто подобное:

Если демон Docker по какой-то причине не запустился, будет показано предупреждение:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Запуск можно сделать вручную:

sudo service docker start

Образы.

Образы загружаются из специального хранилища — docker-реестра: https://hub.docker.com/ В нём хранятся публичные и приватные образы. Можно сформировать собственное хранилище образов или экспортировать образ в файл, что позволит поделиться им любым удобным образом.

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

Образы делятся на базовые (Base images) и дочерние (Child images).

Базовые образы — как правило, содержат в себе операционную систему. (Ubuntu, Debian и подобные).

Дочерние образы — зависят от базовых.

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

Загрузить образ из https://hub.docker.com/:

sudo docker pull <название_образа>

Можно выбрать конкретную версию образа:

sudo docker pull ubuntu:20.04

В данном случае это Ubuntu 20.04.

Поиск образов в реестре. Найти все образы Ubuntu 20.xx:
sudo docker search ubuntu-20

Вывести список всех загруженных образов:

sudo docker images

Удалить образ:

sudo docker rmi <IMAGE ID>

Пример:

sudo docker rmi 56def654ec22

Принудительно удалить образ:

sudo docker rmi -f <IMAGE ID>

—f — отфильтровать образы или контейнеры по предоставленному условию. В данном случае по ID образа.

Удалить образы, которые не используются ни одним контейнером:

sudo docker image prune -a -f

Контейнеры.

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

Вывести список всех контейнеров:

sudo docker ps -a

Вывести список только запущенных контейнеров:

sudo docker ps --no-trunc

—no-trunc — не обрезать вывод. К примеру, будут полностью отображены ID, вместо их сокращения.

Место хранения контейнеров: /var/lib/docker/

Создание и запуск контейнера осуществляется с помощью команды run.

docker run --help

Создание и запуск контейнера на примере busybox (комплект консольных утилит):

sudo docker run busybox echo "hello world"

Из реестра (хранилища) hub.docker.com будет загружен образ busybox (если его нет на локальной машине), из образа будет создан контейнер, внутри которого будет запущена утилита echo, которая отправит в вывод строку «hello world».

Запустить ранее созданный контейнер:

sudo docker start <ID>

Остановить работу контейнера:

sudo docker stop <ID>

Подключение к запущенному контейнеру:

sudo docker exec -it <ID> sh

Контейнеры можно удалить по имени и по ID. Команда:

sudo docker rm <ID>

Пример:

sudo docker rm 791834eb255d

Принудительное удаление запущенного контейнера:

sudo docker rm -f <ID>

Удалить все остановленные контейнеры:

sudo docker container prune -f

Создание и запуск контейнера с желаемым именем (в примере my-busy) с последующим запуском echo, которая выведет строку «hello world»:

sudo docker run --name my-busy busybox echo "hello world"

Создать и запустить контейнер, а затем удалить его по завершению работы (опция —rm).

sudo docker run --rm busybox echo "hello world"

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

Вывести потребляемые контейнером ресурсы:

sudo docker stats <ID>

В контейнеры можно монтировать каталоги основной системы.

Dockerfile и создание собственных образов.

Официальная документация: https://docs.docker.com/engine/reference/builder/

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

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

Собственные образы и контейнеры очень удобно применять для сборки программ. Это особенно актуально при использовании дистрибутивов с длительным сроком поддержки (LTS). Ключевым является то, что не придётся смешивать различные зависимости и самосборные пакеты с системными пакетами. Все они будут изолированы в контейнере, что позитивно скажется на безопасности и стабильности системы.

Наполнение Dockerfile.

Пример содержимого Dockerfile:

# базовый образ
FROM ubuntu:20.04

# установка желаемых пакетов и зависимостей
RUN apt-get update
RUN apt-get install -y wget && echo "We installed wget!"

# создание каталога /mytest
WORKDIR /mytest

# создание файла testfile
RUN touch testfile

# ls и echo будут выполняться при запуске контейнера
CMD ls && echo "Show me mytest"

Каждая строка с командами является инструкцией. Инструкции выполняются одна за другой.

Примечание: Docker рекомендует использовать именно apt-get.

Основные инструкции.

FROM — указать имя базового образа, из которого будет создан собственный образ. Базовый образ будет загружен, если его нет на локальной машине. Dockerfile всегда должен начинаться с FROM.

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

Команды выполняются последовательно, то есть результат первой порции команд, перечисленных в инструкции RUN, не влияет на команды, перечисленные в следующей RUN. Пример: RUN cd /tmp не будет действовать для RUN ls, то есть ls выведет каталоги корня, а не /tmp.

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

WORKDIR — создать и/или выбрать рабочий каталог внутри образа, в котором будут выполнены последующие команды, перечисленные в инструкциях RUN и CMD. Особенно полезно при сборке программ.

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

ENV — объявить переменную окружения, которая будет использоваться в контейнере.

ENTRYPOINT — запускает указанную программу с желаемыми параметрами при старте контейнера. Команды можно записывать в синтаксисе JSON. Обычно указывается в конце Dockerfile. Пример: ENTRYPOINT [«/bin/sh», «-c»]

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

Прочие инструкции можно посмотреть в официальной документации: https://docs.docker.com/engine/reference/builder/

Пример создания образа.

Команда на создание образа:

sudo docker build -f </путь/до/Dockerfile> -t <имя_создаваемого_образа> </путь/до/контекста>

-f — используется, чтобы указать путь до конкретного Dockerfile. Без этой опции демон Docker будет искать Dockerfile в каталоге выполнения.

-t — имя (тэг) создаваемого образа. В обычном случае создаётся локальный образ с указанным именем, но можно загрузить создаваемый образ в репозиторий, если указать имя пользователя в реестре hub.docker.com, а затем аутентификационные данные. Пример: docker build -t myuser/myimage .

</путь/до/контекста> — это аргумент, указывающий демону контекст сборки, то есть какие файлы и каталоги использовать для сборки образа. Если не планируется добавлять какие-то конкретные файлы и каталоги, то достаточно указать любой пустой каталог. Sending build context to Docker daemon — процесс упаковки и отправки файлов демону для сборки образа. Образ будет собираться в специальном временном каталоге. Указанные файлы будут скопированы, упакованы (tar-архив) и помещены в специальный каталог для последующей сборки. После сборки скопированные файлы будут удалены, а оригиналы останутся без изменений.

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

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

Альтернативный способ создания образа.

Docker позволяет сохранить изменения, которые были сделаны в контейнере, в отдельный образ. То есть можно настроить содержимое контейнера (установить желаемые пакеты и тому подобное), затем сохранить всё в новый образ, из которого можно будет запускать уже настроенный контейнер.

sudo docker commit <ID_контейнера> <имя_нового_образа>

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

Поделиться Docker-образом без использования hub.docker.com.

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

sudo docker save --output <имя_файла_образа> <ID_исходного_образа>

Пример сохранения образа ubuntu в файл-образ с именем my-exp-ubuntu.tar в каталог ~/Documents/.

sudo docker save --output ~/Documents/my-exp-ubuntu.tar ubuntu

Чтобы использовать сохранённый образ, его необходимо импортировать:

sudo docker load --input <имя_файла_образа>

sudo docker load --input ~/Downloads/my-exp-ubuntu.tar

Примеры использования Docker.

Монтирование каталогов в контейнер Docker.

Официальная документация:

https://docs.docker.com/storage/volumes/

Docker позволяет монтировать каталоги основной системы в контейнеры, что делает доступным их содержимое для утилит внутри контейнера. К примеру, можно смонтировать в контейнер каталог ~/Video/, чтобы обработать его содержимое с помощью ffmpeg, который находится в контейнере.

Использование на примере busybox.

Создать контейнер из образа busybox, примонтировать каталог ~/Documents/ к контейнеру, запустить утилиту ls внутри контейнера для смонтированного в него каталога, вывести результат и удалить контейнер:

sudo docker run -v ~/Documents/:/mnt/ --rm busybox ls /mnt/

-v — указывает хранилище, которое будет смонтировано в контейнер. Хранилище представляет собой обычный ранее созданный каталог, в котором могут содержаться другие каталоги и файлы. При монтировании контейнер получит доступ к этому каталогу и всему его содержимому. В примере это каталог ~/Documents/.

/mnt — обозначает точку монтирования. В примере это ~/Documents/. Пример пути: /mnt/каталог/файл, что является аналогичным ~/Documents/каталог/файл.

—rm — удалить контейнер после завершения его работы.

Использование интерпретатора sh из контейнера.

sudo docker run --rm -it busybox sh

Образ busybox будет загружен из реестра hub.docker.com (если его нет на локальной машине), из образа busybox будет создан контейнер, внутри которого будет запущена утилита sh, после чего станет доступным ввод команд, которые будут выполняться утилитами busybox внутри контейнера. После завершения работы контейнера он будет удалён (опция —rm).

-i — интерактивный режим.

-t — проброс терминала в контейнер.

Благодаря опции -it будет выделен псевдо-tty, работающий в интерактивном режиме, а не только на вывод, что позволит выполнять команды внутри контейнера через терминал. Без опции -it утилита sh будет запущена единожды, отобразится вывод и работа контейнера завершится.

Команда ls покажет набор каталогов от корня внутри контейнера:

Пример перехода в каталог /bin и выполнение команды ls:

На иллюстрации показано всё многообразие утилит из комплекта busybox.

Для завершения работы этого контейнера необходимо ввести exit.

Использование браузера elinks из контейнера.

Ниже рассмотрен пример установки в контейнер текстового браузера elinks и сохранения изменений в образ.

На базе образа ubuntu будет создан контейнер с именем —name my-base-ubuntu:

sudo docker run -it --name my-base-ubuntu ubuntu sh

При этом с помощью опции -it пробрасывается терминал в интерактивной сессии и запускается утилита sh.

Теперь можно выполнять команды непосредственно внутри контейнера.

Установка браузера elinks:

apt-get update

apt-get install elinks

После завершения установки пакетов можно завершить сессию:

exit

Проверяем наличие контейнера в списке контейнеров:

sudo docker ps -a

Теперь предстоит сохранение изменений, которые были сделаны в контейнере (установлены пакеты для браузера elinks), в образ:

sudo docker commit my-base-ubuntu my-ubuntu-elinks

Сначала указывается имя контейнера (можно указать ID), а потом имя для образа, который будет создан. В данном случае будет создан образ с именем my-ubuntu-elinks.

Проверим наличие образа. Вывести список всех доступных образов:

sudo docker images

Теперь можно удалить контейнер, из которого был создан образ:

sudo docker rm my-base-ubuntu

Создание контейнера из свежесозданного образа и запуск браузера в интерактивной сессии проброшенного терминала:

sudo docker run -it --rm my-ubuntu-elinks elinks

Результат:

Благодаря опции —rm, контейнер будет удалён после завершения работы.

Использование на примере Cmake-Converter.

Официальная документация: https://cmakeconverter.readthedocs.io/en/latest/intro.html

Программа предназначена для автоматического преобразования солюшена (.sln) Visual Studio в CmakeLists.txt. Программа написана на Python и доступна из репозитория посредством пакетного менеджера pip.

Установка и использование очень просты, что очень удобно для освоения Docker.

Настройка Dockerfile.

FROM python

RUN pip install cmake_converter

# Программа располагается здесь: /usr/local/bin/cmake-converter
WORKDIR /usr/local/bin

Для примера Dockerfile будет сохранён по следующему пути: ~/Documents/docker/cmake-converter/

Создание образа.

Перейти в каталог с Dockerfile. Пример:

cd ~/Documents/docker/cmake-converter/

Создать образ с именем my-cmake-converter:

sudo docker build -t my-cmake-converter .

Точка в конце указывает на то, что контекст сборки располагается в том же каталоге, где выполняется команда на сборку. В данном случае это место хранения Dockerfile: ~/Documents/docker/cmake-converter/

Запуск контейнера и использование cmake-converter.

Примечание: В данном примере sln-файл находится в ~/Documents/.

Запустить контейнер my-cmake-converter, смонтировать каталог ~/Documents/ в каталог /mnt/ внутри контейнера, выполнить программу cmake-converter и указать ей путь до sln-файла, который нужно преобразовать в CMakeLists.txt:

sudo docker run -v ~/Documents/:/mnt/ --rm my-cmake-converter cmake-converter -s /mnt/my-project.sln

Готово.

Использование на примере утилиты untrunc.

Официальный репозиторий: https://github.com/ponchio/untrunc

Утилита предназначена для исправления следующей проблемы: moov atom not found audio.mp4: Invalid data found when processing input.

То есть позволяет исправить битое видео в формате mov. К примеру, видео может побиться, если некорректно завершить процесс записи. Утилита позволяет подсунуть moov атом из нормального видео в битое, тем самым решая проблему.

Docker-файл: https://github.com/ponchio/untrunc/blob/master/Dockerfile

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

cd ~/Documents/docker/untrunc/

Загрузить файл:

wget https://github.com/ponchio/untrunc/blob/master/Dockerfile

В этой же сессии терминала выполнить команду на создание образа:

sudo docker build -t untrunc .

Создание контейнера и запуск утилиты:

sudo docker run -v ~/Video/:/mnt/ --rm untrunc /mnt/video_good.mp4 /mnt/video_bad.mp4

-v — указать каталог, который следует смонтировать в контейнер. Контейнер получит доступ ко всему содержимому каталога. В данном примере монтируется каталог ~/Video/ в каталог /mnt/ внутри контейнера.

—rm — удалить контейнер после завершения выполнения команды. В данном случае после завершения обработки видео.

untrunc — непосредственно сама утилита, находящаяся в контейнере. Сначала указывается видео-донор, в котором всё в порядке с moov атомом, а следом указывается видео с повреждённым.

Если всё правильно, то пойдёт процесс обработки, который зависит от объёма видео. Обработка видео 1 Гб занимает до 10 минут. Если moov атом не подходит, то будет указана ошибка.

Восстановление видео не гарантировано. Может восстановиться только звук, а видеоряд будет представлен набором графических артефактов.

Использование утилиты alien.

Утилита применяется для конвертации rpm-пакетов в deb-пакеты. Она требует довольно много зависимостей, которые не хочется тащить в систему. Поэтому сделаем собственный Docker-образ на базе Ubuntu.

Настройка Dockerfile.

FROM ubuntu

# настройка часовых поясов для tzdata
ENV TZ=Europe/Moscow
RUN ln -fs /usr/share/zoneinfo/$TZ /etc/localtime

RUN apt-get update

# установка с автоматическим подтверждением в диалогах
RUN apt-get install -y alien

# выполнить /usr/bin/alien при старте контейнера
ENTRYPOINT ["/usr/bin/alien"]

В данном примере Dockerfile будет сохранён в ~/Documents/docker/alien/.

Создание образа.

Перейти в каталог с Dockerfile:

cd ~/Documents/docker/alien/

Создать образ с именем alien:

sudo docker build -t alien .

Создание контейнера и запуск утилиты:

sudo docker run -v ~/Downloads/:/mnt/ --rm alien /mnt/пакет.rpm

В данном примере rpm-пакет находится в каталоге ~/Downloads/, который был смонтирован в каталог /mnt/ внутри контейнера.

deb-пакет будет создан с тем же именем, что и исходный rpm-пакет.

Это третья часть серии статей про 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»