El Fitxer Dockerfile

Informació extreta de Referència de Docker.

Docker pot crear imatges automàticament llegint les instruccions del fitxer Dockerfile, Aquest és un document de text que conté totes les ordres que un usuari pot escriure a la línia de comandes per muntar una imatge. Per a saber-ne més, recomano accedir a Writing a Dockerfile.

Ús

La comanda docker build . crea un contenidor a partir d'un fitxer Dockerfile del directori actual.

Compte

Compte on executem la comanda ja que tots els fitxers a partir del directori especificat es transferiran al contenidor.

Normalment es busca el fitxer Dockerfile a l'arrel del PATH especificat. Per especificar un fitxer Dockerfile d'un altre directori caldrà utilitzar el paràmetre -f de la següent forma:

Dockerfile -f pathAlFitxer .

Fixeu-vos que continuem tenint el directori que es transferirà al final de la comanda. Podem especificar una etiqueta (i un dipòsit) al crear el contenidor amb el paràmetre -t. Per exemple: docker build -t daw/entorn .

Format

El format a utilitzar és el següent:

# Comentari
INSTRUCCIÓ arguments

La instrucció no distingeix entre majúscules i minúscules. Tanmateix, convé que siguin majúscules per distingir-les dels arguments amb més facilitat.

Docker executa les instruccions del fitxer Dockerfile en ordre. Un fitxer Dockerfile ha de començar amb una instrucció FROM. Abans, però, podem ternir-hi directives d'analitzador , comentaris i variables d'entorn. La instrucció FROM especifica la imatge principal des de la qual estem creant el contenidor. FROM només pot anar precedit d 'una o més instruccions, que declaren les variables d'entorn que s'utilitzen a les línies FROM del fitxer Dockerfile.

Directrius d'analitzador

Les directrius d'analitzador són opcionals i afecten la manera com es gestionen les línies posteriors a . Les directrius d'analitzador no afegeixen capes a la compilació i no es mostraran com a pas de construcció. Les directrius d'analitzador s'escriuen com un tipus especial de comentari al formulari # directiva=valor. Una única directiva només es pot utilitzar una vegada.

Una vegada s'ha processat un comentari, una línia buida o una instrucció del constructor, Docker ja no busca directrius d'analitzador. En el seu lloc, tracta qualsevol cosa formatada com una directiva d'analitzador com un comentari i no intenta validar si es pot tractar d'una directiva d'analitzador. Per tant, totes les directrius d'analitzador han d'estar a la part superior d'un ´Dockerfile´.

Les directrius d'analitzadors no distingeixen entre majúscules i minúscules. No obstant això, convé que siguin minúscules. El conveni també inclou una línia en blanc seguint les directrius de l'analitzador. Els caràcters de continuació de línia no s'admeten a les directives de l'analitzador.

Les directives d'analitzador són les següents:

• syntax

• escape

syntax

# syntax=[remote image reference]

Per exemple:

# syntax=docker/Dockerfile:1
# syntax=docker.io/docker/Dockerfile:1
# syntax=example.com/user/repo:tag@sha256:abcdef...

La directiva syntax defineix la ubicació de la sintaxi Dockerfile que s'utilitza per construir el Dockerfile.

escape

# escape=\

O bé

# escape=`

La directiva escape estableix el caràcter utilitzat per escapar dels caràcters d'un fitxer Dockerfile. Si no s'especifica, el caràcter d'escapament per defecte és .

Variables d'entorn

Podem definir variables d'entorn amb el paràmetre ENV i després utilitzar aquestes variables en d'altres instruccions posteriors. Exemple:

FROM busybox
ENV FOO=/bar
WORKDIR ${FOO}   # WORKDIR /bar
ADD . $FOO       # ADD . /bar
COPY \$FOO /quux # COPY $FOO /quux

Les variables d'entorn poden utilitzar-se en les comandes següents:

ADD	COPY	ENV	EXPOSE
FROM	LABEL	STOPSIGNAL	USER
VOLUME	WORKDIR	ONBUILD (Combinat amb qualsevol altra instrucció de la llista)

Fitxer .dockerignore

Abans d'enviar el contexte al contenidor, docker busca un fitxer anomenat .dockerignore a l'arrel del directori del contexte. Si aquest existeix llavors s'exclouran del contexte tots aquells fitxers i/o diretoris que facin match amb el patró especificat.

Docker tracta aquest fitxer com una llista depatrons separats per un salt de línia (cada patró en una línia diferent). A efectes de coincidència, es considera que l'arrel del context és tant el directori de treball com l'arrel. Per exemple, els patrons /foo/bar i foo/bar tots dos exclouen un fitxer o directori anomenat bar al subdirectori foo del PATH o a l'arrel del repositori git situat a la URL. Cap exclou res més. Quan una línia conté el caràcter # a la primer columna, es considerarà un comentari.

Exemple de fitxer .dockerignore:

# commentari
*/temp*
*/*/temp*
temp?

Aquest fitxer provoca el següent comportament:

Regla	Comportament
# comment	S'ignora
*/temp*	Exclou fitxers i directoris els noms dels quals comencin per temp a qualsevol subdirectori immediat de l'arrel. Per exemple, s'exclou un fitxer tal com /directori/temporal.txt i també exclouria un directori anomenat /directori/temp
*/*/temp*	Exclou fitxers i directoris que comencen per temp des de qualsevol subdirectori que es troba a dos nivells per sota de l'arrel. Per exemple el fitxer /directori/subdirectori/temporal.txt està exclòs.
temp?	Exclou fitxers i directoris al directori arrel els noms dels quals tingui un caràcter després de la paraula temp. Per exemple, /tempA i /tempB estan exclosos.

Docker també admet una cadena de comodins especial ** que coincideix amb qualsevol nombre de directoris (inclòs zero). Per exemple, **/*.go exclourà tots els fitxers que acabin amb .go que es trobin a qualsevol directori, inclós l'arrel del context de compilació.

Les línies que comencen per ! (signe d'exclamació) es poden utilitzar per fer excepcions a les exclusions. El següent és un exemple de fitxer .dockerignore que utilitza aquest mecanisme:

*.md
!README.md

I si hi ha coincidències?

L'última línia del fitxer .dockerignore que coincideix amb un fitxer determinat determina si s'inclou o s'exclou.

Si vols especificar quins fitxers incloure en el context, en lloc de quins excloure cal especificar * com a primer patró, seguit d'un o més ! patrons d'excepció.

FROM

FROM [--platform=<platform>] <image> [AS <name>]

o bé

FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]

o bé

FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]

La instrucció FROM inicialitza un contenidor i estableix la imatge base per a instruccions posteriors. Com a tal, un Dockerfile' ha de començar amb una instruccióFROM`. La imatge pot ser qualsevol imatge vàlida; és especialment fàcil començar traient una imatge dels repositoris públics.

• FROM pot aparèixer diverses vegades dins d'un sol Dockerfile per crear diverses imatges o utilitzar una etapa de compilació com a dependència d'una altra. Simplement anota l'última identificació d'imatge que ha generat el commit abans de cada nova instrucció FROM. Cada instrucció FROM neteja qualsevol estat creat per instruccions anteriors.

• Opcionalment, es pot donar un nom a un contenidor afegint AS nom a la instrucció FROM. El nom es pot utilitzar en instruccions FROM i COPY --from=<nom> per referir-se a la imatge creada en aquesta etapa.

• Els valors tag o digest són opcionals. Si no s'especifiquen, el constructor assumeix una etiqueta per defecte. El constructor torna un error si no troba el valor de l'etiqueta.

• El paràmetre --platform és opcional i es pot utilitzar per especificar la plataforma de la imatge en cas que FROM faci referència a una imatge multiplataforma. Per exemple, linux/amd64, linux/arm64, o windows/amd64.

Interactuació de ARG i FROM

Exemple per entendre-ho:

ARG CODE_VERSION=latest
FROM base:${CODE_VERSION}
CMD /code/run-app

FROM extras:${CODE_VERSION}
CMD /code/run-extras

RUN

RUN té dues formes:

• RUN <command> ( formulari de l' intèrpret d'ordres , l'ordre s'executa en un intèrpret d'ordres, que per defecte és /bin/sh -c a Linux o cmd /S /C a Windows)

• RUN ["executable", "param1", "param2"] ( formulari d' execució )

La instrucció RUN executarà qualsevol ordre en una nova capa a sobre de la imatge actual i confirmarà els resultats. La imatge compromesa resultant s'utilitzarà per al següent pas del fitxer Dockerfile.

CMD

La instrucció CMD té tres formes:

• CMD ["executable","param1","param2"]( formulari exec , aquest és el formulari preferit)

• CMD ["param1","param2"] (com a paràmetres predeterminats a ENTRYPOINT )

• CMD command param1 param2 ( forma de shell )

Només hi pot haver una instrucció CMD al Dockerfile. Si hi ha més d'un CMD, només entrarà en vigor l'últim.

El propòsit principal d'un CMD és proporcionar els valors predeterminats per a un contenidor en execució. Aquests valors predeterminats poden incloure un executable o poden ometre l'executable, en aquest cas també cal especificar una instrucció ENTRYPOINT.

Si CMD s'utilitza per proporcionar els arguments per defecte per a la instrucció ENTRYPOINT, tant el CMD com l'ENTRYPOINT cal especificar-los amb el format de matriu JSON.

Nota

El formulari exec s'analitza com una matriu JSON, el que significa que heu d'utilitzar cometes dobles (") al voltant de paraules no cometes simples (').

LABEL

LABEL <key>=<value> <key>=<value> <key>=<value> ...

La instrucció LABEL afegeix metadades a una imatge. Com exemple d'ús podem veure:

LABEL "com.example.vendor"="ACME Incorporated"
LABEL com.example.label-with-value="foo"
LABEL version="1.0"
LABEL description="Aquest text mostra com \
els valors de label poden ocupar vàries línies."

Una imatge pot tenir més d'una etiqueta. Podeu especificar diverses etiquetes en una sola línia. Podeu escollir especificar diverses etiquetes en una sola instrucció, d'una de les dues maneres següents:

LABEL multi.label1="value1" multi.label2="value2" other="value3"

o bé

LABEL multi.label1="value1" \
      multi.label2="value2" \
      other="value3"

Les etiquetes incloses a les imatges base o pare (imatges de la línia `FROM ) són heretades per la vostra imatge. Si ja existeix una etiqueta però amb un valor diferent, el valor aplicat més recentment substitueix qualsevol valor establert anteriorment.

Per veure les etiquetes d'una imatge, utilitzeu l' docker image inspectordre. Podeu utilitzar l'opció --format per mostrar només les etiquetes;

docker image inspect --format='' myimage

EXPOSE

EXPOSE <port> [<port>/<protocol>...]

La instrucció EXPOSE informa Docker que el contenidor escolta els ports de xarxa especificats en temps d'execució. Pots especificar si el port escolta a TCP o UDP. Si no s'especifica el protocol, el valor per defecte és TCP.

La instrucció EXPOSE en realitat no publica el port. Funciona com un tipus de documentació entre la persona que crea la imatge i la persona que dirigeix ​​el contenidor, sobre quins ports es pretenen publicar. Per publicar realment el port quan s'executa el contenidor, utilitzeu el flag -p activat per publicar i assignar un o més ports, o bé el flag -P per publicar tots els ports exposats i assignar-los a ports de gran ordre.

Per defecte, EXPOSE assumeix el protocol TCP. També es pot especificar UDP:

EXPOSE 80/udp

Per exposar tant a TCP com a UDP, cal afegir dues línies:

EXPOSE 80/tcp
EXPOSE 80/udp

En aquest cas, si utilitzes -P amb docker run, el port s'exposarà una vegada per a TCP i una altra per a UDP. Recorda que -P utilitza un port efímer d'amfitrió d'alta per cada ordre a l'amfitrió, de manera que el port no serà el mateix per a TCP com per UDP.

Independentment de la configuració amb la comapnda EXPOSE, pots substituir-les en temps d'execució mitjançant el flag -p. Per exemple

docker run -p 80:80/tcp -p 80:80/udp ...

ENV

ENV <key>=<value> ...

La instrucció ENV estableix la variable d'entorn <key> al valor <value>. Aquest valor estarà a l'entorn per a totes les instruccions posteriors de l'etapa de construcció i també es pot substituir en línia en moltes altres. El valor s'interpretarà per a altres variables d'entorn, de manera que els caràcters de cometes s'eliminaran si no s'escapen. Igual que l'anàlisi de la línia d'ordres, les cometes i les barres invertides es poden utilitzar per incloure espais dins dels valors.

Exemple:

ENV MY_NAME="John Doe"
ENV MY_DOG=Rex\ The\ Dog
ENV MY_CAT=fluffy

Les variables d'entorn establertes utilitzant ENV persistiran quan s'executi un contenidor des de la imatge resultant. Podeu veure els valors amb docker inspect i canviar-los amb docker run --env <key>=<value>.

ADD

ADD té dues formes:

ADD [--chown=<user>:<group>] <src>... <dest>
ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]

Aquesta darrera forma és obligatòria pels paths que contenen espais en blanc.

La instrucció ADD copia fitxers, directoris i URLs remotes des de <src> i els afegeix al sistema de fitxers de la imatge en el destí <dest>. Cada <src> pot contenir caràcters comodí. <dest> pot ser un directori absilut o relatiu al directori de treball.

Tots els fitxers i directoris nous es creen amb un UID i un GID de 0, tret que el flag opcional --chown especifiqui un nom d'usuari, un nom de grup o una combinació UID/GID determinats per sol·licitar la propietat específica del contingut afegit. El format del flag --chown permet cadenes de nom d'usuari i de nom de grup o UID i GID sencers directes en qualsevol combinació.

COPY

COPY té dues formes:

COPY [--chown=<user>:<group>] <src>... <dest>
COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]

Aquesta darrera forma és obligatòria pels paths que contenen espais en blanc.

La instrucció COPY copia fitxers o directoris nous <src> i els afegeix al sistema de fitxers del contenidor del camí d'accés <dest>.

Els <src> poden especificar diversos recursos, però els camins de fitxers i directoris s'interpretaran com a relatius a la font del context de la compilació. Cadascun dels <src> pot contenir comodins.

Per afegir tots els fitxers que comencin per "hom":

COPY hom* /mydir/

<dest> és una ruta absoluta, o un camí relatiu a WORKDIR, en el qual es copiarà la font a l'interior del contenidor de destinació

Nota

El directori en si mateix no es copia, només el seu contingut.

ADD o COPY? No són el mateix?

Sempre que es pugui utilitzarem COPY tal i com recomanen les millors pràctiques de Docker, però, cal tenir en compte que ADD permet que <src> sigui, a més, una URL o un fitxer comprimit. Per tant:

• ADD permet que <src> sigui una URL

• Si el paràmetre <src> de ADD és un fitxer comprimit en un format de compressió reconegut, es descomprimirà.

ENTRYPOINT

ENTRYPOINT cal definir-se quan utilitzem el contenidor com un executable.

ENTRYPOINT té dues formes:

La forma exec, que és la preferible:

ENTRYPOINT ["executable", "param1", "param2"]

La forma shell:

ENTRYPOINT command param1 param2

VOLUME

VOLUME ["/data"]

La instrucció VOLUME crea un punt de muntatge amb el nom especificat i el marca com a contenidor de volums muntats externament des de l'amfitrió natiu o altres contenidors. El valor pot ser una matriu JSON VOLUME ["/var/log/"], o una cadena senzilla amb diversos arguments, com ara VOLUME /var/logo, VOLUME /var/log /var/db. Per a més informació podem accedir a Volums a Docker