Dockerfile no Windows

O mecanismo do Docker inclui ferramentas para automatizar a criação de imagens de contêiner. Embora as imagens de contêiner possam ser criadas manualmente usando o comando docker commit, adotar um processo de criação de imagem automatizado fornece muitos benefícios, incluindo:

  • Armazenar imagens de contêiner como código.
  • Recriação rápida e precisa das imagens de contêiner para fins de manutenção e atualização.
  • Integração contínua entre imagens de contêiner e o ciclo de desenvolvimento.

Os componentes do Docker que orientam essa automação são Dockerfile e o comando docker build.

  • Dockerfile – um arquivo de texto que contém as instruções necessárias para criar uma nova imagem de contêiner. Essas instruções incluem a identificação de uma imagem existente a ser usada como uma base, comandos a serem executados durante o processo de criação da imagem e um comando que será executado quando novas instâncias da imagem de contêiner forem implantadas.
  • Docker build – o comando do mecanismo do Docker que consome um Dockerfile e aciona o processo de criação de imagem.

Este documento apresentará o uso de um Dockerfile com contêineres do Windows, discutirá a sintaxe e detalhará as instruções do Dockerfile normalmente usadas.

Ao longo deste documento, o conceito de imagens de contêineres e camadas de imagem de contêiner será discutido. Para obter mais informações sobre imagens e a disposição das imagens em camadas, consulte o guia de início rápido para imagens.

Para uma visão completa dos Dockerfiles, consulte Dockerfile reference (Referência do Dockerfile) em docker.com.

Introdução ao Dockerfile

Sintaxe básica

Em sua forma mais básica, um Dockerfile pode ser muito simples. O exemplo a seguir cria uma nova imagem, que inclui o IIS e um site 'hello world'. Este exemplo inclui comentários (indicados com um #), que explicam cada etapa. As seções seguintes deste artigo fornecem mais detalhes sobre as regras de sintaxe e as instruções do Dockerfile.

Observe que o Dockerfile deve ser criado sem extensão. Para fazer isso no Windows, basta criar o arquivo com o editor de sua preferência e salvá-lo usando a notação "Dockerfile", incluindo as aspas.

# Sample Dockerfile

# Indicates that the windowsservercore image will be used as the base image.
FROM microsoft/windowsservercore

# Metadata indicating an image maintainer.
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" ]

Para obter exemplos adicionais de Dockerfiles para Windows, consulte o Repositório do Dockerfile para Windows.

Instruções

As instruções de Dockerfile fornecem ao mecanismo do Docker as etapas necessárias para criar uma imagem de contêiner. Essas instruções são executadas em ordem e uma por vez. Aqui estão os detalhes de algumas instruções básicas do Dockerfile. Para obter uma lista completa de instruções do Dockerfile, consulte Dockerfile Reference (Referência do Dockerfile) em Docker.com.

FROM

A instrução FROM define a imagem de contêiner que será usada durante o processo de criação de nova imagem. Por exemplo, ao usar a instrução FROM microsoft/windowsservercore, a imagem resultante é derivada da (e tem uma dependência na) imagem do sistema operacional base Windows Server Core. Se a imagem especificada não estiver presente no sistema em que o processo de build do Docker está sendo executado, o mecanismo do Docker tentará baixar a imagem de um registro da imagem pública ou privada.

Formato

A instrução FROM usa o formato de:

FROM <image>

Exemplo

FROM microsoft/windowsservercore

Para obter informações detalhadas sobre a instrução FROM, consulte a referência de FROM em Docker.com.

RUN

A instrução RUN especifica os comandos a serem executados e capturados na nova imagem de contêiner. Esses comandos podem incluir itens como a instalação de software, a criação de arquivos e diretórios e a criação da configuração do ambiente.

Formato

A instrução RUN usa o formato de:

# exec form

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

# shell form

RUN <command>

A diferença entre o formato exec e o shell está em como a instrução RUN é executada. Ao usar o formato exec, o programa especificado é executado explicitamente.

O exemplo a seguir utiliza o formato exec.

FROM microsoft/windowsservercore

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

Examinando a imagem resultante, o comando que foi executado é 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

Para contraste, o exemplo a seguir executa a mesma operação, no entanto, usando o formato de shell.

FROM microsoft/windowsservercore

RUN powershell New-Item c:\test

O que resulta em uma instrução de execução de 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

Considerações sobre o Windows

No Windows, ao usar a instrução RUN com o formato de exec., as barras invertidas devem ser seguidas por caracteres de escape.

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

Quando o programa de destino for um Windows Installer, é necessário realizar uma etapa extra antes de iniciar o real procedimento de instalação (silencioso): extração da configuração por meio do sinalizador /x:<directory>. Além disso, o comando deve ser aguardado para sair. Caso contrário, o processo será finalizado prematuramente, sem instalar nada. Para obter detalhes, consulte o exemplo a seguir.

Exemplos

Este exemplo usa o DISM para instalar o IIS na imagem de contêiner.

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

Este exemplo instala o pacote redistribuível do Visual Studio. Observe aqui que o Start-Process e o parâmetro -Wait são usados para executar o instalador. Isso assegurará que a instalação tenha sido concluída antes de passar para a próxima etapa no Dockerfile.

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

Para obter informações detalhadas sobre a instrução RUN, consulte a referência de RUN em Docker.com.

COPIAR

A instrução COPY copia arquivos e diretórios para o sistema de arquivos do contêiner. Os arquivos e diretórios precisam estar em um caminho relativo ao Dockerfile.

Formato

A instrução COPY usa o formato de:

COPY <source> <destination>

Se origem ou destino incluir espaços em branco, coloque o caminho entre colchetes e aspas duplas.

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

Considerações sobre o Windows

No Windows, o formato de destino deve usar barras "/". Por exemplo, essas são instruções válidas de COPY.

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

No entanto, a seguinte não funcionará.

COPY test1.txt c:\temp\

Exemplos

Este exemplo adiciona o conteúdo do diretório de origem a um diretório chamado sqllite na imagem de contêiner.

COPY source /sqlite/

Este exemplo adicionará todos os arquivos que começam com config ao diretório c:\temp da imagem de contêiner.

COPY config* c:/temp/

Para obter informações detalhadas sobre a instrução COPY, consulte a referência do COPY em Docker.com.

ADICIONAR

A instrução ADD é muito parecida com a instrução COPY, porém ela inclui funcionalidades adicionais. Além de copiar arquivos do host para a imagem de contêiner, a instrução ADD também pode copiar arquivos de um local remoto com uma especificação de URL.

Formato

A instrução ADD usa o formato de:

ADD <source> <destination>

Se origem ou destino incluir espaços em branco, coloque o caminho entre colchetes e aspas duplas.

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

Considerações sobre o Windows

No Windows, o formato de destino deve usar barras "/". Por exemplo, essas são instruções válidas de ADD.

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

No entanto, a seguinte não funcionará.

ADD test1.txt c:\temp\

Além disso, no Linux a instrução ADD expandirá pacotes compactados na cópia. Essa funcionalidade não está disponível no Windows.

Exemplos

Este exemplo adiciona o conteúdo do diretório de origem a um diretório chamado sqllite na imagem de contêiner.

ADD source /sqlite/

Este exemplo adicionará todos os arquivos que começam com config ao diretório c:\temp da imagem de contêiner.

ADD config* c:/temp/

Este exemplo baixará o Python para Windows para o diretório c:\temp da imagem de contêiner.

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

Para obter informações detalhadas sobre a instrução ADD, consulte a referência de ADD em Docker.com.

WORKDIR

A instrução WORKDIR define um diretório de trabalho para outras instruções Dockerfile, como RUN, CMD e também o diretório de trabalho para executar instâncias da imagem do contêiner.

Formato

A instrução WORKDIR usa o formato de:

WORKDIR <path to working directory>

Considerações sobre o Windows

No Windows, se o diretório de trabalho incluir uma barra invertida, ela deverá ser seguida por caracteres de escape.

WORKDIR c:\\windows

Exemplos

WORKDIR c:\\Apache24\\bin

Para obter informações detalhadas sobre a instrução WORKDIR, consulte a referência de WORKDIR em Docker.com.

CMD

A instrução CMD, define o comando padrão a ser executado durante a implantação de uma instância da imagem do contêiner. Por exemplo, se o contêiner for hospedar um servidor Web NGINX, CMD poderá incluir instruções para iniciar o servidor Web, como nginx.exe. Se várias instruções CMD forem especificadas em um Dockerfile, somente a última será avaliada.

Formato

A instrução CMD usa o formato de:

# exec form

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

# shell form

CMD <command>

Considerações sobre o Windows

No Windows, caminhos de arquivo especificados na instrução CMD devem usar barras "/" ou ter barras invertidas de escape \\. Por exemplo, essas são instruções válidas de CMD.

# exec form

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

# shell form

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

No entanto, a seguinte não funcionará.

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

Para obter informações detalhadas sobre a instrução CMD, consulte a Referência de CMD em Docker.com.

Caractere de escape

Em muitos casos, uma instrução do Dockerfile precisará abranger várias linhas; faça isso com um caractere de escape. O caractere de escape padrão do Dockerfile é uma barra invertida \. Como a barra invertida é também um separador de caminho de arquivo no Windows, isso poderá causar problemas. Para alterar o caractere de escape padrão, pode-se usar uma diretiva de analisador. Para obter mais informações sobre diretivas do Analisador, veja Parser Directives (Diretivas do Analisador) em Docker.com.

O exemplo a seguir mostra uma única instrução RUN que abrange várias linhas usando o caractere de escape padrão.

FROM microsoft/windowsservercore

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

Para modificar o caractere de escape, coloque uma diretiva do analisador de escape logo na primeira linha do Dockerfile. Veja como fazer isso no exemplo abaixo.

Observe que apenas dois valores podem ser usados como caracteres de escape, \ e ` .

# escape=`

FROM microsoft/windowsservercore

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

Para obter mais informações sobre a diretiva do analisador de escape, veja Escape Parser Directive (Diretiva do Analisador de escape) em Docker.com.

PowerShell no Dockerfile

Comandos do PowerShell

Os comandos do PowerShell podem ser executados em um Dockerfile usando a operação RUN.

FROM microsoft/windowsservercore

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

Chamadas REST

O PowerShell e o comando Invoke-WebRequest podem ser úteis ao coletar informações ou arquivos de um serviço Web. Por exemplo, se estiver criando uma imagem que inclui o Python, o exemplo a seguir poderá ser usado. Considere definir $ProgressPreference como SilentlyContinue para obter downloads mais rápidos.

FROM microsoft/windowsservercore

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 também funciona no Nano Server

Outra opção para usar o PowerShell para baixar arquivos durante o processo de criação de imagem é usar a biblioteca .Net WebClient. Isso pode aumentar o desempenho do download. O exemplo a seguir baixa o software Python usando a biblioteca WebClient.

FROM microsoft/windowsservercore

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

WebClient não tem suporte no Nano Server no momento

Scripts PowerShell

Em alguns casos, pode ser útil copiar um script para os contêineres que estão sendo usados durante o processo de criação da imagem e executar de dentro do contêiner. Observação: isso limitará qualquer cache de camada de imagem e diminuirá a legibilidade do Dockerfile.

Este exemplo copia um script do computador de build para o contêiner usando a instrução ADD. Esse script é executado usando a instrução RUN.

FROM microsoft/windowsservercore
ADD script.ps1 /windows/temp/script.ps1
RUN powershell.exe -executionpolicy bypass c:\windows\temp\script.ps1

Build do Docker

Depois de um Dockerfile ter sido criado e salvo em disco, docker build pode ser executado para criar a nova imagem. O comando docker build leva vários parâmetros opcionais e um caminho para o Dockerfile. Para obter a documentação completa sobre o comando Docker Build, incluindo uma lista de todas as opções de build, consulte Referência de build em Docker.com.

Docker build [OPTIONS] PATH

Por exemplo, o comando a seguir criará uma imagem chamada 'iis'.

docker build -t iis .

Quando o processo de build tiver sido iniciado, a saída indicará o status e retornará quaisquer erros gerados.

C:\> docker build -t iis .

Sending build context to Docker daemon 2.048 kB
Step 1 : FROM micrsoft/windowsservercore
 ---> 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

O resultado é uma nova imagem de contêiner, nesse exemplo, chamada '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

Referências e leituras adicionais

Otimizar Dockerfiles e build do Docker para Windows

Dockerfile Reference (Referência do Dockerfile) em Docker.com