Docker Compose : résoudre une connexion refusée entre conteneurs

Dans un conteneur, localhost désigne ce conteneur. Les exemples utilisent des conteneurs Linux et les services app et db : adaptez ces noms depuis le dossier de compose.yaml.

Choisir l’adresse selon l’appelant

Pour une base PostgreSQL appelée db, avec un port publié 127.0.0.1:5433:5432 :

Appelant	Adresse de la base
Application dans le même réseau Compose	`db:5432`
Outil lancé sur votre ordinateur	`localhost:5433`
Navigateur de votre ordinateur	Utilise l’URL publiée de l’API ; ne se connecte pas directement à PostgreSQL

Entre services, utilisez le nom du service et son port interne. La publication ports sert à l’accès depuis l’hôte ; elle n’est pas nécessaire pour deux services du même réseau. Évitez les IP de conteneurs codées en dur : elles peuvent changer.

Vérifier l’état et la configuration

docker compose ps -a
docker compose logs --tail 100 db
docker compose config --quiet

Si la base est arrêtée ou en boucle, corrigez d’abord son démarrage. config --quiet valide la configuration sans l’afficher. Pour lire la configuration résolue, utilisez docker compose config, mais retirez les secrets avant de partager sa sortie.

Dans votre configuration applicative, vérifiez l’hôte, le port, le nom de base et le protocole. Une variable définie dans .env pour l’interpolation Compose n’entre pas automatiquement dans le conteneur : transmettez-la via environment ou env_file selon le besoin.

Confirmer le réseau et tester la connexion

docker network ls
docker network inspect NOM_DU_RESEAU

Remplacez NOM_DU_RESEAU par le réseau du projet, souvent nommé nomduprojet_default. Vérifiez que les conteneurs de app et db y figurent. Avec des réseaux personnalisés, les deux services doivent partager au moins un réseau. Deux projets Compose distincts ont généralement des réseaux distincts.

Depuis le service appelant, utilisez le client correspondant à la dépendance. Par exemple, si le client PostgreSQL est installé dans app :

docker compose exec app pg_isready -h db -p 5432

Pour une API HTTP, si curl est présent dans le conteneur appelant, adaptez le service, le port et une route de diagnostic existante :

docker compose exec app curl --connect-timeout 3 --max-time 10 -i http://api:3000/health

Un outil absent n’indique pas une panne réseau. Utilisez les outils déjà disponibles dans votre image ou un environnement de diagnostic prévu à cet effet.

Résultat	Interprétation
Nom introuvable / `ENOTFOUND`	Nom incorrect ou résolution DNS indisponible
Connexion refusée / `ECONNREFUSED`	Mauvais port, service pas prêt ou écoute limitée
Délai dépassé	Vérifier le routage, le filtrage réseau et la charge
Réponse HTTP `401` ou `403`	Le transport HTTP fonctionne ; vérifier l’authentification
PostgreSQL accepte les connexions	Vérifier ensuite les identifiants et la base réellement utilisés

Vérifier l’écoute et la disponibilité

Un serveur HTTP dans un conteneur doit généralement écouter sur 0.0.0.0 pour être joignable par les autres conteneurs. Une écoute sur 127.0.0.1 reste limitée à lui-même. EXPOSE dans un Dockerfile ne démarre pas de serveur et ne publie pas de port.

Si l’erreur n’apparaît qu’au démarrage, intégrez ce fragment à vos services existants :

services:
  app:
    depends_on:
      db:
        condition: service_healthy
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s

Ce fragment suppose l’image officielle PostgreSQL, qui contient pg_isready, et des variables POSTGRES_USER et POSTGRES_DB déjà définies dans db. Il complète votre fichier : conservez ses images, volumes et variables. Le double dollar reporte l’expansion de la variable au shell du conteneur.

La condition attend le healthcheck au lancement. Elle ne remplace pas la reconnexion avec délai côté application après une panne. pg_isready ne garantit pas que vos migrations sont terminées ou que vos identifiants applicatifs sont corrects.

Si le service cible tourne sur l’ordinateur

Avec Docker Desktop, utilisez host.docker.internal. Avec Docker Engine sous Linux, un mappage peut être nécessaire sur le service appelant :

extra_hosts:
  - "host.docker.internal:host-gateway"

Sur Linux, vérifiez que le service de l’hôte écoute sur une interface accessible depuis Docker et que le pare-feu autorise uniquement l’accès nécessaire. Cette configuration concerne l’accès au système hôte, pas les échanges entre services Compose.

Appliquer et vérifier

docker compose up -d
docker compose ps
docker compose logs --since 2m app db

Rejouez une vraie requête de l’application. Un simple docker compose restart ne prend pas en compte les nouvelles variables d’environnement ou la nouvelle configuration Compose.