Dockerfile in Windows
Il motore Docker include strumenti che automatizzano la creazione di immagini del contenitore. Anche se è possibile creare immagini contenitore manualmente eseguendo il comando, l'adozione docker commit di un processo di creazione automatica delle immagini offre molti vantaggi, tra cui:
- Archiviazione di immagini contenitore come codice.
- Ricreazione rapida e precisa delle immagini contenitore ai fini della manutenzione e dell'aggiornamento.
- Integrazione continua tra le immagini contenitore e il ciclo di sviluppo.
I componenti di Docker che gestiscono l'automazione sono Dockerfile e il comando docker build.
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 delle immagini e un comando che verrà eseguito quando si distribuiscono nuove istanze dell'immagine contenitore.
La compilazione Docker è il comando del motore Docker che usa un Dockerfile e attiva il processo di creazione dell'immagine.
Questo argomento illustra come usare Dockerfile con contenitori Windows, comprendere la sintassi di base e quali sono 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 contenitore.
Per un'occhiata completa a Dockerfiles, vedere il riferimento a Dockerfile.
Sintassi di base
Il formato di base di un Dockerfile può essere molto semplice. Nell'esempio seguente si crea una nuova immagine, inclusi IIS e un sito "hello world". Questo esempio include commenti (indicati con un #), che descrivono ogni passaggio. Le sezioni successive di questo articolo illustreranno in dettaglio le regole di sintassi e le istruzioni Dockerfile.
Nota
Un Dockerfile deve essere creato senza estensione. A tale scopo in Windows, creare il file con l'editor scelto, 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 Dockerfiles per Windows, vedere il repository Dockerfile for Windows.
Istruzioni
Le istruzioni di Dockerfile forniscono al motore Docker le istruzioni necessarie per creare un'immagine del contenitore. Queste istruzioni vengono eseguite uno per uno e in ordine. Gli esempi seguenti sono le istruzioni più comunemente usate in Dockerfiles. Per un elenco completo delle istruzioni di Dockerfile, vedere il riferimento a Dockerfile.
FROM
L'istruzione FROM imposta l'immagine contenitore che verrà usata durante il processo di creazione di una nuova immagine. Ad esempio, quando si usa l'istruzione FROM mcr.microsoft.com/windows/servercore, l'immagine risultante deriva e presenta 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:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
Per informazioni più dettagliate, vedere il riferimento FROM.
ESEGUI
L'istruzione RUN specifica i comandi da eseguire e acquisire nella nuova immagine contenitore. Questi comandi possono includere elementi, tra cui 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 modulo exec e shell è il modo in cui viene eseguita l'istruzione RUN . Quando si usa il formato exec, il programma specificato viene eseguito in modo esplicito.
Ecco un esempio del modulo exec:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN ["powershell", "New-Item", "c:/test"]
L'immagine risultante esegue il powershell New-Item c:/test comando:
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, nell'esempio seguente viene eseguita 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
Quando si usa l'istruzione RUN con il formato exec in Windows, devono essere usati caratteri di escape per le barre rovesciate.
RUN ["powershell", "New-Item", "c:\\test"]
Quando il programma di destinazione è un programma di installazione di Windows, è necessario estrarre il programma di installazione tramite il /x:<directory> flag prima di poter avviare la procedura di installazione effettiva (invisibile all'utente). È anche necessario attendere l'uscita del comando prima di eseguire qualsiasi altra operazione. In caso contrario, il processo termina prematuramente senza installare nulla. Per informazioni dettagliate, vedere l'esempio riportato di seguito.
Esempi di uso di RUN con Windows
Nell'esempio seguente Dockerfile usa DISM per installare IIS nell'immagine del contenitore:
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart
Questo esempio installa il pacchetto ridistribuibile di Visual Studio.
Start-Process e il -Wait parametro viene usato per eseguire il programma di installazione. Ciò garantisce che l'installazione venga 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.
COPIA
L'istruzione COPY copia file e directory nel file system del contenitore. I file e le directory devono trovarsi in un percorso relativo al Dockerfile.
Il COPY formato dell'istruzione è simile al seguente:
COPY <source> <destination>
Se l'origine o la destinazione include spazio vuoto, 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 utilizzare le barre. Ad esempio, queste sono istruzioni valide COPY :
COPY test1.txt /temp/
COPY test1.txt c:/temp/
Nel frattempo, il formato seguente con barre rovesciata non funzionerà:
COPY test1.txt c:\temp\
Esempi di uso di COPY con Windows
Nell'esempio seguente viene aggiunto 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 la configurazione nella c:\temp directory dell'immagine del contenitore:
COPY config* c:/temp/
Per informazioni più dettagliate sull'istruzione COPY , vedere il riferimento ALLA COPIA.
ADD
L'istruzione ADD è simile all'istruzione COPY, ma con anche altre funzionalità. Oltre a copiare i file dall'host nell'immagine contenitore, l'istruzione ADD può anche copiare i file da una postazione remota con la specifica di un URL.
Il ADD formato dell'istruzione è simile al seguente:
ADD <source> <destination>
Se l'origine o la destinazione includono spazio vuoto, 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 utilizzare le barre. Ad esempio, queste sono istruzioni valide 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 espanderà i pacchetti compressi nella copia. Questa funzionalità non è disponibile in Windows.
Esempi di uso di ADD con Windows
Nell'esempio seguente viene aggiunto 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 c:\temp directory dell'immagine del contenitore.
ADD config* c:/temp/
Nell'esempio seguente verrà scaricato Python per Windows nella c:\temp directory 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 il riferimento ADD.
WORKDIR
L'istruzione WORKDIR imposta una directory di lavoro per le altre istruzioni Dockerfile, ad esempio RUN, CMD e imposta la directory di lavoro per l'esecuzione di istanze dell'immagine contenitore.
Il WORKDIR formato dell'istruzione è simile al seguente:
WORKDIR <path to working directory>
Considerazioni sull'uso di WORKDIR con Windows
In Windows, se la directory di lavoro include una barra rovesciata, è necessario usare un carattere di escape.
WORKDIR c:\\windows
esempi
WORKDIR c:\\Apache24\\bin
Per informazioni dettagliate sull'istruzione WORKDIR , vedere il riferimento a WORKDIR.
CMD
L'istruzione CMD imposta il comando predefinito da eseguire quando si distribuisce un'istanza dell'immagine contenitore. Ad esempio, se il contenitore ospiterà un server Web NGINX, le CMD istruzioni potrebbero includere 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 CMD formato dell'istruzione è simile al seguente:
# exec form
CMD ["<executable", "<param>"]
# shell form
CMD <command>
Considerazioni sull'uso di CMD con Windows
In Windows, i percorsi di file specificati nell'istruzione CMD devono usare le barre o le barre rovesciate con carattere di escape \\. Di seguito sono riportate 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 a CMD.
Carattere di escape
In molti casi, un'istruzione Dockerfile dovrà estendersi su più righe. A tale scopo, è possibile usare un carattere di escape. Il carattere di escape Dockerfile predefinito è una barra rovesciata, \. Tuttavia, poiché la barra rovesciata è anche un separatore di percorso file in Windows, l'uso per estenderlo su più righe può causare problemi. Per risolvere questo problema, è possibile usare una direttiva parser per modificare il carattere di escape predefinito. Per altre informazioni sulle direttive del parser, vedere Direttive del parser.
Nell'esempio seguente viene illustrata 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 parser di escape nella prima riga del Dockerfile. Questo può essere visto 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 altre informazioni sulla direttiva del parser di escape, vedere Direttiva del parser di escape.
PowerShell in Dockerfile
Cmdlet PowerShell
I cmdlet di PowerShell possono essere eseguiti in un Dockerfile con l'operazione RUN .
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell -command Expand-Archive -Path c:\apache.zip -DestinationPath c:\
Chiamate REST
Il cmdlet di Invoke-WebRequest 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 per SilentlyContinue 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.
È possibile usare PowerShell per scaricare i file durante il processo di creazione dell'immagine anche usando la libreria .NET WebClient. Questa opzione può migliorare le prestazioni del download. L'esempio seguente scarica il software di Python usando la libreria.
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 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 tramite 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 di 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 è simile al docker build 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