Docker Compose pour un développement local proche de la production : guide pratique

Introduction

Un environnement local « proche de la production » paie rapidement ses dividendes. Lorsque votre application, votre base de données, votre cache et votre proxy s'exécutent ensemble via Docker Compose avec des paramètres réalistes, vous dévoilez plus tôt les problèmes d'intégration, vous déboguez plus vite et vous réduisez les surprises au moment de livrer. Ce guide montre étape par étape comment bâtir ce setup avec des services, des Docker networks, des Docker volumes, des fichiers d'environnement, des Docker health checks, et un workflow de débogage concret.

Vue d'ensemble du workflow

Adoptez une boucle simple qui reflète la manière dont un logiciel est livré :

Planifier

Listez les services et leurs interactions (ports, protocoles, variables d'environnement).
Décidez des réseaux, des volumes et des critères de santé pour chaque service.

Construire

Écrivez des Dockerfile proches de la production (images petites, utilisateurs non-root, versions épinglées).
Utilisez docker build ou laissez Compose builder à partir de votre Dockerfile.

Lancer

Démarrez la pile avec docker compose up -d.
Attendez que les health checks passent en healthy.

Tester

Envoyez le trafic via le point d'entrée public (par exemple, Nginx sur le port 80).
Validez readiness, liveness et les cas d'usage essentiels.

Itérer

Modifiez la configuration ou le code, reconstruisez et relancez.

Ce séquencement garde les changements compréhensibles et limite le rework.

Conception Compose

Ci-dessous, un docker-compose.yml pragmatique pour une petite pile web : une app Node.js, Postgres, Redis et Nginx en proxy frontal. Il utilise deux réseaux (frontend et backend), des volumes nommés pour les données, des fichiers d'environnement pour les réglages, et des health checks avec un ordre de démarrage explicite.

version: '3.9'

services:
  web:
    build:
      context: ./web
    image: local/web: dev
    ports:
      - '8080:3000'
    env_file:
      - ./env/web.env
    environment:
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ['CMD-SHELL', 'wget -qO- http://localhost:3000/health || exit 1']
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 15s
    volumes:
      - ./web:/app: cached
      - web-node-modules:/app/node_modules
    networks:
      - frontend
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U app -d appdb']
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

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

  nginx:
    image: nginx:1.25-alpine
    depends_on:
      web:
        condition: service_healthy
    ports:
      - '80:80'
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d: ro
    networks:
      - frontend

volumes:
  db-data:
  redis-data:
  web-node-modules:

networks:
  frontend:
  backend:

Exemple de config Nginx

Acheminez le trafic sur le port 80 vers le service web.

# ./nginx/conf.d/app.conf
server {
  listen 80;
  server_name _;

  location / {
    proxy_pass http://web:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  location /healthz {
    return 200 'ok';
    add_header Content-Type text/plain;
  }
}

Exemple de Dockerfile Node.js

Restez proche de la production : base minimale, utilisateur non-root, version épinglée, et un endpoint de santé simple dans l'app sur /health.

# ./web/Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
RUN addgroup -S app && adduser -S app -G app && chown -R app: app /app
USER app
EXPOSE 3000
CMD node server.js

Exemple d'app Node minimale

// ./web/server.js
const express = require('express');
const app = express();
const port = 3000;

app.get('/health', (req, res) => res.send('ok'));
app.get('/', (req, res) => res.send('Hello from web via Nginx'));

app.listen(port, () => console.log(`web listening on ${port}`));

Variables d'environnement et secrets

Utilisez un fichier .env au niveau du projet pour les variables de Compose, et des fichiers env par service pour les réglages applicatifs.

Le .env de projet pilote le comportement de Compose et les valeurs partagées.
Les env files de service pilotent les paramètres applicatifs.
Ne commitez pas de secrets réels. Fournissez des fichiers d'exemple et chargez les vraies valeurs depuis un emplacement sécurisé.

Exemple de .env de projet :

# ./.env
COMPOSE_PROJECT_NAME=prodlike
WEB_PORT=8080

Exemple de fichier env de service :

# ./env/web.env
PORT=3000
DATABASE_URL=postgresql://app: app@db:5432/appdb
REDIS_URL=redis://redis:6379/0

Vous pouvez référencer ${WEB_PORT} dans votre fichier Compose pour éviter de coder en dur les ports.

Health checks et ordre

Les Docker health checks rendent explicite la disponibilité des dépendances. Utilisez healthcheck dans chaque service et depends_on avec condition: service_healthy pour les dépendants. Cela évite que le web échoue parce que la base n'est pas encore prête.

Santé du web : GET /health renvoie 200.
Santé de Postgres : pg_isready passe.
Santé de Redis : redis-cli ping renvoie PONG.

Compose affiche la santé via docker compose ps afin que vous sachiez quand la pile est prête.

Démarrer, tester, itérer

Démarrez la pile :

docker compose up -d --build

Vérifiez l'état et la santé :

docker compose ps
docker compose logs -f --tail=100 web db redis nginx

Testez via le proxy comme un utilisateur :

curl -sS http://localhost/

Options de hot-reload :

Montez ./web dans le conteneur pour des éditions locales rapides.
Si vous avez besoin de nodemon, ajoutez-le à devDependencies et exécutez-le via un fichier Compose d'override réservé au local.

Reconstruisez quand le Dockerfile change :

docker compose build web && docker compose up -d web

Débogage et troubleshooting

Contrôles et corrections fréquents :

Conflits de port
Symptôme : docker compose up échoue à exposer un port.
Correctif : changez les ports hôtes (ex. WEB_PORT) ou arrêtez le processus en conflit.

Health check qui échoue
Consultez les logs : docker compose logs web.
Exécutez un curl interne : docker compose exec web sh -lc 'wget -qO- http://localhost:3000/health'.
Vérifiez les variables d'environnement : docker compose exec web env | sort.

L'app n'atteint pas db ou redis
Vérifiez le DNS interne : docker compose exec web getent hosts db redis.
Testez la connectivité TCP : docker compose exec web sh -lc 'nc -zv db 5432' et 'nc -zv redis 6379'.

Permissions de volumes sous Linux
Symptôme : EACCES en écriture.
Correctif : alignez UID/GID dans le conteneur sur l'utilisateur hôte, ou chown du répertoire de travail au build comme montré dans le Dockerfile.

Synchronisation de fichiers lente sur macOS/Windows
Symptôme : hot reload lent.
Correctif : utilisez l'option :cached, placez les dépendances lourdes dans un volume nommé (web-node-modules), ou re-buildez plus souvent au lieu de tout monter en live.

Réinitialisation inattendue des données
Assurez-vous d'utiliser des volumes nommés (db-data, redis-data) plutôt que des volumes anonymes.
docker compose down -v supprime les volumes nommés ; utilisez-le avec précaution.

Environnement non appliqué
Vérifiez l'ordre de résolution : .env, shell et env_file.
Affichez la config finale : docker compose config.

Commandes utiles :

docker compose config
docker compose ps --format json | jq '.'
docker compose logs -f web
docker compose exec -it web sh
docker compose inspect web

# Réseaux et volumes
docker network ls
docker network inspect prodlike_backend
docker volume ls

Plan pilote local

Commencez petit, mesurez, puis étendez.

Périmètre

Services : web + db uniquement.
Critères de succès :
Temps entre docker compose up -d et services en healthy < 15 s sur votre machine.
curl http://localhost/ renvoie 200 et le contenu attendu.
docker compose restart web revient à healthy en moins de 5 s.

Étapes

Implémentez les endpoints et checks de santé pour web et db.
Ajoutez un volume nommé pour les données Postgres.
Câblez l'environnement via ./env/web.env et ./.env.
Mesurez les temps de base avec les commandes de ce guide.
Ajoutez Redis et Nginx quand le pilote atteint les critères.

Pourquoi cela fonctionne

Un périmètre étroit est plus simple à déboguer et à raisonner.
Des résultats mesurables clairs vous indiquent quand agrandir la pile.

Conclusion

Un setup Docker Compose proche de la production vous donne un feedback rapide et réaliste sans quitter votre machine. Modélisez votre pile avec des services, réseaux et volumes ; câblez la configuration via des env files ; utilisez des Docker health checks et un workflow reproductible pour réduire le rework. Démarrez par un pilote restreint, mesurez les résultats, puis progressez vers une parité plus complète. Les mots-clés comme Docker Compose, Docker networks, Docker volumes, Docker health checks, Dockerfile examples, docker commands, local testing et troubleshooting restent centraux pour des workflows de développement locaux réellement efficaces.