Guide 03 / 3
Dockerfile & compose.yaml
Comprendre chaque instruction et ses conséquences sur le build ou l’exécution.
Expliquer le cycle Dockerfile → image → conteneur et configurer des services Compose.
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
FROM python:3.13-slim
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.
Exemple
RUN pip install --no-cache-dir -r requirements.txt
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.
Exemple
CMD ["python", "app.py"]
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.
Exemple
ENTRYPOINT ["python", "app.py"]
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.
Exemple
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.
Exemple
ADD archive.tar.gz /opt/app/
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.
Exemple
WORKDIR /app
ENV
Définit une variable disponible pendant les instructions suivantes et dans les conteneurs basés sur l’image.
Exemple
ENV APP_MODE=production
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.
Exemple
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.
Exemple
EXPOSE 3000
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.
Exemple
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.
Exemple
HEALTHCHECK CMD wget -q -O - http://localhost:3000/health || exit 1
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é.
Exemple
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.
Exemple
VOLUME /data
SHELL
Change le programme interpréteur utilisé par les instructions en forme shell.
Exemple
SHELL ["/bin/sh", "-c"]
ONBUILD
Enregistre une instruction déclenchée lorsque cette image sert ultérieurement d’image de base à un autre Dockerfile.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
services:
web:
image
Image à utiliser : soit récupérée d’un registre, soit associée au résultat du build selon la configuration.
Exemple
image: nginx:alpine
build
Indique à Compose comment fabriquer une image. Peut être un chemin court ou un objet détaillé.
Exemple
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.
Exemple
context: .
dockerfile
Chemin d’un fichier de construction alternatif, interprété relativement au contexte de build.
Exemple
dockerfile: docker/Dockerfile
ports
Publie un port du conteneur sur l’hôte. La syntaxe courte « 8080:3000 » se lit hôte:conteneur.
Exemple
ports:
- "8080:3000"
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.
Exemple
expose:
- "3000"
volumes (service)
Monte un stockage dans le conteneur : volume nommé ou chemin hôte.
Exemple
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.
Exemple
volumes:
db_data:
networks
Associe les services à un ou plusieurs réseaux ; les noms de service servent souvent à communiquer.
Exemple
networks:
- interne
environment
Variables transmises au processus du conteneur. Peuvent modifier les ports, le mode d’exécution ou des comportements applicatifs.
Exemple
environment:
NODE_ENV: production
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.
Exemple
env_file:
- .env.app
É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é.
Exemple
depends_on:
db:
condition: service_healthy
restart
Indique la stratégie de redémarrage appliquée à un conteneur.
Exemple
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.
Exemple
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).
Exemple
command: ["node", "server.js"]
entrypoint
Remplace l’exécutable d’entrée défini dans l’image pour un service.
Exemple
entrypoint: ["/app/start.sh"]
profiles
Permet d’activer seulement certains services optionnels, comme des outils de débogage.
Exemple
profiles: ["debug"]
secrets
Déclare et distribue à certains services des données sensibles sous forme de fichiers.
Exemple
secrets:
- db_password
build.args
Passe des paramètres à des ARG du Dockerfile lors de la construction.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
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.
Exemple
depends_on:
db:
condition: service_healthy