🐳 Dockerfile : multi-stage, cache et secrets pour des images rapides et sûres

📚 Introduction

Un Dockerfile qui « marche » est facile à écrire. Un Dockerfile qui construit vite, produit une image légère et ne fuit aucun secret, c’est un autre métier. Or c’est exactement là que se joue le confort au quotidien : un build de trois minutes au lieu de trente secondes, une image de 1,2 Go au lieu de 80 Mo, ou un token d’API qui traîne dans une couche publique — tout ça se décide dans le Dockerfile.

Cet article part du principe que les bases sont acquises (si ce n’est pas le cas, commencez par les fondamentaux de Docker) et se concentre sur les quatre techniques qui font la différence : l’ordre des couches pour le cache, le build multi-stage, les cache mounts BuildKit et les secrets de build. Toutes reposent sur des fonctionnalités stables et documentées — rien d’exotique.

🧱 L’ordre des couches n’est pas anodin

Chaque instruction d’un Dockerfile crée une couche, et Docker met ces couches en cache. Tant qu’une instruction et ses fichiers d’entrée ne changent pas, Docker réutilise la couche au lieu de la reconstruire. Mais dès qu’une couche est invalidée, toutes les suivantes le sont aussi.

D’où la règle d’or : ordonner du moins changeant au plus changeant. L’erreur classique est de copier tout le code avant d’installer les dépendances :

# ❌ à éviter : le moindre changement de code réinstalle tout
COPY . .
RUN npm ci

En copiant d’abord le manifeste de dépendances, on ne réinstalle que lorsqu’il change réellement :

# ✅ le cache de npm ci survit aux changements de code
COPY package*.json ./
RUN npm ci
COPY . .

Complément indispensable : un fichier .dockerignore. Sans lui, COPY . . embarque node_modules, .git, les fichiers d’environnement et les artefacts locaux dans le contexte de build — ce qui gonfle l’image et invalide le cache pour rien.

🔎 Comment fonctionne le cache de build Docker ?

En une phrase : Docker calcule une empreinte de chaque instruction (la commande et le contenu des fichiers qu’elle copie), et si cette empreinte a déjà été construite, il réutilise la couche existante au lieu de l’exécuter.

Concrètement, la cascade d’invalidation explique tout : si vous modifiez une ligne à l’étape 3, les étapes 1 et 2 restent en cache, mais 3, 4, 5… sont rejouées. C’est pourquoi placer les instructions lentes et stables (installation de paquets système, dépendances) en haut, et les instructions volatiles (copie du code applicatif) en bas, change radicalement le temps de build au quotidien.

🧩 Multi-stage : séparer le build du runtime

C’est la technique la plus rentable pour alléger une image. Le principe : une première étape contient tout l’outillage de compilation ; une seconde, minimale, ne reçoit que le produit fini.

# Étape de build : compilateurs, dépendances de dev, etc.
FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
# Image finale : rien que le nécessaire pour exécuter
FROM node:22-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/server.js"]

Le COPY --from=build va chercher uniquement les fichiers utiles dans l’étape précédente. L’image livrée ne contient ni le code source, ni les dépendances de développement, ni la chaîne de compilation. On passe couramment de plusieurs centaines de Mo à quelques dizaines. J’ai détaillé une application concrète de ce pattern dans le multi-stage build pour Laravel.

⚡ Cache mounts BuildKit : accélérer les dépendances

L’ordre des couches met en cache le résultat d’un npm ci ou d’un composer install — mais dès que le manifeste change, tout est retéléchargé. Les cache mounts de BuildKit résolvent ça : ils montent un cache persistant qui survit d’un build à l’autre, sans être inclus dans l’image.

# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

Ici, le cache de npm (/root/.npm) est conservé entre les builds. Même quand npm ci doit se relancer, il retrouve les paquets déjà téléchargés au lieu de tout retirer du réseau. Sur des dépendances lourdes, le gain se compte en minutes.

La directive # syntax=docker/dockerfile:1 en première ligne est obligatoire pour débloquer la syntaxe --mount. Elle active le frontend Dockerfile de BuildKit, qui est le moteur de build par défaut de Docker moderne.

🔒 Secrets de build : jamais dans une couche

Voici l’erreur la plus dangereuse. Pour récupérer une dépendance privée pendant le build, la tentation est de passer un token via ARG ou ENV :

# ❌ le token finit inscrit dans l'image, lisible via `docker history`
ARG NPM_TOKEN
RUN npm ci

Le problème : tout ce qui passe par ARG ou ENV est gravé dans les couches de l’image et ressort avec docker history. Le token est exposé à quiconque récupère l’image.

La bonne méthode, ce sont les secrets de build BuildKit. Le secret est monté le temps d’une instruction RUN, dans un fichier sous /run/secrets/, et n’est jamais persisté :

# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npmtoken \
    NPM_TOKEN="$(cat /run/secrets/npmtoken)" npm ci

Et à la construction, on fournit le secret depuis un fichier ou une variable :

docker build --secret id=npmtoken,src=./npm_token.txt .

Le secret est disponible pendant le RUN, puis disparaît. Aucune trace dans les couches, aucune fuite via docker history. En CI, on branche ce mécanisme sur le coffre à secrets du pipeline — j’en parle côté GitHub Actions.

⚠️ Quelques précautions

• Toujours un .dockerignore. Sans lui, le cache et la taille d’image partent en fumée, et des fichiers sensibles peuvent se retrouver dans le contexte de build.
• Épinglez vos images de base. node:22-alpine reste prévisible ; node:latest change sous vos pieds et casse le cache de façon imprévisible.
• Un secret n’est pas un ARG. Répétons-le : ARG/ENV pour un token est une fuite. Utilisez --mount=type=secret.
• Attention au sharing des cache mounts. Pour des gestionnaires sensibles aux accès concurrents (apt, par exemple), ajoutez sharing=locked afin d’éviter les corruptions lors de builds parallèles.

🎉 Conclusion

Un bon Dockerfile n’est pas qu’une liste d’instructions qui aboutit : c’est un artefact qu’on optimise. Ordonner les couches du stable au volatile pour exploiter le cache, séparer build et runtime en multi-stage pour alléger l’image, monter des cache mounts BuildKit pour accélérer les dépendances, et passer les secrets via --mount=type=secret pour ne rien laisser fuiter — ces quatre réflexes transforment l’expérience de build.

Aucun ne demande d’outil supplémentaire : tout est dans BuildKit, activé par défaut. Le seul prérequis, c’est la ligne # syntax=docker/dockerfile:1 en tête de fichier. À partir de là, vos images sont plus rapides à construire, plus légères à déployer et plus sûres à distribuer.

🔗 Liens utiles

• Dockerfile — référence officielle
• Build secrets — documentation Docker
• Cache mounts (RUN --mount=type=cache) — documentation Docker
• Multi-stage builds — documentation Docker