Dockerfile sur Windows

Le moteur Docker inclut des outils qui automatisent la création d’images conteneur. Bien que vous puissiez créer manuellement des images conteneur en exécutant la commande docker commit, l’adoption d’un processus de création d’images automatisé présente de nombreux avantages, notamment :

• Stockage d'images de conteneurs sous forme de code.
• Récréation rapide et précise des images de conteneur à des fins de maintenance et de mise à niveau.
• Intégration continue entre les images de conteneurs et le cycle de développement.

Les composants Docker qui pilotent cette automatisation sont le fichier Dockerfile et la commande docker build.

Le fichier Dockerfile est un fichier texte qui contient les instructions nécessaires pour créer une image conteneur. Ces instructions incluent l’identification d’une image existante à utiliser comme base, les commandes à exécuter pendant le processus de création d’image et une commande qui s’exécute lorsque de nouvelles instances de l’image conteneur sont déployées.

La build Docker est la commande du moteur Docker qui consomme un fichier Dockerfile et déclenche le processus de création d’image.

Cette rubrique vous montre comment utiliser des fichiers Dockerfile avec des conteneurs Windows, comprendre leur syntaxe de base et quelles sont les instructions Dockerfile les plus courantes.

Ce document traite du concept d’images conteneur et de couches d’images conteneur. Si vous souhaitez en savoir plus sur les images et la superposition d’images, consultez images de base de conteneurs.

Pour obtenir un aperçu détaillé des Dockerfiles, consultez la référence Dockerfile .

Syntaxe de base

Dans sa forme la plus simple, un fichier Dockerfile peut être très simple. L’exemple suivant crée une image, qui inclut IIS et un site « hello world ». Cet exemple inclut des commentaires (indiqués avec un #), qui expliquent chaque étape. Les sections suivantes de cet article expliquent plus en détail les règles de syntaxe Dockerfile et les instructions Dockerfile.

Note

Un fichier Dockerfile doit être créé sans extension. Pour ce faire dans Windows, créez le fichier avec votre éditeur de choix, puis enregistrez-le avec la notation « Dockerfile » (y compris les guillemets).

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

Pour obtenir d’autres exemples de fichiers Dockerfile pour Windows, consultez le Dockerfile pour le référentiel Windows.

Instructions

Les instructions dockerfile fournissent au moteur Docker les instructions dont il a besoin pour créer une image conteneur. Ces instructions sont effectuées un par un et dans l’ordre. Les exemples suivants sont les instructions les plus couramment utilisées dans les fichiers Dockerfiles. Pour obtenir la liste complète des instructions Dockerfile, consultez la référence Dockerfile.

DE

L’instruction FROM définit l’image conteneur qui sera utilisée pendant le nouveau processus de création d’image. Par exemple, lors de l’utilisation de l’instruction FROM mcr.microsoft.com/windows/servercore, l’image résultante est dérivée et a une dépendance sur l’image du système d’exploitation de base Windows Server Core. Si l’image spécifiée n’est pas présente sur le système où le processus de génération Docker est en cours d’exécution, le moteur Docker tente de télécharger l’image à partir d’un registre d’images publique ou privée.

Le format de l’instruction FROM ressemble à ceci :

FROM <image>

Voici un exemple de la commande FROM :

Pour télécharger l'édition Core de Windows Server version ltsc2019 à partir du Microsoft Container Registry (MCR) :

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

Pour plus d’informations, voir la référence DE.

EXÉCUTER

L’instruction RUN spécifie les commandes à exécuter et capturées dans la nouvelle image conteneur. Ces commandes peuvent inclure des éléments tels que l’installation de logiciels, la création de fichiers et de répertoires et la création d’une configuration d’environnement.

L’instruction RUN ressemble à ceci :

# exec form

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

# shell form

RUN <command>

La différence entre le formulaire exec et le formulaire shell est dans la façon dont l’instruction RUN est exécutée. Lorsque vous utilisez le formulaire exec, le programme spécifié est exécuté explicitement.

Voici un exemple de formulaire exec :

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

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

L’image résultante exécute la commande 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

En revanche, l’exemple suivant exécute la même opération sous forme d’interpréteur de commandes :

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

RUN powershell New-Item c:\test

L’image résultante a une instruction d’exécution 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

Considérations relatives à l’utilisation de RUN avec Windows

Sur Windows, lorsque vous utilisez l’instruction RUN au format exec, les barres obliques inverses doivent être échappées.

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

Lorsque le programme cible est un programme d’installation Windows, vous devez extraire l’installation via l’indicateur de /x:<directory> avant de pouvoir lancer la procédure d’installation réelle (silencieuse). Vous devez également attendre la sortie de la commande avant de faire autre chose. Sinon, le processus se termine prématurément sans installer quoi que ce soit. Pour plus d’informations, consultez l’exemple ci-dessous.

Exemples d’utilisation de RUN avec Windows

L’exemple dockerfile suivant utilise DISM pour installer IIS dans l’image conteneur :

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

Cet exemple installe le package redistribuable Visual Studio. Start-Process et le paramètre -Wait sont utilisés pour exécuter le programme d’installation. Cela garantit que l’installation se termine avant de passer à l’instruction suivante dans le fichier Dockerfile.

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

Pour plus d’informations sur l’instruction RUN, consultez la référence RUN.

COPIER

L’instruction COPY copie les fichiers et les répertoires dans le système de fichiers du conteneur. Les fichiers et répertoires doivent se trouver dans un chemin d’accès relatif au fichier Dockerfile.

Le format de l’instruction COPY se présente comme suit :

COPY <source> <destination>

Si la source ou la destination inclut des espaces blancs, placez le chemin entre crochets et guillemets doubles, comme illustré dans l’exemple suivant :

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

Considérations relatives à l’utilisation de COPY avec Windows

Sur Windows, le format de destination doit utiliser des barres obliques. Par exemple, il s’agit d’instructions COPY valides :

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

En attendant, le format suivant avec des barres obliques inverses ne fonctionnera pas :

COPY test1.txt c:\temp\

Exemples d’utilisation de COPY avec Windows

L’exemple suivant ajoute le contenu du répertoire source à un répertoire nommé sqllite dans l’image conteneur :

COPY source /sqlite/

L’exemple suivant ajoute tous les fichiers commençant par la configuration au répertoire c:\temp de l’image conteneur :

COPY config* c:/temp/

Pour plus d'informations détaillées sur l'instruction COPY, consultez la référence COPY .

AJOUTER

L’instruction ADD est semblable à l’instruction COPY, mais avec encore plus de fonctionnalités. Outre la copie de fichiers à partir de l’hôte dans l’image conteneur, l’instruction ADD peut également copier des fichiers à partir d’un emplacement distant avec une spécification d’URL.

Le format de l’instruction ADD se présente comme suit :

ADD <source> <destination>

Si la source ou la destination incluent des espaces blancs, placez le chemin entre crochets et guillemets doubles :

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

Considérations relatives à l’exécution de ADD avec Windows

Sur Windows, le format de destination doit utiliser des barres obliques. Par exemple, il s’agit d’instructions ADD valides :

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

En attendant, le format suivant avec des barres obliques inverses ne fonctionnera pas :

ADD test1.txt c:\temp\

En outre, sur Linux, l’instruction ADD développe les packages compressés lors de la copie. Cette fonctionnalité n’est pas disponible dans Windows.

Exemples d’utilisation de ADD avec Windows

L’exemple suivant ajoute le contenu du répertoire source à un répertoire nommé sqllite dans l’image conteneur :

ADD source /sqlite/

L’exemple suivant ajoute tous les fichiers commençant par « config » au répertoire c:\temp de l’image conteneur.

ADD config* c:/temp/

L’exemple suivant télécharge Python pour Windows dans le répertoire c:\temp de l’image conteneur.

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

Pour plus d’informations sur l’instruction ADD, consultez la référence AJOUTER.

RÉPERTOIRE DE TRAVAIL

L’instruction WORKDIR définit un répertoire de travail pour d’autres instructions Dockerfile, telles que RUN, CMD, et également le répertoire de travail pour l’exécution d’instances de l’image conteneur.

Le format de l’instruction WORKDIR se présente comme suit :

WORKDIR <path to working directory>

Considérations relatives à l’utilisation de WORKDIR avec Windows

Sur Windows, si le répertoire de travail inclut une barre oblique inverse, il doit être échappé.

WORKDIR c:\\windows

Exemples

WORKDIR c:\\Apache24\\bin

Pour plus d’informations sur l’instruction WORKDIR, consultez la référence WORKDIR.

CMD

L’instruction CMD définit la commande par défaut à exécuter lors du déploiement d’une instance de l’image conteneur. Par exemple, si le conteneur héberge un serveur web NGINX, le CMD peut inclure des instructions pour démarrer le serveur web avec une commande telle que nginx.exe. Si plusieurs instructions CMD sont spécifiées dans un fichier Dockerfile, seule la dernière est évaluée.

Le format de l’instruction CMD se présente comme suit :

# exec form

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

# shell form

CMD <command>

Considérations relatives à l’utilisation de CMD avec Windows

Sur Windows, les chemins d’accès aux fichiers spécifiés dans l’instruction CMD doivent utiliser des barres obliques avant ou avoir des barres obliques inverses en échappement \\. Voici des instructions CMD valides :

# exec form

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

# shell form

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

Toutefois, le format suivant sans les barres obliques appropriées ne fonctionnera pas :

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

Pour plus d’informations sur l’instruction CMD, consultez la référence CMD .

Caractère d’échappement

Dans de nombreux cas, une instruction Dockerfile doit s’étendre sur plusieurs lignes. Pour ce faire, vous pouvez utiliser un caractère d’échappement. Le caractère d’échappement dockerfile par défaut est une barre oblique inverse \. Toutefois, étant donné que la barre oblique inverse est également un séparateur de chemin d’accès de fichier dans Windows, l’utilisation de celle-ci pour étendre plusieurs lignes peut entraîner des problèmes. Pour contourner ce problème, vous pouvez utiliser une directive d’analyseur pour modifier le caractère d’échappement par défaut. Pour plus d’informations sur les directives d’analyseur, consultez directives d’analyseur.

L’exemple suivant montre une seule instruction RUN qui s’étend sur plusieurs lignes à l’aide du caractère d’échappement par défaut :

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

Pour modifier le caractère d’échappement, placez une directive d’analyseur d’échappement sur la toute première ligne du fichier Dockerfile. Cet exemple est visible dans l’exemple suivant.

Note

Seules deux valeurs peuvent être utilisées comme caractères d’échappement : \ et `.

# 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

Pour plus d'informations sur les directives d'analyse d'échappement, consultez Directives d'analyse d'échappement.

PowerShell dans Dockerfile

Applets de commande PowerShell

Les applets de commande PowerShell peuvent être exécutées dans un fichier Dockerfile avec l’opération de RUN.

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

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

Appels REST

L’applet de commande Invoke-WebRequest powerShell peut être utile lors de la collecte d’informations ou de fichiers à partir d’un service web. Par exemple, si vous générez une image incluant Python, vous pouvez définir $ProgressPreference sur SilentlyContinue pour obtenir des téléchargements plus rapides, comme illustré dans l’exemple suivant.

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

Note

Invoke-WebRequest fonctionne également dans Nano Server.

Une autre option permettant d’utiliser PowerShell pour télécharger des fichiers pendant le processus de création d’image consiste à utiliser la bibliothèque .NET WebClient. Cela peut augmenter les performances de téléchargement. L’exemple suivant télécharge le logiciel Python à l’aide de la bibliothèque 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

Note

Nano Server ne prend actuellement pas en charge WebClient.

Scripts PowerShell

Dans certains cas, il peut être utile de copier un script dans les conteneurs que vous utilisez pendant le processus de création d’image, puis d’exécuter le script à partir du conteneur.

Note

Cela limite la mise en cache des couches d’images et diminue la lisibilité du fichier Dockerfile.

Cet exemple copie un script à partir de la machine de build dans le conteneur à l’aide de l’instruction ADD. Ce script est ensuite exécuté à l’aide de l’instruction 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

Version Docker

Une fois qu’un fichier Dockerfile a été créé et enregistré sur le disque, vous pouvez exécuter docker build pour créer la nouvelle image. La commande docker build accepte plusieurs paramètres facultatifs et un chemin d’accès au fichier Dockerfile. Pour obtenir une documentation complète sur Docker Build, y compris une liste de toutes les options de build, consultez la référence de build.

Le format de la commande docker build ressemble à ceci :

docker build [OPTIONS] PATH

Par exemple, la commande suivante crée une image nommée « iis ».

docker build -t iis .

Lorsque le processus de génération a été lancé, la sortie indique l’état et retourne les erreurs renvoyées.

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

Le résultat est une nouvelle image conteneur, qui, dans cet exemple, est nommée « 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

Lectures et références supplémentaires

• Optimiser les Dockerfiles et la version Docker pour Windows
• référence Dockerfile