Dockerfile в Windows

Подсистема Docker содержит средства, автоматизирующие создание образов контейнеров. Хотя образы контейнеров можно создавать вручную с помощью команды docker commit, внедрение процесса автоматического создания образа предоставляет множество преимуществ, в том числе:

  • Сохранение образов контейнеров в виде кода.
  • Быстрое и точное воссоздание образов контейнеров для обслуживания и обновления.
  • Непрерывная интеграция между образами контейнеров и циклом разработки.

За такую автоматизацию отвечают два компонента Docker — файл Dockerfile и команда docker build.

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

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

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

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

Полный обзор файлов Dockerfile см. в справке по Dockerfile на странице .

Базовый синтаксис

В исходной форме файл Dockerfile может быть очень простым. Следующий пример создает образ, включающий IIS и сайт "hello world". Этот пример включает комментарии (обозначенные с помощью #), поясняющие каждый шаг. В последующих разделах этой статьи более подробно рассматриваются правила синтаксиса Dockerfile и инструкции Dockerfile.

Примечание

Файл Dockerfile необходимо создавать без расширения. Чтобы сделать это в Windows, создайте файл с помощью удобного для вас редактора, а затем сохраните его, используя нотацию "Dockerfile" (вместе с кавычками).

# Sample Dockerfile

# Indicates that the windowsservercore image will be used as the base image.
FROM mcr.microsoft.com/windows/servercore:ltsc2019

# Metadata indicating an image maintainer.
LABEL maintainer="jshelton@contoso.com"

# Uses dism.exe to install the IIS role.
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart

# Creates an HTML file and adds content to this file.
RUN echo "Hello World - Dockerfile" > c:\inetpub\wwwroot\index.html

# Sets a command or process that will run each time a container is run from the new image.
CMD [ "cmd" ]

Дополнительные примеры файлов Dockerfile для Windows см. в репозитории файлов Dockerfile для Windows.

Инструкция

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

FROM

Инструкция FROM задает образ контейнера, который будет применяться при создании нового образа. Например, при использовании инструкции FROM mcr.microsoft.com/windows/servercore полученный образ является производным и зависимым от базового образа ОС Windows Server Core. Если указанный образ отсутствует в системе, где выполняется процесс сборки Docker, подсистема Docker попытается скачать его из общедоступного или частного реестра образов.

Формат инструкции FROM выглядит следующим образом:

FROM <image>

Ниже приведен пример команды FROM.

Чтобы загрузить Windows Server Core версии ltsc2019 из Реестра контейнеров (Майкрософт):

FROM mcr.microsoft.com/windows/servercore:ltsc2019

Дополнительные сведения см. в справочнике по инструкции FROM.

RUN

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

Инструкция RUN выглядит следующим образом:

# exec form

RUN ["<executable>", "<param 1>", "<param 2>"]

# shell form

RUN <command>

Различие между формой исполняемого файла (exec form) и формой оболочки (shell form) заключается в способе выполнения инструкции RUN. При использовании формы исполняемого файла указанная программа запускается явным образом.

Ниже приведен пример формы исполняемого файла.

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN ["powershell", "New-Item", "c:/test"]

Полученный образ выполняет команду powershell New-Item c:/test:

docker history doc-exe-method

IMAGE               CREATED             CREATED BY                    SIZE                COMMENT
b3452b13e472        2 minutes ago       powershell New-Item c:/test   30.76 MB

В отличие от предыдущего примера здесь та же операция выполняется с использованием формы оболочки:

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell New-Item c:\test

Полученный образ содержит инструкцию RUN cmd /S /C powershell New-Item c:\test.

docker history doc-shell-method

IMAGE               CREATED             CREATED BY                              SIZE                COMMENT
062a543374fc        19 seconds ago      cmd /S /C powershell New-Item c:\test   30.76 MB

Рекомендации по использованию инструкции RUN с Windows

В Windows при использовании инструкции RUN в формате исполняемого файла необходимо экранировать инструкции символы обратной косой черты.

RUN ["powershell", "New-Item", "c:\\test"]

Если целевая программа является установщиком Windows, чтобы запустить фактическую процедуру (автоматической) установки, необходимо извлечь программу установки, используя флаг /x:<directory>. Прежде чем выполнять какие-либо другие действия, необходимо дождаться завершения выполнения команды. В противном случае процесс будет завершен преждевременно и без установки. Дополнительные сведения см. в приведенном ниже примере.

Примеры использования инструкции RUN с Windows

В следующем примере для установки служб IIS в образе контейнера используется система DISM.

RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart

Этот пример устанавливает распространяемый пакет Visual Studio. Start-Process и параметр -Wait используются для запуска программы установки. Это гарантирует, что установка будет завершена до перехода к следующей инструкции в Dockerfile.

RUN powershell.exe -Command Start-Process c:\vcredist_x86.exe -ArgumentList '/quiet' -Wait

Подробные сведения об инструкции RUN см. в справочнике по RUN на странице .

COPY

Инструкция COPY копирует файлы и каталоги в файловую систему контейнера. Эти файлы и каталоги должны иметь путь, являющийся относительным для Dockerfile.

Формат инструкции COPY выглядит следующим образом:

COPY <source> <destination>

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

COPY ["<source>", "<destination>"]

Рекомендации по использованию инструкции COPY с Windows

В Windows для путей назначения необходимо использовать символы косой черты. Например, здесь показаны допустимые инструкции COPY.

COPY test1.txt /temp/
COPY test1.txt c:/temp/

При этом следующий формат с обратными косыми чертами работать не будет:

COPY test1.txt c:\temp\

Примеры использования инструкции COPY с Windows

В следующем примере содержимое исходного каталога добавляется в каталог с именем sqllite в образе контейнера.

COPY source /sqlite/

В следующем примере все файлы, начинающиеся с config, добавляют в каталог c:\temp образа контейнера.

COPY config* c:/temp/

Дополнительные сведения об инструкции COPY см. в справочнике по инструкции COPY.

ДОБАВИТЬ

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

Формат инструкции ADD выглядит следующим образом:

ADD <source> <destination>

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

ADD ["<source>", "<destination>"]

Рекомендации по выполнению инструкции ADD с Windows

В Windows для путей назначения необходимо использовать символы косой черты. Например, здесь показаны допустимые инструкции ADD.

ADD test1.txt /temp/
ADD test1.txt c:/temp/

При этом следующий формат с обратными косыми чертами работать не будет:

ADD test1.txt c:\temp\

Кроме того, в системе Linux во время копирования инструкция ADD распаковывает сжатые пакеты. В Windows эта функция недоступна.

Примеры использования инструкции ADD с Windows

В следующем примере содержимое исходного каталога добавляется в каталог с именем sqllite в образе контейнера.

ADD source /sqlite/

В следующем примере все файлы, начинающиеся с "config", добавляют в каталог c:\temp образа контейнера.

ADD config* c:/temp/

В этом примере Python для Windows скачивается в каталог c:\temp образа контейнера.

ADD https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe /temp/python-3.5.1.exe

Дополнительные сведения об инструкции ADD см. в справочнике по инструкции ADD.

WORKDIR

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

Формат инструкции WORKDIR выглядит следующим образом:

WORKDIR <path to working directory>

Рекомендации по использованию инструкции WORKDIR с Windows

Если в Windows рабочий каталог содержит обратную косую черту, ее следует экранировать.

WORKDIR c:\\windows

Примеры

WORKDIR c:\\Apache24\\bin

Подробные сведения об инструкции WORKDIR см. в справочнике по WORKDIR.

CMD

Инструкция CMD задает команду по умолчанию, выполняемую при развертывании экземпляра образа контейнера. Например, если в контейнере будет размещен веб-сервер NGINX, CMD может включать инструкции для запуска этого веб-сервера, например с помощью команды nginx.exe. Если в файле Dockerfile указано несколько инструкций CMD, вычисляется только последняя из них.

Формат инструкции CMD выглядит следующим образом:

# exec form

CMD ["<executable", "<param>"]

# shell form

CMD <command>

Рекомендации по использованию инструкции CMD с Windows

В Windows для путей к файлам, указанным в инструкции CMD, следует использовать символы косой черты или экранировать символы обратной косой черты \\. Допустимы следующие инструкции CMD:

# exec form

CMD ["c:\\Apache24\\bin\\httpd.exe", "-w"]

# shell form

CMD c:\\Apache24\\bin\\httpd.exe -w

Однако следующий формат без соответствующих косых черт работать не будет:

CMD c:\Apache24\bin\httpd.exe -w

Дополнительные сведения об инструкции CMD см. в справочнике по инструкции CMD.

Escape-символ

Во многих случаях инструкция Dockerfile должна занимать несколько строк. Для этого можно использовать escape-символ. Escape-символ Dockerfile по умолчанию — обратная косая черта (\). Однако, поскольку обратная косая черта также является разделителем пути к файлу в Windows, использование его для разделения нескольких строк может вызвать проблемы. Чтобы их избежать, можно изменить escape-символ по умолчанию с помощью директивы анализатора. Дополнительные сведения о директивах анализатора см. в этом разделе.

В следующем примере показана инструкция RUN, которая занимает несколько строк и использует escape-символ по умолчанию.

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell.exe -Command \
    $ErrorActionPreference = 'Stop'; \
    wget https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; \
    Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
    Remove-Item c:\python-3.5.1.exe -Force

Чтобы изменить escape-символ, поместите директиву Parser для escape-символа на первую строку Dockerfile. Это показано в следующем примере.

Примечание

В качестве escape-символов можно использовать только символы: \ и `.

# escape=`

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell.exe -Command `
    $ErrorActionPreference = 'Stop'; `
    wget https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; `
    Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; `
    Remove-Item c:\python-3.5.1.exe -Force

Дополнительные сведения о директиве анализатора для escape-символа см. в этом разделе.

PowerShell в Dockerfile

Командлеты PowerShell

Командлеты PowerShell можно выполнять в Dockerfile при помощи операции RUN.

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell -command Expand-Archive -Path c:\apache.zip -DestinationPath c:\

Вызовы REST

При сборе данных или файлов из веб-службы удобно использовать командлет PowerShell Invoke-WebRequest. Например, при сборке образа, включающего Python, можно задать для $ProgressPreference значение SilentlyContinue, чтобы ускорить загрузку, как показано в следующем примере.

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell.exe -Command \
  $ErrorActionPreference = 'Stop'; \
  $ProgressPreference = 'SilentlyContinue'; \
  Invoke-WebRequest https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; \
  Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
  Remove-Item c:\python-3.5.1.exe -Force

Примечание

Invoke-WebRequest также работает на сервере Nano Server.

Кроме того, с помощью PowerShell можно скачивать файлы во время создания образа, используя библиотеку .NET WebClient. Это может повысить производительность скачивания. Следующий пример скачивает программное обеспечение Python, используя библиотеку WebClient.

FROM mcr.microsoft.com/windows/servercore:ltsc2019

RUN powershell.exe -Command \
  $ErrorActionPreference = 'Stop'; \
  (New-Object System.Net.WebClient).DownloadFile('https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe','c:\python-3.5.1.exe') ; \
  Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
  Remove-Item c:\python-3.5.1.exe -Force

Примечание

Сейчас Nano Server не поддерживает WebClient.

Сценарии PowerShell

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

Примечание

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

Этот пример копирует сценарий с компьютера сборки в контейнер с помощью инструкции ADD. Затем этот сценарий выполняется с помощью инструкции RUN.

FROM mcr.microsoft.com/windows/servercore:ltsc2019
ADD script.ps1 /windows/temp/script.ps1
RUN powershell.exe -executionpolicy bypass c:\windows\temp\script.ps1

Команда Docker build

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

Формат команды docker build выглядит следующим образом:

docker build [OPTIONS] PATH

Например, следующая команда создает образ с именем "iis".

docker build -t iis .

При инициации процесса сборки в выходных данных указывается состояние и выводятся все возникающие ошибки.

C:\> docker build -t iis .

Sending build context to Docker daemon 2.048 kB
Step 1 : FROM mcr.microsoft.com/windows/servercore:ltsc2019
 ---> 6801d964fda5

Step 2 : RUN dism /online /enable-feature /all /featurename:iis-webserver /NoRestart
 ---> Running in ae8759fb47db

Deployment Image Servicing and Management tool
Version: 10.0.10586.0

Image Version: 10.0.10586.0

Enabling feature(s)
The operation completed successfully.

 ---> 4cd675d35444
Removing intermediate container ae8759fb47db

Step 3 : RUN echo "Hello World - Dockerfile" > c:\inetpub\wwwroot\index.html
 ---> Running in 9a26b8bcaa3a
 ---> e2aafdfbe392
Removing intermediate container 9a26b8bcaa3a

Successfully built e2aafdfbe392

В результате создается новый образ контейнера, который в этом примере носит имя "iis".

docker images

REPOSITORY          TAG                 IMAGE ID            CREATED              VIRTUAL SIZE
iis                 latest              e2aafdfbe392        About a minute ago   207.8 MB
windowsservercore   latest              6801d964fda5        4 months ago         0 B

Дополнительные материалы и справочники