This is an old revision of the document!
Table of Contents
Dockerfile: Guía rápida y completa
Directivas de un fichero Dockerfile
ARG inicializa variables que solo estarán operativas en la creación de la imagen, no en los contenedores basados en la misma. Antes del FROM se pueden indicar directivas de parseo y/o ARG para inicializar alguna variable.
ARG VERSION=latest
FROM indica la imagen que se va a usar como base. Es bueno escribir una versión si la imagen va a perdurar en el tiempo y será distribuida. No se recomienda usar “latest” ya que nunca sabremos cuando cambiará la imagen en remoto.
FROM alpine:$VERSION
RUN ejecuta comandos para la construcción de la imagen, NO en el contenedor. En este caso instala socat y nginx, además de crear el directorio “/run/nginx”. Suele utilizarse para instalar paquetes, descargar contenido, correr scripts necesarios para la construcción etc
RUN apk add socat nginx RUN mkdir -p /run/nginx
Si nombramos de nuevo con ARG la variable definida en la primera linea antes del “FROM” podemos sobrescribirla desde la linea de comandos o bien inicializarla con un valor (denominado valor predeterminado). No se pueden definir directamente desde la linea de comandos, siempre deben estar en el Dockerfile primeramente.
ARG VERSION
Por ejemplo ARG puede usarse para desactivar instalaciones interactivas en diversos sistemas,en sistemas Debian se podría usar la siguiente variable DEBIAN_FRONTEND=noninteractive“.
ARG DEBIAN_FRONTEND=noninteractive
Con ARG no deben usarse credenciales ni llaves criptográficas ya que estas estarían visibles al ejecutar “docker history”. Las variables son únicamente validas en el momento de definirse. La última definición de la variable en el Dockerfile será la que puede ser sobrescrita desde la linea de comandos. Si se usan múltiples FROM (multi-stage builds), ARG debe estar también definida en cada stage. La construcción por etapas se explica más adelante.
Las variables definidas von ARG pueden ser sobrescritas siempre con ENV (se verá más adelante), haciendo inútil por tanto el uso de la sustitución por linea de comando de variables definidas mediante ARG. Ejemplo de sustitución de variable definida con ARG.
ARG CONT_IMG_VER
ENV CONT_IMG_VER=v1.0.0
Docker incluye una serie de variables predefinidas, que no necesitan introducirse en el Dockerfile primeramente y pueden ser inicializadas desde el Dockerfile o directamente con ”--build-arg“. Estas variables NO se incluyen en la salida de docker history. Recordar que si no se definen las variables, a excepción de estas, mediante ARG en el Dockerfile, estás no pueden ser inicializadas desde la linea de comandos.
HTTP_PROXY http_proxy HTTPS_PROXY https_proxy FTP_PROXY ftp_proxy NO_PROXY no_proxy
EXPOSE define el puerto expuesto por el comando ejecutado, es solo informativo para que el usuario que use la imagen utilice las opciones de mapeo de puertos que quiera. El mapeo, al igual que con los volúmenes de Docker, no pueden ser mapeados desde le fichero Dockerfile y se hace siempre desde la linea de comano u otras aplicaciones externas de gestión de contenedores.
EXPOSE 80/tcp
USER facilita configurar el propietario (UID/Grupo) usado por los comandos RUN, CMD y ENTRYPOINT. Solo puede definirse un grupo de usuario, no varios. Si no se define grupo, este será root. Al configurar un usuario para correr la aplicación, NO es necesario que se cree el id de usuario previamente en la imagen (al no ser que se especifiquen nombres en vez de ids).
# Usando IDs. USER 567:567 # Usando nombre de usuario. USER manolo
NOTA: Se debe tener en cuenta que el sistema de ficheros estará como root, por lo que si el proceso interactúa con ficheros y directorios, habrá que preocuparse de configurar permisos previamente.
RUN groupadd -g 567 user && \ useradd -r -u 567 -g user user USER 567:567 # Si queremos la coniguración 567:0 simplemente no debe definirse grupo. #USER 567
Si el comando ejecutado usa ficheros de configuración para establecer el usuario, como por ejemplo Apache o Nginx, el uso de USER no será efectivo.
ENTRYPOINT y CMD permiten ejecutar un comando predeterminado al iniciar el contenedor. Como funcionalidad agregada usando la instrucción CMD junto con ENTRYPOINT, se puede usar para pasar o completar parámetros al ejecutable configurado en ENTRYPOINT. Esto facilita sobrescribir los parámetros desde la linea de comandos, cosa que con las opciones de linea de comandos de “entrypoint” es algo más laborioso.
ENTRYPOINT modo shell, este método arranca un subproceso de ”/bin/sh -c“ para ejecutar lo definido. No es recomendable su uso ya que el que recibe las señales del sistema es el proceso shell y no el programa que ejecutamos en ENTRYPOINT. Tampoco es compatible con el uso de CMD para asignar parámetros.
ENTRYPOINT top
Para solventar el problema de la no recepción de señales del sistema (ej docker stop XXX), es recomendable usar el comando exec para sustituir al proceso padre shell por el comando a ejecutar.
ENTRYPOINT exec top
NOTA: Si en vez de una aplicación en el contenedor se debe usar un script que arranque varios ejecutables en el contenedor, en la documentación oficial hay varios hacks de interés: https://docs.docker.com/engine/reference/builder/#exec-form-entrypoint-example
ENTRYPOINT modo Exec no arranca el proceso a través de shell si no directamente, es el uso recomendado de ENTRYPOINT y el que se usa con el uso de la linea de comandos mediante ”--entrypoint“. CMD deben usarse también en esta sintaxis cuando se usa como argumentos de ENTRYPOINT.
ENTRYPOINT ["nginx"] CMD ["-g", "daemon off;"]
ENTRYPOINT sin el uso de CMD para parámetros. EL uso de CMD junto con ENTRYPOINT es interesante si se quieren sobrescribir cómodamente los parámetros desde la linea de comandos. Si esto no es requerido, puede usarse ENTRYPOINT unicamente.
ENTRYPOINT ["nginx","-g", "daemon off;"]
CMD también tiene su modo shell y Exec. Al igual que ENTRYPOINT, si no se usan corchetes estamos ejecutando el comando a partir de un proceso shell padre.
# Modo Exec. CMD ["nginx","-g", "daemon off;"] # Modo shell. CMD nginx -g 'daemon off;'
Si hay varios ENTRYPOINT solo el último tiene efecto. Lo mismo pasa con CMD. En un Dockerfile unicamente puede haber una instrucción CMD y ENTRYPOINT.
Tabla con todas las combinaciones posibles entre ENTRYPOINT y CMD en base al uso de parámetros y a sus diferentes modos de ejecución (shell / Exec):
| No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT [“exec_entry”, “p1_entry”] | |
|---|---|---|---|
| No CMD | error, not allowed | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry |
| CMD [“exec_cmd”, “p1_cmd”] | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry exec_cmd p1_cmd |
| CMD [“p1_cmd”, “p2_cmd”] | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd |
| CMD exec_cmd p1_cmd | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd |
LABEL permite especificar etiquetas de varias formas. Pueden ser visualizadas con el comando “inspect”.
LABEL "Entorno"=":Imagen de prueba" LABEL "Descripción"="Vamos a probar un poco esto de Docker a ver cómo fuciona." "Version"="1.0" LABEL multi.label1="value1" \ multi.label2="value2" \ other="value3"
ENV permite establecer variables de entorno que a diferencia de ARG perduran en el contenedor. Se pueden usar múltiples veces incluso en la misma linea. También puede usarse como vimos anteriormente para sobrescribir variables inicializadas con ARG,
ENV variable="variable de entorno pasada por ENV" variable2=variable2\ de\ entorno\ pasada\ por\ ENV
ADD permite copiar ficheros del host a la imagen y los contenedores dispondrán de esos ficheros, permite configurar propietario y grupo. Si se especifica el nombre de usuario, este debe estar en ”/etc/passwd“ y ”/etc/group“. Se debe de usar siempre rutas relativas al directorio donde creemos la imagen con el Dockerfile. Para el destino sí se deben usar rutas absolutas. Se pueden especificar varios origenes pero NO sin son remotos.
La diferencia con COPY es que ADD descomprime automáticamente ficheros comprimidos y permite descargar de internet archivos. Los permisos predeterminados son 600 para los ficheros obtenidos remotamente con ADD.
ADD --chown=XXXX:XXXX "alpine-minirootfs-3.13.0-x86_64.tar.gz" /opt/codicoalpine # ADD decomprimirá el tar.gz en /opt/codigoalpine, si no se desea la descompresión automática se debe usar COPY. # La aplicación de permisos en este caso no se aplican a los ficheros descomprimidos.
ADD no es compatible con procesos de autenticación cuando usamos origenesremotos. En esos casos se puede usar RUN von wget o cualquier otro software que permite descargar mediante autenticación.
ADD https://freetsa.org/files/cacert.pem /opt/
COPY no permite usar ficheros remotos y no descomprime los ficheros de manera automáticamente como si hace ADD.
COPY --chown=XXXX:XXXX "alpine-minirootfs-3.13.0-x86_64.tar.gz" /opt/codicoalpine # El propietario de /opt/codicoalpine/alpine-minirootfs-3.13.0-x86_64.tar.gz sera XXXX.
La ruta origen es relativa siempre al directorio de trabajo donde estemos (PWD).
COPY directorio_local/ /opt/codicoalpine/
NOTA: Si en el destino se usa una ruta relativa, será en base al WORKDIR usado por la imagen. Si se copia un directorio del anfitrión (host) los permisos son también copiados (no así el propietario).
VOLUME permite crear volumenes al arrancar el contenedor. En este ejenplo se crearán dos volúmenes para esos directorios del contenedor (Para montar directorios del host se usa ”-v“ en linea de comandos, no es posible definir eso desde el Dockerfile). Esto se debe a que podría provocar problemas al cambiar de host si este no tiene la misma carpeta.
VOLUME /opt/volumen1 /opt/volumen2 COPY "alpine-minirootfs-3.13.0-x86_64.tar.gz" /opt/volumen2/
WORKDIR configura el directorio de trabajo, sencillamente es la carpeta donde ejecutaran RUN, CMD, ENTRYPOINT, COPY y ADD sus instrucciones. Si no existe el directorio es creado automáticamente. Puede usarse varias veces y puede ampliarse múltiples veces si la primera inicialización usa una ruta directa y las siguientes relativas. También puede interactuar con ENV. Los WORKDIR no crean nuevas capas a la hora de crear imágenes.
# En este ejemplo el COMANDO1 será ejecutado en el WORKDIR /root/carpeta1/subcarpeta1 y el COMANDO2 en /opt. ENV DIRPATH=/root WORKDIR $DIRPATH/carpeta1 WORKDIR subcarpeta1 RUN COMANDO1 WORKDIR /opt/ RUN COMANDO2
ONBUILD se usa sobre todo en creación de imágenes base y orientado a imágenes cuya finalidad sea compilar/construir algo. Funciona como una especie de include de comandos que se ejecutarán sobre las imágenes derivadas. Por ejemplo permite ahorrar espacio en los Dockerfile y no repetir configuraciones. Veamos un ejemplo simple.
# Se construye la imagen base con el siguiente Dockerfile. FROM maven:3.6.0-alpine WORKDIR app ONBUILD COPY . /app ONBUILD RUN mvn package
# Se crea la imagen de nombre mavenbase. docker build -f Dockerfile -t mavenbase .
En otro Dockerfile configuramos el siguiente FROM especificando la imagen anterior y se procederá a ejecutar esos comandos sobre la imagen. De esa manera no se repetiría tanto comando “COPY” y “RUN” al tener muchos Dockerfiles similares.
FROM mavenbase:latest
STOPSIGNAL facilita especificar la señal con la que el contenedor debe terminar.De manera predeterminada, mediante “docker stop” se envían la señal “SIGTERM” y si no termina, después de un periodo de gracia de 10 segundos de forma predeterminada, SIGKILL.
STOPSIGNAL signal
HEALTHCHECK Permite especificar nuestros propios checks de comprobación. Solo puede haber uno por Dockerfile.
HEALTHCHECK --interval=DURATION CMD curl -f http://localhost/ || exit 1 --timeout=DURATION --start-period=DURATION --retries=N
Construcción de imágenes Docker multietapas (multi-stage)
Para poder disponer de imágenes pequeñas se necesita que estas tengan el mínimo indispensables de ficheros para correr la aplicación deseada. Para ello en los Dockerfiles es posible utilizar y trabajar sobre varias imágenes base para que al final, una última imagen pueda copiar los ficheros ya construidos en esas etapas de construcción anteriores (imágenes temporales). Esas imágenes intermedias (etapas de construcción) se reerencian mediante la instrucción AS y desaparecen al terminar el proceso de consutrcción.
El proceso es simple, cada etapa empieza con FROM, se asigna mediante AS un nombre que luego es referenciado mediante COPY --from en la imagen final.
En este ejemplo se crea una imagen a partir de apine:latest, la cual copia contenido de dos distros diferentes. debian:latest (AS busi) y “nginx:latest” (Al no estar definida en el Dockerfile, usará Dockerhub).
ARG VERSION=latest FROM debian:$VERSION as busi RUN apt-get update && \ apt-get install -y nginx ARG VERSION=latest FROM alpine:$VERSION COPY --from=nginx:latest /etc/nginx/nginx.conf /opt/imagen_nginx/ COPY cacert.pem /opt/ COPY --from=busi /etc/apt/ /etc/nginx/nginx.conf /opt/imagen_debian/
docker build -t alpine_multistage .
En este absurdo ejemplo para entender su uso, la imagen de nombre “alpine_multistage” creada tendrá en ”/opt/“ el fichero cacert.pem.procedente del host. En /opt/imagen_nginx el fichero nginx.conf de la imagen remota “nginx:latest” obtenida desde Dockerhub automáticamente.Y para finalizar en el directorio /opt/imagen_debian/ encontraremos el contenido de /etc/apt/ y el fichero nginx.conf de la imagen debian.
Consejos / Buenas prácticas
El consejo general al crear Dockerfiles es usar el mínimo de lineas necesarias para crear menos capas. También se debe prestar atención al orden de las instrucciones para hacer eficiente el uso de cache.
El orden de los comandos influye en ell uso de la cache, al cambiar una linea las lineas posteriores quedarían invalidadas para usar en cache y deben ser procesadas de nuevo. Por lo tanto es mejor poner al final las lineas que vayan a ser modificadas más frecuentemente.
Si se van a instalar paquetes, es mejor todo en una linea que no en varias.
Al copiar ficheros siempre es mejor especificar varios origines si el destino es siempre el mismo. De esa manera se ahorran lineas con ADD y COPY. También es interesante el uso de ficheros .dockerignore para evitar copiar determinados ficheros sin necesidad de esquivarlos usando múltiples ADD y/o COPY.
Si se puede usar una versión oficial de una imagen docker suele ser mejor opción que construirla uno mismo.
Usar WORKDIR con los valores de rutas para usar con COPY, ADD y RUN y no estar especificando en cada linea una ruta. (Los WORKDIR además no usan capas).
Para producción se debería tener el mínimo instalado, es decir, a la hora de crear imágenes personalizadas, no agregar paquetes que no se necesitan. Para depurar siempre pueden ser instalados posteriormente. También sería recomendable limpiar la cache de paquetes, etc. El uso de varias etapas (multi-stage) permite incluir varios FROM y poder crear etapas intermedias de las que copiar unicamente los ficheros necesarios para la imagen final.
El uso de ONBUILD permite también ahorrarnos repetir instrucciones cuando se necesitan muchos ficheros Dockerfile similares.
Se debería especificar la versión concreta de una imagen y evitar uso de versiones “latest” ya que esta cambiará en el tiempo.
Las imágenes Alpine no usa libc, por lo que no siempre sirve para todo, pero si en la mayoría de casos, por lo que es una buena imagen para usar como base.
Si se puede evitar el uso de root (usuario predeterminado) mejor.
Crear una imagen con nombre personalizado.
docker build -t alpine_busi .