Docker & Docker Compose — Le cours

Guide 03 / 3

Dockerfile & compose.yaml

Comprendre chaque instruction et ses conséquences sur le build ou l’exécution.

Résultat attendu :

Expliquer le cycle Dockerfile → image → conteneur et configurer des services Compose.

Lecture
0%

01 · Comment les fichiers travaillent ensemble

Dockerfile décrit comment fabriquer une image ; compose.yaml décrit comment exécuter les services. Ce ne sont pas des langages de programmation ni, à proprement parler, l’API HTTP de Docker Engine.

Dockerfile

Recette de construction de l’image. Ses instructions sont traitées principalement pendant docker build.

Dockerfile → docker build → image

compose.yaml

Déclaration YAML de services, volumes et réseaux. Compose interprète cette configuration pour créer et faire fonctionner les conteneurs.

compose.yaml → docker compose up → services

API Docker Engine

Interface HTTP du démon Docker utilisée par des clients pour piloter l’Engine. Les mots FROM, RUN et CMD sont des instructions Dockerfile, pas des appels de cette API.

La CLI peut interroger l’API du démon pour lister des conteneurs.

02 · Instructions Dockerfile

Les instructions sont lues dans l’ordre pendant la construction ; certaines préparent l’image, d’autres définissent des valeurs utilisées au lancement.

FROM

Choisit l’image de base et commence une étape de build. Une image de base contient déjà un système minimal ou des outils.

FROM python:3.13-slim
À retenir :

Privilégier une référence explicite et maintenue.

RUN

Exécute une commande au moment de construire l’image : installer une bibliothèque, générer un fichier, préparer un dossier. Son résultat intègre l’image.

RUN pip install --no-cache-dir -r requirements.txt
À retenir :

RUN ne démarre pas le serveur lorsqu’on lance le conteneur.

CMD

Définit la commande par défaut exécutée au lancement du conteneur, ou des arguments pour ENTRYPOINT. Une commande de docker run peut la remplacer.

CMD ["python", "app.py"]
À retenir :

Seul le dernier CMD du Dockerfile prend effet.

ENTRYPOINT

Détermine le programme à exécuter quand le conteneur démarre. Ce programme devient généralement le processus principal (PID 1), par exemple le serveur web ou le script de l’application.

ENTRYPOINT ["python", "app.py"]
À retenir :

CMD peut compléter ENTRYPOINT avec des arguments.

COPY

Copie des fichiers du contexte de construction dans l’image. La destination est un chemin à l’intérieur de l’image, pas sur la machine hôte.

COPY ./src /app/src

ADD

Ajoute des fichiers et propose des fonctions supplémentaires (sources distantes, archives locales selon le cas). Pour une simple copie, privilégier COPY.

ADD archive.tar.gz /opt/app/
À retenir :

ADD n’est pas une commande générique de téléchargement.

WORKDIR

Définit le dossier de travail pour les instructions suivantes et la commande par défaut. Il est créé si nécessaire.

WORKDIR /app

ENV

Définit une variable disponible pendant les instructions suivantes et dans les conteneurs basés sur l’image.

ENV APP_MODE=production
À retenir :

Ne pas y inscrire des secrets.

ARG

Définit une valeur utilisée pendant le build, éventuellement passée via --build-arg ; elle n’est pas automatiquement une variable d’environnement d’exécution.

ARG APP_VERSION=1.0

EXPOSE

Documente le ou les ports réseau sur lesquels l’application doit écouter. Cela informe les lecteurs et certains outils, mais ne rend pas le service accessible depuis l’hôte.

EXPOSE 3000
À retenir :

Pour accéder depuis votre ordinateur : docker run -p 8080:3000 ...

USER

Définit l’utilisateur utilisé pour les instructions ou le démarrage suivants. Faire tourner une application sans droits root limite certains risques.

USER app

HEALTHCHECK

Définit un test périodique qui indique si l’application fonctionne réellement, au-delà de la simple présence de son processus.

HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
À retenir :

Le programme utilisé pour tester doit être présent dans l’image.

LABEL

Ajoute des métadonnées en paires clé=valeur, utiles pour la traçabilité.

LABEL org.opencontainers.image.title="Mon API"

VOLUME

Déclare un point de montage prévu pour des données. En pratique, la persistance se configure souvent dans Docker Compose.

VOLUME /data

SHELL

Change le programme interpréteur utilisé par les instructions en forme shell.

SHELL ["/bin/sh", "-c"]

ONBUILD

Enregistre une instruction déclenchée lorsque cette image sert ultérieurement d’image de base à un autre Dockerfile.

ONBUILD COPY . /app

.dockerignore

Fichier à côté du contexte de build qui retire des fichiers du contexte transmis au constructeur ; permet d’exclure caches, dépendances locales et données sensibles.

node_modules
.git
.env

03 · Clés de compose.yaml

L’indentation YAML construit une hiérarchie : services contient web et db ; chaque service contient ses paramètres. Les noms indiqués ci-dessous sont des clés de configuration, pas des commandes.

name

Nom logique du projet Compose, utilisé pour distinguer ses ressources de celles d’autres projets.

name: demo-web

services

Section racine contenant tous les services de l’application. Un service décrit l’image et la configuration de ses conteneurs.

services:
  web:

image

Image à utiliser : soit récupérée d’un registre, soit associée au résultat du build selon la configuration.

image: nginx:alpine

build

Indique à Compose comment fabriquer une image. Peut être un chemin court ou un objet détaillé.

build:
  context: .
  dockerfile: Dockerfile

context

Chemin des fichiers envoyés au constructeur. Le point représente le répertoire du projet Compose. Il est distinct de WORKDIR dans l’image.

context: .

dockerfile

Chemin d’un fichier de construction alternatif, interprété relativement au contexte de build.

dockerfile: docker/Dockerfile

ports

Publie un port du conteneur sur l’hôte. La syntaxe courte « 8080:3000 » se lit hôte:conteneur.

ports:
  - "8080:3000"
À retenir :

Sans ports, les conteneurs d’un même réseau peuvent souvent se joindre directement.

expose

Documente les ports internes d’un service, sans les publier sur l’hôte.

expose:
  - "3000"

volumes (service)

Monte un stockage dans le conteneur : volume nommé ou chemin hôte.

volumes:
  - db_data:/var/lib/postgresql/data

volumes (racine)

Déclare les volumes nommés gérés par le projet, réutilisés par les services.

volumes:
  db_data:

networks

Associe les services à un ou plusieurs réseaux ; les noms de service servent souvent à communiquer.

networks:
  - interne

environment

Variables transmises au processus du conteneur. Peuvent modifier les ports, le mode d’exécution ou des comportements applicatifs.

environment:
  NODE_ENV: production
À retenir :

Pour des identifiants, préférer un mécanisme de secrets.

env_file

Charge les variables d’environnement depuis un fichier texte de paires clé=valeur.

env_file:
  - .env.app
À retenir :

Éviter de committer des secrets réels dans Git.

depends_on

Contrôle les dépendances et l’ordre de création des services. Ne garantit pas que l’application dépendante soit prête sans condition de santé.

depends_on:
  db:
    condition: service_healthy

restart

Indique la stratégie de redémarrage appliquée à un conteneur.

restart: unless-stopped

healthcheck

Test périodique de santé d’un service ; permet à Compose de reconnaître l’état healthy et de conditionner des dépendances.

healthcheck:
  test: ["CMD", "pg_isready", "-U", "app"]
  interval: 10s

command

Remplace la commande par défaut de l’image au démarrage (souvent le CMD).

command: ["node", "server.js"]

entrypoint

Remplace l’exécutable d’entrée défini dans l’image pour un service.

entrypoint: ["/app/start.sh"]

profiles

Permet d’activer seulement certains services optionnels, comme des outils de débogage.

profiles: ["debug"]

secrets

Déclare et distribue à certains services des données sensibles sous forme de fichiers.

secrets:
  - db_password

build.args

Passe des paramètres à des ARG du Dockerfile lors de la construction.

build:
  args:
    APP_VERSION: "1.0"

deploy

Regroupe des options de déploiement telles que certaines limites de ressources ou réplications, selon le mode d’exécution et sa prise en charge.

deploy:
  resources:
    limits:
      memory: 512M

version (héritage)

Ancien champ de compatibilité devenu obsolète. Docker Compose moderne se base sur la spécification courante.

Ne pas ajouter version: "3" dans un nouveau compose.yaml.

04 · Les confusions fréquentes

Ces associations méritent d’être comprises avant de modifier un projet existant.

RUN ≠ CMD

RUN travaille pendant docker build et laisse un résultat dans l’image. CMD définit ce qui doit se lancer plus tard, lors de docker run.

RUN npm ci
CMD ["node", "server.js"]

CMD ≠ ENTRYPOINT

ENTRYPOINT choisit le programme principal. CMD peut fournir sa commande par défaut ou ses arguments ; ses valeurs sont plus facilement remplacées au lancement.

ENTRYPOINT ["python"]
CMD ["app.py"]

ARG ≠ ENV

ARG concerne la construction ; ENV rend une valeur disponible dans l’image et le conteneur. Aucun des deux ne doit servir de coffre-fort à mots de passe.

ARG VERSION=1.0
ENV MODE=production

EXPOSE ≠ ports

EXPOSE dans Dockerfile documente le port interne. ports dans Compose établit l’accès à travers le port de l’hôte.

EXPOSE 3000
ports: ["8080:3000"]

image ≠ build

image indique une référence d’image ; build donne une recette pour la fabriquer. Les deux peuvent apparaître ensemble, avec des règles de téléchargement et de build à connaître.

image: monapp:dev
build: .

context ≠ WORKDIR

context détermine les fichiers accessibles au build depuis l’hôte ; WORKDIR est le répertoire courant à l’intérieur de l’image et du conteneur.

context: .
WORKDIR /app

depends_on ≠ prêt

depends_on garantit une séquence de création ; pour attendre la disponibilité d’une base, associer un healthcheck et condition: service_healthy.

depends_on:
  db:
    condition: service_healthy