Dockeriser une application avec Claude Code : Dockerfile, Compose & déploiement (Guide 2026)

Dockeriser une application avec Claude Code : du code au conteneur en une session

« Ça marche sur ma machine. » Cette phrase, tout développeur l'a prononcée — juste avant de découvrir que l'application refuse de démarrer sur le serveur, ou sur l'ordinateur d'un collègue. Docker existe précisément pour tuer ce problème : il emballe votre application, ses dépendances et son environnement dans un conteneur portable qui tourne à l'identique partout. Le hic ? Écrire un Dockerfile propre, configurer docker-compose et optimiser l'image demandent des connaissances qu'on n'a pas toujours sous la main.

Bonne nouvelle : conteneuriser une application est exactement le genre de tâche que Claude Code accomplit en quelques prompts bien cadrés. Dans ce guide 2026, on part d'une application classique et on la transforme, étape par étape, en une image Docker légère et prête pour la production — en pilotant l'agent plutôt qu'en mémorisant chaque instruction Docker.

Sommaire

Docker en 2 minutes : les concepts pour garder le contrôle {#docker-concepts}

Avant de lancer l'agent, fixons le vocabulaire — c'est ce qui vous permettra de relire et valider ce que Claude Code produit, au lieu de copier-coller à l'aveugle.

Retenez cette chaîne mentale : *Dockerfile → image → conteneur*. Vous écrivez une recette (Dockerfile), vous la compilez en un modèle (image), vous en lancez des instances (conteneurs). Tout le reste n'est que détail de configuration.

Préparer le projet avec Claude Code {#preparer-projet}

Ouvrez votre projet dans le terminal et lancez Claude Code à la racine. Première bonne pratique : laissez l'agent analyser votre stack avant de générer quoi que ce soit. Un prompt d'ouverture efficace :

« Analyse ce projet : quel langage, quel framework, quelles dépendances, quel port d'écoute et quelle commande de démarrage ? Je veux ensuite le conteneuriser avec Docker. »

Claude Code lit votre package.json, votre requirements.txt ou votre go.mod, repère le point d'entrée et vous restitue un résumé. Cette étape évite les hypothèses erronées : un Dockerfile qui expose le mauvais port ou lance la mauvaise commande ne sert à rien.

Si vous débutez complètement avec l'agent, notre guide Claude Code pour débutants explique comment l'installer et cadrer vos premiers prompts. Et si votre application n'existe pas encore, commencez par la construire — par exemple avec notre tutoriel créer une API REST avec Claude Code — avant de la conteneuriser.

Étape 1 : générer un premier Dockerfile {#etape-1-dockerfile}

Une fois la stack identifiée, demandez un Dockerfile simple et fonctionnel :

« Génère un Dockerfile pour cette application Node.js. Utilise une image de base officielle, installe les dépendances, copie le code, expose le port 3000 et lance `npm start`. Ajoute aussi un fichier .dockerignore adapté. »

Claude Code produit alors quelque chose comme :

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Notez le réflexe important : copier d'abord package*.json et installer les dépendances avant de copier le reste du code. Grâce au cache de couches de Docker, tant que vos dépendances ne changent pas, cette étape n'est pas ré-exécutée à chaque build — un gain de temps considérable. Si Claude Code ne le fait pas spontanément, demandez-lui : « réorganise le Dockerfile pour tirer parti du cache de couches. »

Le .dockerignore généré exclut ce qui n'a rien à faire dans l'image :

node_modules
npm-debug.log
.git
.env
Dockerfile
.dockerignore

Étape 2 : optimiser avec un build multi-étapes {#etape-2-multistage}

Le premier Dockerfile fonctionne, mais il embarque souvent des outils de build inutiles en production. C'est là qu'intervient le build multi-étapes — la technique qui fait la différence entre une image de 900 Mo et une image de 90 Mo.

« Transforme ce Dockerfile en build multi-étapes : une étape pour installer et compiler, une étape finale de production qui ne contient que le code compilé et les dépendances runtime. Objectif : l'image la plus légère possible. »

Le résultat sépare clairement les deux phases :

# Étape 1 : build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Étape 2 : production
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

L'image finale ne contient plus les dépendances de développement ni les fichiers sources bruts, seulement le code compilé et le nécessaire pour l'exécuter. Demandez à Claude Code de mesurer le gain : « quelle sera la taille approximative de l'image avant et après cette optimisation ? » Il vous donnera un ordre de grandeur et pourra suggérer d'autres leviers (image distroless, suppression des caches npm, etc.).

Cette recherche de sobriété — livrer uniquement le strict nécessaire — rejoint les principes que nous détaillons dans notre article sur le déploiement d'une application avec Claude Code : une image légère se déploie plus vite et coûte moins cher à héberger.

Étape 3 : orchestrer plusieurs services avec docker-compose {#etape-3-compose}

Une vraie application dépasse rarement un seul conteneur : il y a l'API, la base de données, parfois un cache Redis ou un frontend. Plutôt que de lancer chaque conteneur à la main, on décrit l'ensemble dans un fichier docker-compose.yml.

« Génère un docker-compose.yml qui lance trois services : mon API Node (build depuis le Dockerfile local, port 3000), une base PostgreSQL 16 avec un volume persistant, et Redis. Configure le réseau interne, les variables d'environnement et fais dépendre l'API du démarrage de la base. »

Claude Code produit un fichier structuré et commenté :

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app
      REDIS_URL: redis://cache:6379
    depends_on:
      - db
      - cache
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
  cache:
    image: redis:7-alpine

volumes:
  pgdata:

Remarquez que l'API référence la base par son nom de service (db), pas par une adresse IP : docker-compose crée un réseau interne où chaque service est joignable par son nom. Une seule commande — docker compose up — démarre tout l'ensemble. Si votre base tourne plutôt sur une plateforme managée, notre guide créer un backend full-stack avec Supabase et Claude Code montre l'approche complémentaire, sans conteneur à gérer soi-même.

Étape 4 : construire, lancer et déboguer {#etape-4-build}

Place à l'exécution. Demandez à Claude Code les commandes exactes pour votre cas :

« Donne-moi les commandes pour construire l'image, lancer le conteneur, voir les logs et l'arrêter proprement. »

Vous obtenez le trio de base :

docker build -t mon-app .
docker run -p 3000:3000 --env-file .env mon-app
docker compose up --build

Et c'est ici que Claude Code devient précieux : le débogage. Un build Docker qui échoue crache souvent une erreur cryptique. Copiez-la simplement dans le chat :

« Le build échoue avec cette erreur : [collez le message]. Qu'est-ce qui cloche et comment le corriger ? »

L'agent identifie les causes classiques — un fichier manquant à cause du .dockerignore, une variable d'environnement non transmise, un port déjà occupé, une commande de démarrage incorrecte — et propose un correctif ciblé. C'est le même réflexe conversationnel que pour n'importe quelle erreur de code : vous décrivez le symptôme, l'agent diagnostique.

Étape 5 : préparer le déploiement en production {#etape-5-deploy}

Votre image tourne en local ? Elle tournera à l'identique en production — c'est toute la promesse de Docker. Reste à la publier et à la lancer sur un serveur.

« Prépare le déploiement : pousse l'image sur GitHub Container Registry, écris un docker-compose de production avec un reverse proxy Nginx et un certificat HTTPS via Let's Encrypt, et documente les étapes pour un VPS Ubuntu. »

Claude Code peut aussi générer le workflow d'intégration continue qui construit et publie l'image à chaque push. Pour aller plus loin sur cette automatisation, notre article Claude Code et les pipelines DevOps CI/CD détaille comment brancher tests, build d'image et déploiement dans une chaîne entièrement pilotée par l'agent.

L'un des grands intérêts du conteneur, c'est la souveraineté : vous n'êtes plus prisonnier d'une plateforme. Si l'auto-hébergement et le contrôle total de votre infrastructure IA vous intéressent, la formation OpenClaw sur les agents IA auto-hébergés explore en profondeur comment déployer et opérer ses propres services sans dépendre d'un fournisseur cloud — une démarche parfaitement complémentaire à la conteneurisation. Et si votre application conteneurisée consomme des données externes via des microservices, observer une API bien conçue comme ImmoAPI — endpoints documentés, pagination, réponses JSON propres — donne un bon modèle de ce à quoi doit ressembler un service prêt pour la production.

**Vous voulez déléguer toute la chaîne technique — du Dockerfile au conteneur en production — plutôt que de bloquer sur chaque erreur de build ?** Découvrez [comment vous faire remplacer par l'IA](https://go.saas-ia.io/se-faire-remplacer-par-lia) sur la partie infrastructure et déploiement, et gardez votre énergie pour la conception de votre produit.

Bonnes pratiques et pièges à éviter {#bonnes-pratiques}

Quelques réflexes à demander systématiquement à Claude Code :

Le fil conducteur reste le même que pour tout travail avec l'agent : vous ne subissez plus la complexité de Docker, vous la pilotez. Vous décrivez l'objectif, vous relisez la proposition, vous validez ou vous corrigez.

Docker et Claude Code en vidéo {#video}

Rien ne vaut une démonstration pour visualiser l'enchaînement complet — de l'application locale au conteneur qui tourne. Cette vidéo montre comment piloter Claude Code pour construire une application de bout en bout, une méthode directement transposable à la conteneurisation décrite ici :

Conclusion : vos applications enfin portables

Docker n'est plus une compétence réservée aux experts en infrastructure. En pilotant Claude Code étape par étape — analyser la stack, générer un Dockerfile, l'optimiser en multi-étapes, orchestrer les services avec docker-compose, déboguer les erreurs et préparer le déploiement — vous transformez n'importe quelle application en un conteneur léger, portable et reproductible, en une seule session.

Le vrai changement de posture : vous ne mémorisez plus des dizaines d'instructions Docker, vous décrivez, relisez et validez. La conteneurisation devient une conversation. Ouvrez votre projet, lancez Claude Code, et donnez-lui son premier objectif : « conteneurise cette application avec Docker ». Votre première image portable est à quelques prompts.

FAQ : conteneuriser une application avec Claude Code {#faq}