Docker – Les Docker files

.dockerignore

Création d’un fichier .dockerignore

A l’instar de Git, pour des gains de performance et des raisons de sécurité, il est préférable de créer un fichier .dockerignore (au même niveau que le Dockerfile) référençant les fichiers à écarter du contexte.

# comment
*/temp*
*/*/temp*
temp?

Dockerfile
*.md
!README.md
README-secret.md

Dockerfile

FROM <image>[:<tag>|@<digest>]

MAINTAINER <author's detail>

COPY <src> ... <dst>

ADD <src> ... <dst>

ENV <key> <value>

Les variables définies avec ENV pourront être utilisées avec les instructions ADD, COPY, ENV, EXPOSE, LABEL, USER, WORKDIR, VOLUME, STOPSIGNAL, et ONBUILD.

ARG <variable>[=<default value>]

Les variables définies avec ARG pourront être utilisées avec les instructions ADD, COPY, ENV, EXPOSE, LABEL, USER, WORKDIR, VOLUME, STOPSIGNAL, et ONBUILD.

USER <UID>|<UName>

WORKDIR <dirpath>

Souvent utilisée conjointement avec les commandes RUN, CMD et ENTRYPOINT.
Les commandes COPY et ADD l’utilise implicitement lors des copies vers une destination à chemin relatif. Relatif à WORKDIR justement.
WORKDIR <dirpath> est équivalent et préférable à RUN cd <dirpath>

HEALTHCHECK [<options>] CMD <command>

Vérifie l’état de santé d’un container en lançant la commande spécifiée à l’intérieur du container.
Après le timeout indiqué, le container est considéré en échec.
Après le nombre d’essais indiqués par l’option retry, le container est considéré comme unhealthy.
Rmq : exit 1 peut être remplacé par false.

• --interval=DURATION : Time between running the check (default: 30s)
• --retries=N : Consecutive failures needed to report unhealthy (default:3)
• --timeout=DURATION : Maximum time to allow one check to run (default: 30s)
• --start-period=DURATION : Start period for the container to initialize before starting health-retries countdown (default: 0s)

VOLUME ["<mountpoint>"]

ou

VOLUME <mountpoint>

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

Si le protocole n’est pas spécifié, c’est TCP par défaut.
Plusieurs ports/protocoles peuvent être exposés et spécifiés sur une seule instruction.

LABEL <key-1>=<val-1> <key-2>=<val-2> ... <key-n>=<val-n>

Il est préférable (mais non obligatoire) d’utiliser une seule instruction LABEL, quitte à déclarer plusieurs paires key=value pour la même instruction.

RUN <command>

Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
ou

RUN ["<exec>", "<arg-1>", ..., "<arg-n>"]

Forme Exec : Commande non exécutée dans un Shell.
RUN echo $HOME équivaut à RUN [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction RUN afin de réduire le nombre de layers lors de la construction de l’image.

Même commande, sur plusieurs lignes :

RUN apt-get update && \
    apt-get install -y apache2 && \
    apt-get clean

CMD ["<exec>", "<arg-1>", ..., "<arg-n>"]

Forme Exec : Commande non exécutée dans un Shell.
ou

CMD <command>

Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
CMD echo $HOME équivaut à CMD [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction CMD sachant que seule la dernière sera exécutée.

ENTRYPOINT ["<exec>", "<arg-1>", ..., "<arg-n>"]

Forme Exec : Commande non exécutée dans un Shell.
ou

ENTRYPOINT <command>

Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
ENTRYPOINT echo $HOME équivaut à ENTRYPOINT [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction ENTRYPOINT sachant que seule la dernière sera exécutée.

Construction de l’image à partir du Dockerfile

Généralement le Dockerfile se trouve à la racine du contexte (tout comme le .dockerignore).

$ docker image build .

ou

$ docker build .

ex :
Avec Dockerfile

FROM busybox
RUN echo "hello world"
COPY . /home/workfiles/

Avec .dockerignore

Dockerfile

$ docker image build .
Sending build context to Docker daemon  2.048kB
Step 1/3 : FROM busybox
latest: Pulling from library/busybox
90e01955edcd: Pull complete 
Digest: sha256:2a03a6059f21e150ae84b0973863609494aad70f0a80eaeb64bddd8d92465812
Status: Downloaded newer image for busybox:latest
 ---> 59788edf1f3e
Step 2/3 : RUN echo "hello world"
 ---> Running in af7de1f071bf
hello world
Removing intermediate container af7de1f071bf
 ---> 00778e2bdadf
Step 3/3 : COPY . /home/workfiles/
 ---> 14eedf0143d8
Successfully built 14eedf0143d8
$ docker image ls
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
<none>              <none>              14eedf0143d8        10 seconds ago      1.15MB
$ docker image history 14eedf0143d8
IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
14eedf0143d8        56 seconds ago      /bin/sh -c #(nop) COPY dir:880576b49fa41beee…   60B                 
00778e2bdadf        56 seconds ago      /bin/sh -c echo "hello world"                   0B                  
59788edf1f3e        13 days ago         /bin/sh -c #(nop)  CMD ["sh"]                   0B                  
<missing>           13 days ago         /bin/sh -c #(nop) ADD file:63eebd629a5f7558c…   1.15MB              
$ docker run -it --name busytest 14eedf0143d8
/ # ls /home/workfiles/
essai.txt

Mais il est possible de spécifier le chemin vers le Dockerfile et le contexte, tout en définissant un tag pour l’image :

$ docker image build -f /path/to/Dockerfile -t image:tag /path/to/context-dir/

ou

$ docker build -f /path/to/Dockerfile -t image:tag /path/to/context-dir/

ex :
Avec dockerfiles/Dockerfile

FROM busybox
RUN echo "hello world"
COPY . /home/workfiles/

$ docker image build -f dockerfiles/Dockerfile -t darwinos/repotest:busybox-V1.2 docker/
Sending build context to Docker daemon  2.095kB
Step 1/3 : FROM busybox
latest: Pulling from library/busybox
07a152489297: Pull complete 
Digest: sha256:141c253bc4c3fd0a201d32dc1f493bcf3fff003b6df416dea4f41046e0f37d47
Status: Downloaded newer image for busybox:latest
 ---> 8c811b4aec35
Step 2/3 : RUN echo "hello world"
 ---> Running in 6b6bbf94efeb
hello world
Removing intermediate container 6b6bbf94efeb
 ---> 7d7ff4a1708b
Step 3/3 : COPY . /home/workfiles/
 ---> 79d9a58ba6da
Successfully built 79d9a58ba6da
Successfully tagged darwinos/repotest:busybox-V1.2
$ docker image ls darwinos/repotest:busybox-V1.2
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
darwinos/repotest   busybox-V1.2        79d9a58ba6da        29 seconds ago      1.15MB

On peut ensuite lancer un container à partir de cette image :

$ docker run -it --name busytest darwinos/repotest:busybox-V1.2
/ # ls /home/workfiles/
essai.txt

docker-compose.yml

version

version: "3"

services

services:
   db:
     [...]

   wordpress:
     [...]

Le format de définition de chaque service se fait selon le format suivant :

services:
--> container name:
----> container options
--> container name:
----> container options

Chaque container créé portera un nom généré selon le format : dossier-courant_service-name_X, sauf si la sous-instruction container_name: est présente.

image

db:
  image: postgres:9.4

build

webapp:
  build: ./dir

webapp:
  build:
    context: ./dir
    dockerfile: Dockerfile-alternate
    args:
      buildno: 1

context

worker:
  build:
    context: ./worker

dockerfile

worker:
  build:
    context: ./worker
    dockerfile: Dockerfile-alternate

args

#Dockerfile
ARG buildno
ARG gitcommithash

RUN echo "Build number: ${buildno}"
RUN echo "Based on commit: ${gitcommithash}"

#Compose file : arguments sous forme de dictionnaire
webapp:
  build:
    context: .
    args:
      buildno: 1
      gitcommithash: cdc3b19

#Compose file : arguments sous forme de liste
webapp:
  build:
    context: .
    args:
      - buildno=1
      - gitcommithash=cdc3b19

labels

#Labels sous forme de dictionnaire
webapp:
  build:
    context: .
    labels:
      com.example.description: "Accounting webapp"
      com.example.department: "Finance"
      com.example.label-with-empty-value: ""

#Labels sous forme de liste
webapp:
  build:
    context: .
    labels:
      - "com.example.description=Accounting webapp"
      - "com.example.department=Finance"
      - "com.example.label-with-empty-value"

command

command: bundle exec thin -p 3000


command: ["bundle", "exec", "thin", "-p", "3000"]


command: python app.py

volumes

#Volume de type volume : nouvelle notation
web:
  image: nginx:alpine
  volumes:
    - type: volume
      source: mydata
      target: /data

volumes:
  mydata:



#Volume de type volume : ancienne notation
web:
  image: nginx:alpine
  volumes:
    - "mydata:/data"

volumes:
  mydata:



#Volume de type bind : nouvelle notation	  
web:
  image: nginx:alpine
  volumes:
    - type: bind
      source: ./static
      target: /opt/app/static



#Volume de type bind : ancienne notation		
web:
  image: nginx:alpine
  volumes:
    - ./static:/opt/app/static

ports

#Nouvelle notation
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host




#Ancienne notation
ports:
  - "8080:80"

networks

vote:
  build: ./vote
  command: python app.py
  volumes:
    - ./vote:/app
  ports:
    - "5000:80"
  networks:
    - front-tier
    - back-tier

networks:
  front-tier:
  back-tier:

container_name

redis:
  image: redis:alpine
  container_name: redis
  ports: ["6379"]
  networks:
    - back-tier

depends_on

version: '3'
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

environment

#Sous forme d'un dictionnaire
environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:



#Sous forme d'une liste
environment:
  - RACK_ENV=development
  - SHOW='true'
  - SESSION_SECRET

restart

redis:
  image: redis:alpine
  container_name: redis
  restart: always
  ports: ["6379"]
  networks:
    - back-tier

healthcheck

• interval: DURATION : Time between running the check (default: 30s)
• retries: N : Consecutive failures needed to report unhealthy (default:3)
• timeout: DURATION : Maximum time to allow one check to run (default: 30s)
• start_period: DURATION : Start period for the container to initialize before starting health-retries countdown (default: 0s)

web:
  image: nginx
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost"]
    interval: 1m30s
    timeout: 10s
    retries: 3
    start_period: 1m

docker-stack.yml

deploy

version: '3'
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

mode

version: '3'
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global



version: '3'
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

replicas

version: '3'
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

restart_policy

version: "3"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

condition

version: "3"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

delay

version: "3"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

max_attempts

version: "3"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

window

version: "3"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

update_config

version: '3.4'
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s

rollback_config

version: '3.7'
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      rollback_config:
        parallelism: 2
        delay: 10s

parallelism

version: '3.4'
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s

delay

version: '3.4'
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s

configs (syntaxe courte)

version: "3.3"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

configs (syntaxe longue)

version: "3.3"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

secrets (syntaxe courte)

version: "3.1"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

secrets (syntaxe longue)

version: "3.1"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

Pour aller plus loin

• Exemples de fichiers Dockerfile
• Exemples de fichiers docker-compose.yml
• YAML – Memo Bases

Références

• Docker docs – Dockerfile reference
• Docker docs – Best practices for writing Dockerfiles
• Docker docs – Compose file version 3 reference
• Label Schema Convention DRAFT (1.0.0-rc.1)
• The Secret Lives of Data – Raft Understandable Distributed Consensus