Dockerfile in Windows
Il motore Docker include strumenti che automatizzano la creazione di immagini del contenitore. Sebbene sia possibile creare manualmente immagini del contenitore eseguendo il comando docker commit, l'adozione di un processo di creazione automatica delle immagini offre molti vantaggi, tra cui:
- Archiviazione di immagini del contenitore come codice.
- Ricreazione rapida e precisa delle immagini dei contenitori per scopi di manutenzione e aggiornamento.
- Integrazione continua tra immagini del contenitore e ciclo di sviluppo.
I componenti Docker che determinano questa automazione sono il Dockerfile e il comando docker build.
Il Dockerfile è un file di testo che contiene le istruzioni necessarie per creare una nuova immagine del contenitore. Queste istruzioni includono l'identificazione di un'immagine esistente da usare come base, i comandi da eseguire durante il processo di creazione dell'immagine e un comando che verrà eseguito quando vengono distribuite nuove istanze dell'immagine del contenitore.
Docker build è il comando del motore Docker che usa un Dockerfile e attiva il processo di creazione dell'immagine.
Questo argomento illustra come usare Dockerfile con i contenitori Windows, comprendere la sintassi di base e le istruzioni dockerfile più comuni.
Questo documento illustra il concetto di immagini contenitore e livelli di immagine del contenitore. Per altre informazioni sulle immagini e sul layering delle immagini, vedere immagini di base del container.
Per un'analisi completa dei Dockerfile, vedere il riferimento Dockerfile.
Sintassi di base
Nella sua forma più semplice, un Dockerfile può essere molto semplice. Nell'esempio seguente viene creata una nuova immagine, che include IIS e un sito "hello world". Questo esempio include commenti (indicati con un #), che spiegano ogni passaggio. Le sezioni successive di questo articolo illustrano in dettaglio le regole di sintassi dockerfile e le istruzioni di Dockerfile.
Nota
È necessario creare un Dockerfile senza estensione. A tale scopo in Windows, creare il file con l'editor preferito, quindi salvarlo con la notazione "Dockerfile" (incluse le virgolette).
# 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" ]
Per altri esempi di Dockerfile per Windows, vedere il repository Dockerfile per Windows.
Disposizioni
Le istruzioni di Dockerfile forniscono al motore Docker le istruzioni necessarie per creare un'immagine del contenitore. Queste istruzioni vengono eseguite una alla sola e in ordine. Gli esempi seguenti sono le istruzioni più usate in Dockerfiles. Per un elenco completo delle istruzioni di Dockerfile, vedere il riferimento Dockerfile.
DA
L'istruzione FROM imposta l'immagine contenitore che verrà usata durante il processo di creazione della nuova immagine. Ad esempio, quando si usa l'istruzione FROM mcr.microsoft.com/windows/servercore, l'immagine risultante è derivata da e ha una dipendenza dall'immagine del sistema operativo di base di Windows Server Core. Se l'immagine specificata non è presente nel sistema in cui viene eseguito il processo di compilazione Docker, il motore Docker tenterà di scaricare l'immagine da un registro di immagini pubblico o privato.
Il formato dell'istruzione FROM è simile al seguente:
FROM <image>
Ecco un esempio del comando FROM:
Per scaricare il core windows server della versione ltsc2019 dal Registro Contenitori Microsoft:To download the ltsc2019 version windows server core from the Microsoft Container Registry (MCR):
FROM mcr.microsoft.com/windows/servercore:ltsc2019
Per informazioni più dettagliate, vedere il riferimento FROM.
CORRERE
L'istruzione RUN specifica i comandi da eseguire e acquisiti nella nuova immagine del contenitore. Questi comandi possono includere elementi come l'installazione di software, la creazione di file e directory e la creazione della configurazione dell'ambiente.
L'istruzione RUN è simile alla seguente:
# exec form
RUN ["<executable>", "<param 1>", "<param 2>"]
# shell form
RUN <command>
La differenza tra il form exec e la shell consiste nel modo in cui viene eseguita l'istruzione RUN. Quando si usa il modulo exec, il programma specificato viene eseguito in modo esplicito.
Di seguito è riportato un esempio del formato exec:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN ["powershell", "New-Item", "c:/test"]
L'immagine risultante esegue il comando 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
Al contrario, l'esempio seguente esegue la stessa operazione nel formato shell:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell New-Item c:\test
L'immagine risultante ha un'istruzione di esecuzione di 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
Considerazioni sull'uso di RUN con Windows
In Windows, quando si usa l'istruzione RUN con il formato exec, le barre rovesciate devono essere precedute da un carattere di escape.
RUN ["powershell", "New-Item", "c:\\test"]
Quando il programma di destinazione è un programma di installazione di Windows, è necessario estrarre l'installazione tramite il flag /x:<directory> prima di avviare la procedura di installazione effettiva (invisibile all'utente). È anche necessario attendere che il comando venga chiuso prima di eseguire qualsiasi altra operazione. In caso contrario, il processo terminerà prematuramente senza installare nulla. Per informazioni dettagliate, consultare l'esempio seguente.
Esempi di utilizzo di RUN con Windows
Nell'esempio seguente di Dockerfile viene utilizzato DISM per installare IIS nell'immagine del contenitore.
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart
In questo esempio viene installato il pacchetto ridistribuibile di Visual Studio.
Start-Process e il parametro -Wait vengono usati per eseguire il programma di installazione. In questo modo l'installazione viene completata prima di passare all'istruzione successiva nel Dockerfile.
RUN powershell.exe -Command Start-Process c:\vcredist_x86.exe -ArgumentList '/quiet' -Wait
Per informazioni dettagliate sull'istruzione RUN, vedere il riferimento RUN.
COPIARE
L'istruzione COPY copia i file e le directory nel file system del contenitore. I file e le directory devono trovarsi in un percorso relativo al Dockerfile.
Il formato dell'istruzione COPY è simile al seguente:
COPY <source> <destination>
Se l'origine o la destinazione include spazi vuoti, racchiudere il percorso tra parentesi quadre e virgolette doppie, come illustrato nell'esempio seguente:
COPY ["<source>", "<destination>"]
Considerazioni sull'uso di COPY con Windows
In Windows, il formato di destinazione deve usare barre oblique. Ad esempio, queste sono istruzioni valide COPY:
COPY test1.txt /temp/
COPY test1.txt c:/temp/
Nel frattempo, il seguente formato con barre rovesciate non funzionerà.
COPY test1.txt c:\temp\
Esempi di utilizzo di COPY con Windows
L'esempio seguente aggiunge il contenuto della directory di origine a una directory denominata sqllite nell'immagine del contenitore:
COPY source /sqlite/
Nell'esempio seguente verranno aggiunti tutti i file che iniziano con config alla directory c:\temp dell'immagine del contenitore:
COPY config* c:/temp/
Per informazioni più dettagliate sull'istruzione COPY, vedere il riferimento COPY.
AGGIUNGERE
L'istruzione ADD è simile all'istruzione COPY, ma con ancora più funzionalità. Oltre a copiare file dall'host nell'immagine del contenitore, l'istruzione ADD può anche copiare file da un percorso remoto con una specifica url.
Il formato dell'istruzione ADD è simile al seguente:
ADD <source> <destination>
Se l'origine o la destinazione includono spazi vuoti, racchiudere il percorso tra parentesi quadre e virgolette doppie:
ADD ["<source>", "<destination>"]
Considerazioni sull'esecuzione di ADD con Windows
In Windows, il formato di destinazione deve usare barre in avanti. Ad esempio, queste sono istruzioni valide del tipo ADD:
ADD test1.txt /temp/
ADD test1.txt c:/temp/
Nel frattempo, il formato seguente con barre rovesciata non funzionerà:
ADD test1.txt c:\temp\
Inoltre, in Linux l'istruzione ADD espande i pacchetti compressi nella copia. Questa funzionalità non è disponibile in Windows.
Esempi di uso di ADD con Windows
L'esempio seguente aggiunge il contenuto della directory di origine a una directory denominata sqllite nell'immagine del contenitore:
ADD source /sqlite/
Nell'esempio seguente verranno aggiunti tutti i file che iniziano con "config" alla directory c:\temp dell'immagine del contenitore.
ADD config* c:/temp/
L'esempio seguente scaricherà Python per Windows nella directory c:\temp dell'immagine del contenitore.
ADD https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe /temp/python-3.5.1.exe
Per informazioni più dettagliate sull'istruzione ADD, vedere ADD reference.
WORKDIR
L'istruzione WORKDIR imposta una directory di lavoro per altre istruzioni dockerfile, ad esempio RUN, CMDe anche la directory di lavoro per l'esecuzione di istanze dell'immagine del contenitore.
Il formato dell'istruzione WORKDIR è simile al seguente:
WORKDIR <path to working directory>
Considerazioni sull'uso di WORKDIR con Windows
Su Windows, se la directory di lavoro include una barra rovesciata, deve essere fatta l'escape.
WORKDIR c:\\windows
esempi
WORKDIR c:\\Apache24\\bin
Per informazioni dettagliate sull'istruzione WORKDIR, vedere il riferimento WORKDIR.
CMD
L'istruzione CMD imposta il comando predefinito da eseguire durante la distribuzione di un'istanza dell'immagine del contenitore. Ad esempio, se il contenitore ospiterà un server Web NGINX, il CMD potrebbe includere istruzioni per avviare il server Web con un comando come nginx.exe. Se in un Dockerfile vengono specificate più istruzioni CMD, viene valutata solo l'ultima.
Il formato dell'istruzione CMD è simile al seguente:
# exec form
CMD ["<executable", "<param>"]
# shell form
CMD <command>
Considerazioni sull'uso di CMD con Windows
Su Windows, i percorsi di file specificati nell'istruzione CMD devono necessariamente utilizzare barre oblique o avere barre rovesciate codificate \\. Di seguito sono riportate le istruzioni valide CMD:
# exec form
CMD ["c:\\Apache24\\bin\\httpd.exe", "-w"]
# shell form
CMD c:\\Apache24\\bin\\httpd.exe -w
Tuttavia, il formato seguente senza le barre appropriate non funzionerà:
CMD c:\Apache24\bin\httpd.exe -w
Per informazioni più dettagliate sull'istruzione CMD, vedere il riferimento CMD.
Carattere di escape
In molti casi, un'istruzione Dockerfile dovrà estendersi su più righe. Per fare ciò, è possibile usare un carattere di escape. Il carattere di escape predefinito per Dockerfile è una barra rovesciata \. Tuttavia, poiché la barra rovesciata è anche un separatore di percorso di file in Windows, il suo utilizzo per dividere il codice su più righe può causare problemi. Per aggirare questo problema, è possibile usare una direttiva parser per modificare il carattere di escape predefinito. Per ulteriori informazioni sulle direttive del parser, vedere direttive del parser.
L'esempio seguente mostra una singola istruzione RUN che si estende su più righe usando il carattere di escape predefinito:
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
Per modificare il carattere di escape, inserire una direttiva di escape del parser nella prima riga del Dockerfile. Questo può essere visualizzato nell'esempio seguente.
Nota
È possibile usare solo due valori come caratteri di escape: \ e `.
# 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
Per ulteriori informazioni sulla direttiva escape del parser, vedere direttiva escape del parser.
PowerShell in Dockerfile
Cmdlet di PowerShell
I cmdlet di PowerShell possono essere eseguiti in un Dockerfile con l'operazione di RUN.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell -command Expand-Archive -Path c:\apache.zip -DestinationPath c:\
Chiamate REST
Il cmdlet Invoke-WebRequest di PowerShell può essere utile quando si raccolgono informazioni o file da un servizio Web. Ad esempio, se si compila un'immagine che include Python, è possibile impostare $ProgressPreference su SilentlyContinue per ottenere download più veloci, come illustrato nell'esempio seguente.
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
Nota
Invoke-WebRequest funziona anche in Nano Server.
Un'altra opzione per l'uso di PowerShell per scaricare i file durante il processo di creazione dell'immagine consiste nell'usare la libreria WebClient .NET. Ciò può aumentare le prestazioni di download. L'esempio seguente scarica il software Python usando la libreria 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
Nota
Nano Server attualmente non supporta WebClient.
Script di PowerShell
In alcuni casi, può essere utile copiare uno script nei contenitori usati durante il processo di creazione dell'immagine, quindi eseguire lo script dall'interno del contenitore.
Nota
Questo limiterà la memorizzazione nella cache dei livelli di immagine e ridurrà la leggibilità del Dockerfile.
Questo esempio copia uno script dal computer di compilazione nel contenitore usando l'istruzione ADD. Questo script viene quindi eseguito usando l'istruzione 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
Compilazione Docker
Dopo aver creato e salvato un Dockerfile su disco, è possibile eseguire docker build per creare la nuova immagine. Il comando docker build accetta diversi parametri facoltativi e un percorso al Dockerfile. Per la documentazione completa su Docker Build, incluso un elenco di tutte le opzioni di compilazione, vedere il riferimento alla compilazione .
Il formato del comando docker build è simile al seguente:
docker build [OPTIONS] PATH
Ad esempio, il comando seguente creerà un'immagine denominata "iis".
docker build -t iis .
Quando il processo di compilazione è stato avviato, l'output indicherà lo stato e restituirà eventuali errori generati.
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
Il risultato è una nuova immagine del contenitore, che in questo esempio è denominata "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