Guide pratique Claude Code et Docker Compose : App locale, Postgres, Redis et Worker

Docker Compose sert de plan de travail local pour lancer ensemble une application, PostgreSQL, Redis et un worker. La documentation Docker Compose le décrit comme un outil pour définir et exécuter des applications multi-conteneurs, avec services, réseaux et volumes dans un seul fichier YAML.

C’est précisément pour cela qu’il fonctionne bien avec Claude Code. Au lieu de demander vaguement “prépare un environnement Docker”, donnez-lui des fichiers concrets à lire : compose.yaml, Dockerfile, .env.example et Makefile. Le résultat devient vérifiable, reproductible et plus facile à transmettre à l’équipe.

Quand Masa a testé ce modèle sur une petite application Next.js avec un worker de queue, le gain n’est pas venu d’un prompt magique. Il est venu des détails : attente de Postgres, persistance Redis, protection de node_modules, commandes migration/test alignées avec CI.

Ce guide propose une base copiable app + PostgreSQL + Redis + worker. Compose est excellent pour le développement local, les tests d’intégration et l’onboarding. Pour la production, il faut une revue séparée : orchestration, secrets, monitoring, sauvegardes, sécurité et coût.

Architecture

flowchart LR
  Dev["Developer"] --> App["app: web server"]
  App --> Pg["postgres: database"]
  App --> Redis["redis: cache and queue"]
  Worker["worker: background jobs"] --> Pg
  Worker --> Redis
  App --> Volume["named volume: node_modules"]
  Pg --> PgVol["named volume: postgres_data"]
  Redis --> RedisVol["named volume: redis_data"]

app sert l’application web. worker traite les tâches asynchrones : emails, webhooks, images, jobs de queue. postgres et redis ont des healthchecks afin de vérifier que le service est vraiment prêt, pas seulement que le conteneur a démarré.

Pour la syntaxe officielle, gardez sous la main la Compose file reference et la services reference. Demander à Claude Code de s’appuyer sur ces références évite beaucoup d’exemples obsolètes.

Où Compose est utile

Usage	Pourquoi Compose convient	Point de vigilance
Développement local	Un seul ordre démarre app, DB, Redis et worker	Les mounts ne se comportent pas pareil selon l’OS
Tests d’intégration	DB et Redis de test peuvent être créés à la demande	Ports et cache doivent être explicites en CI
Onboarding	.env.example et make setup fixent le parcours	Ne jamais mettre de vrais secrets dans l’exemple
Production	Possible pour de petits outils internes	Revue sécurité, reprise, supervision, coût obligatoire

La limite production est essentielle. Compose crée un atelier identique sur les machines des développeurs. Pour produire, comparez avec ECS, Kubernetes, Cloud Run, Fly.io, Render ou votre plateforme interne. Demandez à Claude Code de lister les contraintes de migration plutôt que de transformer automatiquement le fichier local en plan de déploiement.

compose.yaml à copier

L’exemple suppose un projet Node.js ou Next.js. Remplacez npm run dev, npm run worker:dev et les scripts de migration par ceux de votre package.json.

# compose.yaml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev
    command: npm run dev -- --hostname 0.0.0.0
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?schema=public
      REDIS_URL: redis://redis:6379
    volumes:
      - .:/workspace
      - node_modules:/workspace/node_modules
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 20s

  worker:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev
    command: npm run worker:dev
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?schema=public
      REDIS_URL: redis://redis:6379
    volumes:
      - .:/workspace
      - node_modules:/workspace/node_modules
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    env_file:
      - .env
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/postgres/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  node_modules:
  postgres_data:
  redis_data:

Trois détails comptent. Dans le réseau Compose, les services se joignent par nom : postgres:5432 et redis:6379, pas localhost. node_modules est un named volume pour que le bind mount du code ne remplace pas les dépendances installées dans le conteneur. Les deux signes dollar dans le healthcheck Postgres gardent la variable pour le shell du conteneur.

Dockerfile

Un seul Dockerfile avec plusieurs stages reste souvent plus simple qu’une collection de fichiers séparés.

# Dockerfile
# syntax=docker/dockerfile:1

FROM node:22-alpine AS base
WORKDIR /workspace
ENV NEXT_TELEMETRY_DISABLED=1
COPY package*.json ./
RUN npm ci

FROM base AS dev
EXPOSE 3000
CMD ["npm", "run", "dev", "--", "--hostname", "0.0.0.0"]

FROM base AS build
COPY . .
RUN npm run build

FROM node:22-alpine AS production
WORKDIR /workspace
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /workspace/.next ./.next
COPY --from=build /workspace/public ./public
USER node
EXPOSE 3000
CMD ["npm", "start"]

Le stage dev ne copie pas les sources, car Compose les monte depuis l’hôte. Le stage build copie tout le dépôt pour que CI et l’image de production puissent construire sans dépendre de votre machine.

.env.example

Commitez .env.example, jamais .env. Le fichier d’exemple doit montrer la forme des variables sans exposer de vrais identifiants.

# .env.example
POSTGRES_USER=app
POSTGRES_PASSWORD=app_password
POSTGRES_DB=app_development

DATABASE_URL=postgresql://app:app_password@postgres:5432/app_development?schema=public
REDIS_URL=redis://redis:6379
NODE_ENV=development
PORT=3000

env_file transmet des variables aux conteneurs. L’interpolation du fichier Compose lit aussi le .env du projet. Gardez cette différence en tête et évitez les valeurs contradictoires.

Makefile et commandes ponctuelles

Un petit Makefile rend les opérations quotidiennes moins ambiguës. Si votre équipe n’utilise pas make, mettez les mêmes commandes dans les scripts package.json.

COMPOSE = docker compose --env-file .env -f compose.yaml

.PHONY: setup up up-d down restart logs ps app-shell db-shell redis-cli migrate seed test lint clean

setup:
	cp .env.example .env
	$(COMPOSE) build

up:
	$(COMPOSE) up --build

up-d:
	$(COMPOSE) up -d --build

down:
	$(COMPOSE) down

restart:
	$(COMPOSE) restart app worker

logs:
	$(COMPOSE) logs -f app worker postgres redis

ps:
	$(COMPOSE) ps

app-shell:
	$(COMPOSE) exec app sh

db-shell:
	$(COMPOSE) exec postgres psql -U app -d app_development

redis-cli:
	$(COMPOSE) exec redis redis-cli

migrate:
	$(COMPOSE) run --rm app npm run db:migrate

seed:
	$(COMPOSE) run --rm app npm run db:seed

test:
	$(COMPOSE) run --rm app npm test

lint:
	$(COMPOSE) run --rm app npm run lint

clean:
	$(COMPOSE) down --volumes --remove-orphans

exec sert à agir dans un conteneur déjà lancé. run --rm sert aux commandes ponctuelles : lint, test, migration, seed. Cette distinction rapproche le local de CI.

Prompt de revue pour Claude Code

La page Claude Code common workflows recommande de découper le travail quotidien en tâches ciblées : comprendre, modifier, tester, relire. Appliquez le même principe à Compose.

Relis la configuration Docker Compose de ce dépôt.

Fichiers:
- compose.yaml
- Dockerfile
- .env.example
- package.json
- workflows CI s'ils existent

Vérifie:
1. app + postgres + redis + worker fonctionnent en local
2. healthchecks et depends_on sont utilisés correctement
3. named volumes et bind mounts sont sûrs
4. .env.example ne contient aucun secret réel
5. les commandes migrate, seed, test et lint existent
6. risques CI: ports, cache, permissions, attente des services
7. points à revoir avant une utilisation en production

Contraintes:
- respecter le framework et le package manager existants
- garder les gros refactors sous forme de proposition
- si tu modifies un fichier, expliquer la raison et la commande de vérification

Placez ce prompt près de CLAUDE.md pour répéter le même standard. À lire aussi : le guide Dev Container et le guide CI/CD.

Cas d’usage pratiques

Premier cas : l’onboarding du premier jour. Si un nouveau membre copie .env.example puis lance make up, l’application, la DB, Redis et le worker sont prêts sans installation manuelle de chaque service.

Deuxième cas : tester les queues en local. Emails, images, webhooks de paiement et notifications vivent souvent dans un worker. Le mettre dans Compose évite de simuler tout dans le serveur web.

Troisième cas : stabiliser les tests d’intégration. Beaucoup de bugs passent avec un raccourci SQLite et échouent sur Postgres. Compose permet de tester plus près de la base réelle.

Quatrième cas : revue d’infrastructure avec Claude Code. Les erreurs localhost, volumes obsolètes, healthchecks absents et secrets dans les exemples passent facilement inaperçus. Un prompt réutilisable transforme cela en checklist.

Pièges fréquents

Le piège le plus courant est de connecter l’app à localhost depuis le conteneur. Dans Compose, les noms de services sont les noms DNS. Utilisez postgres et redis.

Autre piège : croire que depends_on suffit. condition: service_healthy aide, mais l’app doit encore gérer les retries, et le worker ne doit pas lancer de tâches critiques avant les migrations.

Les named volumes anciens créent aussi des faux diagnostics. Si le schéma change mais que postgres_data reste, votre état local n’est plus celui du dépôt. make clean recrée une base propre, mais supprime les données locales.

Ne mettez pas de vraies API keys dans .env.example. Utilisez des valeurs comme app_password ou replace_me, et gardez les secrets réels dans Docker secrets, un secret manager cloud ou les secrets CI.

Enfin, ne prenez pas le fichier Compose local comme plan de production sans revue. Production signifie TLS, exposition réseau, sauvegarde DB, persistance Redis, monitoring, scan de vulnérabilités, provenance des images, permissions et coût.

Formations et templates ClaudeCodeLab

Pour adapter cette base à votre dépôt, commencez par les produits et templates ClaudeCodeLab afin de standardiser CLAUDE.md, les prompts de revue et les runbooks. Si le sujet coûteux est le déploiement en équipe, Docker Desktop, CI/CD, les permissions ou la limite entre Compose et l’orchestration de production, utilisez la page training and consultation.

Références officielles : Docker Compose, Compose file reference, services reference et Claude Code common workflows.

Après avoir testé le contenu de cet article, le projet de Masa démarrait app, Postgres, Redis et worker avec make up, et les healthchecks réduisaient la course où l’application démarre avant la base. Le point fragile restait les vieux named volumes : ils peuvent faire croire qu’une migration est cassée ou corrigée à tort. Conclusion pratique : Compose est une excellente base locale, mais la production mérite une revue séparée de sécurité, d’exploitation, de reprise et de coût.