Claude Code et Docker : Compose, volumes, reseaux et builds CI

Definir ce que Claude Code doit prendre en charge

Si vous demandez simplement a Claude Code de “dockeriser l’application”, il peut produire un Dockerfile qui demarre une fois mais reste difficile a relire. Docker sert a figer un environnement d’execution : une image est le modele, un conteneur est l’instance lancee, un volume conserve les donnees hors du conteneur, et un reseau permet aux services de se joindre par nom.

Dans un projet serieux, le Dockerfile n’est pas toute l’histoire. Il faut relire ensemble Dockerfile, docker-compose.yml, .dockerignore, variables d’environnement, health checks et build CI. Gardez les references officielles ouvertes : Dockerfile reference, Compose file reference, Docker build best practices, Docker Build GitHub Actions et Claude Code overview.

Pour le reste de la chaine, voyez aussi Claude Code CI/CD setup, approval and sandbox guide et security best practices.

Cas d’usage concrets

L’integration Docker a de la valeur quand elle retire de l’incertitude. Nommez le probleme avant de demander des changements.

Cas d’usage	Ce que Docker standardise	Ce que demander a Claude Code
Arrivee d’un nouveau dev	Node.js, PostgreSQL, Redis, ports, commandes	Faire demarrer la stack avec docker compose up
Debug proche de la production	Variables, noms de services, health checks, ordre de demarrage	Lister les differences local/production
Verification de PR	Dockerfile, lockfile, cache, logs CI	Ajouter un workflow qui build l’image
Formation et handoff	Commandes, echecs, recuperation	Documenter les regles dans CLAUDE.md et README

Pour un SaaS ou un site monetise, c’est directement lie au revenu. Checkout, formulaires de leads, back-office et pages produits ne doivent pas dependre d’un seul laptop. Les independants peuvent commencer avec ClaudeCodeLab products. Les equipes qui veulent adapter permissions, CI et criteres de revue a leur depot peuvent passer par Claude Code training and consultation.

Prompt avec garde-fous

Le premier prompt doit indiquer le contexte, les fichiers attendus, les interdits et la verification. Cela evite une configuration plausible mais risquee.

Dockerize this Node.js + TypeScript API.

Context:
- pnpm is the package manager.
- The app listens on port 3000.
- GET /health returns 200.
- Local development needs PostgreSQL 16 and Redis 7.

Create:
- Production multi-stage Dockerfile
- docker-compose.yml for local development
- .dockerignore
- Docker-related package.json scripts
- GitHub Actions workflow that only verifies docker build

Constraints:
- Do not run the production container as root.
- Do not COPY .env files or secrets into the image.
- Explain the volume and network choices for the README.
- Include verification commands and how to inspect failures.

Un multi-stage build separe l’environnement de compilation de l’environnement d’execution. Les outils TypeScript restent dans le stage de build, tandis que l’image finale ne contient que les dependances de production et dist.

Dockerfile copiable

L’exemple suppose une API Node.js qui compile src/index.ts vers dist/index.js. Le stage dev sert au local avec Compose, le stage runner a la production.

# syntax=docker/dockerfile:1

FROM node:22-bookworm-slim AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
WORKDIR /app
RUN corepack enable

FROM base AS dev
ENV NODE_ENV=development
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
CMD ["pnpm", "dev"]

FROM base AS deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

FROM base AS prod-deps
ENV NODE_ENV=production
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod && pnpm store prune

FROM base AS runner
ENV NODE_ENV=production
RUN groupadd --system --gid 1001 nodejs \
  && useradd --system --uid 1001 --gid nodejs appuser
COPY --from=prod-deps --chown=appuser:nodejs /app/node_modules ./node_modules
COPY --from=build --chown=appuser:nodejs /app/dist ./dist
COPY --chown=appuser:nodejs package.json ./
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 CMD node -e "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
CMD ["node", "dist/index.js"]

Demandez a Claude Code de verifier trois points : les secrets peuvent-ils entrer dans l’image, l’ordre des COPY preserve-t-il le cache, et l’image runtime exclut-elle bien les devDependencies.

Compose : volumes et reseaux

Compose lance plusieurs conteneurs ensemble. Ici API, PostgreSQL et Redis partagent un reseau ; l’API utilise les noms postgres et redis. Les volumes gardent l’etat hors des conteneurs jetables. pgdata conserve la base, et api_node_modules empeche les modules du host d’ecraser ceux du conteneur Linux.

services:
  api:
    build:
      context: .
      target: dev
    command: pnpm dev
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:app@postgres:5432/app
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - .:/app
      - api_node_modules:/app/node_modules
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 10s
      timeout: 3s
      retries: 5

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:
  api_node_modules:

depends_on regle l’ordre de lancement, pas la disponibilite reelle d’une base. Combinez-le avec healthcheck et condition: service_healthy.

Garder les secrets hors du build

Commencez par .dockerignore. Il reduit le contexte de build et evite de copier .env.

.git
node_modules
dist
coverage
.env
.env.*
!.env.example
npm-debug.log*
pnpm-debug.log*
Dockerfile*
docker-compose*.yml

Ajoutez ensuite des scripts partages dans package.json.

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/index.js",
    "docker:dev": "docker compose up --build",
    "docker:check": "bash scripts/docker-check.sh"
  },
  "dependencies": {
    "@fastify/redis": "latest",
    "fastify": "latest",
    "pg": "latest"
  },
  "devDependencies": {
    "tsx": "latest",
    "typescript": "latest"
  }
}

Script de verification repetable

Les verifications manuelles s’oublient vite. Gardez le flux dans scripts/docker-check.sh.

#!/usr/bin/env bash
set -euo pipefail

docker compose build api
docker compose up -d postgres redis api

cleanup() {
  docker compose down
}
trap cleanup EXIT

for attempt in {1..30}; do
  if curl -fsS http://127.0.0.1:3000/health >/dev/null; then
    echo "healthcheck ok"
    exit 0
  fi
  echo "waiting for api... ${attempt}/30"
  sleep 2
done

docker compose logs api
exit 1

Le script build l’image, lance la stack, attend /health et affiche les logs si l’API ne devient jamais saine.

CI : build d’abord, push ensuite

Au premier PR, verifiez seulement que l’image se construit. Publication, signature, scan de vulnerabilites et SBOM peuvent venir apres.

name: docker-build

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v7
        with:
          context: .
          target: runner
          push: false
          tags: claude-code-docker-sample:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Claude Code doit expliquer si ce workflow pousse une image, si les permissions sont excessives et comment il se comporte sans cache.

Echecs frequents

Le pire incident est de copier .env dans l’image. Une fois un secret pousse dans un registry, le nettoyage coute cher. Relisez .dockerignore, secrets CI et logs de build ensemble.

Autre piege : monter node_modules du host dans un conteneur Linux. Les modules natifs peuvent differer entre macOS, Windows et Linux. Un volume nomme isole ce risque.

Troisieme probleme : l’API demarre avant que PostgreSQL accepte les connexions. Utilisez health checks et retry applicatif.

Enfin, evitez root en production. Cela marche en demo, mais augmente le rayon d’impact d’une faille. Demandez a Claude Code de pointer les lignes Dockerfile qui prouvent le non-root.

Flux de travail sur

L’ordre conseille est : inspecter le depot, lister les dependances runtime, ecrire .dockerignore, creer Compose local, creer le Dockerfile production, ajouter le script de verification, puis CI. Apres chaque etape, lisez git diff et demandez a Claude Code quatre elements : fichiers modifies, raison, commande de verification, risque restant.

Ce flux fonctionne bien avec session handoff template. Docker doit devenir une pratique relisible d’equipe, pas un fichier genere une seule fois.

Resultat observe

En pratique, les petites taches donnent de meilleurs resultats avec Claude Code. .dockerignore, puis Compose, puis health checks, puis CI : cet ordre produit des diffs plus faciles a relire. Le volume api_node_modules et l’attente service_healthy reduisent les deux problemes les plus courants : “ca marche seulement chez moi” et “l’API demarre mais ne se connecte pas a Postgres”.