Écrivez un Dockerfile fiable pour une application web : FROM, COPY, RUN, CMD, cache, .dockerignore et multi-stage, avec des exemples Node et Nginx commentés.
| Instruction | Moment | Exemple |
|---|---|---|
| `RUN` | Construction de l’image | `RUN npm ci` |
| `CMD` | Démarrage, valeurs par défaut | `CMD ["npm", "start"]` |
| `ENTRYPOINT` | Exécutable principal | `ENTRYPOINT ["docker-entrypoint.sh"]` |
Écrit par
Un Dockerfile est une recette textuelle : une suite d’instructions qui indique à Docker comment construire une image. Pour une application web (Node, PHP ou Python), c’est le passage de « je lance une image officielle générique » à « voici mon image, avec mon code et mes dépendances ».
Ce guide détaille les instructions essentielles (FROM, COPY, RUN, CMD), le multi-stage, et les erreurs qui produisent des images lentes, lourdes ou risquées. La référence complète se trouve dans la documentation du Dockerfile.
Sans Dockerfile, vous utilisez surtout des images toutes faites (nginx, postgres). Dès que vous devez :
…vous écrivez un Dockerfile. L’image obtenue est un artefact partageable : même contenu sur votre ordinateur, en intégration continue et sur un serveur. Pour la construire :
docker build -t mon-app:dev .
L’option -t donne un nom et une étiquette (tag) à l’image. Le point final désigne le contexte de build : l’ensemble des fichiers envoyés au démon Docker. D’où l’importance du fichier .dockerignore, abordé plus bas.
Voici un exemple pédagogique pour une API Express :
FROM node:22-bookworm-slim
WORKDIR /usr/src/app
# Les manifestes d'abord, pour profiter du cache
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
# Le reste du code ensuite
COPY . .
ENV NODE_ENV=production
USER node
EXPOSE 3000
CMD ["node", "server.js"]
Choisissez une étiquette précise (22-bookworm-slim) plutôt que latest, qui change dans le temps. Les variantes slim et alpine allègent l’image ; Debian slim est souvent plus confortable quand des dépendances natives sont en jeu.
Équivalent d’un cd permanent pour les instructions suivantes. Si le dossier n’existe pas, Docker le crée.
COPY transfère des fichiers du contexte vers l’image. L’ordre compte pour le cache : copiez d’abord les manifestes de dépendances, lancez l’installation, puis copiez le reste du code. Modifier server.js ne relance alors pas npm ci.
RUN lance une commande au moment de la construction (installer des paquets, compiler). Chaque instruction crée une couche (layer) : regroupez avec && quand c’est pertinent, sans rendre la recette illisible.
ENV définit des variables d’environnement dans l’image, par exemple NODE_ENV. N’y gravez jamais de secret : une clé d’API écrite en clair reste lisible dans l’historique de l’image. USER abandonne les droits root ; les images Node officielles fournissent un utilisateur node pour cela.
EXPOSE indique le port d’écoute, mais n’ouvre rien sur l’hôte : c’est l’option -p de docker run qui publie le port.
CMD définit la commande lancée au démarrage du conteneur. Privilégiez la forme exec en JSON (["node", "server.js"]) : les signaux d’arrêt sont mieux transmis au processus.
Si votre conteneur s’arrête aussitôt, regardez CMD : quand le processus principal se termine, le conteneur aussi. Une API doit donc rester au premier plan.
À la racine du projet, ce fichier exclut des éléments du contexte :
node_modules
.git
.env
npm-debug.log
dist
coverage
Dockerfile*
README.md
Sans lui, vous envoyez le node_modules de votre machine (lent, parfois incompatible d’un système à l’autre) et vous risquez de copier un .env local dans l’image. C’est mauvais pour les performances et pour la sécurité.
Les applications web modernes compilent souvent un artefact (JavaScript, CSS). La construction multi-stage sépare les outils de build de l’image finale. La documentation sur le multi-stage présente le principe en détail.
# Étape de build : tous les outils nécessaires
FROM node:22-bookworm AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
# Étape finale : uniquement ce qui sert à l'exécution
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]
Les avantages sont concrets : pas de compilateurs inutiles en production, une image finale plus petite et une surface d’attaque réduite. Pour un front purement statique, l’étape finale peut même être une image Nginx qui sert le dossier compilé.
FROM node:22-bookworm AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:1.27-alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
Le fichier nginx.conf gère la règle try_files nécessaire au routage d’une application monopage. Le résultat : une image légère, un serveur éprouvé pour le statique et un build reproductible en CI. Retenez la règle : l’environnement qui construit n’est pas forcément celui qui exécute. Node compile, Nginx sert.
L’ordre des instructions détermine ce que Docker peut réutiliser :
FROM et WORKDIR ;package.json et du verrou de dépendances ;RUN npm ci ;RUN npm run build, si nécessaire ;USER et CMD.Modifier package-lock.json recalcule les dépendances ; modifier un seul fichier de routes réutilise la couche d’installation. Sur une intégration continue, ce détail réduit sensiblement les temps de construction.
docker build -t mon-app:debug .
Si l’échec survient pendant RUN npm ci, lisez d’abord les journaux de npm : registre inaccessible, dépendances incompatibles, bibliothèques système manquantes (certains modules natifs demandent des outils de compilation). Vous pouvez aussi construire jusqu’à une étape précise, puis y ouvrir un shell :
docker build --target build -t mon-app:build .
docker run --rm -it mon-app:build /bin/bash
npm install sans lockfile laisse flotter les versions. Préférez npm ci avec un package-lock.json versionné.ENV API_KEY=… ou un COPY .env reste récupérable dans l’historique. Fournissez les secrets à l’exécution.latest sans le documenter : aujourd’hui l’image fonctionne, demain l’étiquette a bougé. Épinglez une version et mettez à jour volontairement.mon-app:1.4.2) ;/health et, si besoin, une instruction HEALTHCHECK ;Pour assembler cette image avec une base de données et un proxy, enchaînez avec Docker Compose : orchestrer une stack locale. Les bonnes pratiques Docker pour projets web complètent cette liste. Si vous préférez déléguer la mise en production, l’agence Yunt peut cadrer le projet avec vous.
Un Dockerfile décrit comment fabriquer une image web fiable : base claire, dépendances en cache, code copié au bon moment, processus non-root et commande de démarrage explicite. Le multi-stage sépare le build du runtime pour obtenir des images plus saines.
Écrivez une recette simple pour votre API, ajoutez un .dockerignore, étiquetez l’image et lancez-la avec un mappage de port. Quand c’est stable, passez à Compose. Pour transformer ces gestes en compétence durable, découvrez Academy Yunt.
Le Dockerfile explique comment construire l’image d’une application. Compose décrit comment lancer plusieurs services ensemble, en s’appuyant sur ces images.
Ce n’est pas obligatoire. Alpine est compacte mais repose sur la bibliothèque musl, que certains modules natifs supportent mal. Debian slim est un excellent choix par défaut pour Node.
Préférez COPY. ADD ajoute des comportements supplémentaires (téléchargement d’URL, extraction d’archives) qui surprennent souvent.
Généralement à la racine de chaque application ou package, avec un contexte de build ciblé pour n’envoyer que les fichiers utiles.
La forme exec JSON transmet mieux les signaux et évite un shell intermédiaire. Utilisez la forme shell seulement si vous avez besoin de l’expansion de variables par le shell.