Le problème

Notre boutique en ligne tourne en développement avec une stack Docker Compose par service : order, stock, shipping. Chacune a son api FrankenPHP, sa database PostgreSQL et son redis. RabbitMQ et Mercure vivent dans une stack commune, que les autres rejoignent par un réseau externe, app-network.

Tout commence par l'API. Pour joindre RabbitMQ, elle reçoit networks: [app-network] et quitte du même coup le réseau default de sa stack. Elle ne trouve plus database, et le correctif rapide branche aussi database et redis sur app-network.

Cela fonctionne tant qu'une seule stack tourne. Au démarrage de stock, le nom database désigne deux conteneurs sur app-network, car chaque nom de service y est un alias réseau. Le DNS embarqué de Docker renvoie alors les deux adresses, dans un ordre mélangé à chaque réponse.

Le client PostgreSQL (libpq, sous pdo_pgsql) essaie les adresses dans l'ordre reçu et garde la première qui accepte la connexion. Les stacks viennent du même gabarit : même utilisateur, même mot de passe, même nom de base. L'API de order peut donc lire, écrire ou migrer la base de stock sans la moindre erreur, et redis pose le même problème.

Sur le réseau partagé, « database » désigne deux conteneurs stack order réseau default api database redis app-network réseau externe rabbitmq mercure stack stock réseau default api database redis « database » ? Le DNS de Docker renvoie les deux adresses : l'API de order peut ouvrir la base de stock . Correctif : seule l' api rejoint app-network , et liste aussi default database et redis restent sur le default de leur stack ; les autres stacks appellent order-api .

La solution

Seule l'API rejoint le réseau partagé : elle parle à RabbitMQ et à Mercure, et les autres stacks l'appellent. Elle liste aussi default, car nommer un réseau retire le réseau implicite. database et redis ne listent aucun réseau : Compose les branche sur default, et seulement sur lui.

# services/order/compose.override.yaml
services:
  api:
    networks:
      # Nommer un réseau retire le réseau implicite : nous le gardons.
      default: {}
      app-network:
        # Le nom à utiliser depuis les autres stacks.
        aliases:
          - order-api
  # database et redis ne listent aucun réseau : ils restent sur default.

networks:
  app-network:
    external: true

Sur default, database ne désigne plus que la base de la stack. Sur app-network, le nom api reste ambigu : chaque stack y branche le sien. Les autres stacks appellent donc order-api, un alias qui n'existe que sur ce réseau.

Docker Compose 5.7.0, publié le 2 novembre 2026, ajoute use_service_name_alias. Placé à false à côté de aliases, il retire le nom api de app-network. Avant cette version, la règle reste de ne jamais appeler api depuis une autre stack.

Le piège

Une API qui démarre ne prouve rien : elle a peut-être migré la base d'à côté. Nous vérifions la résolution depuis le conteneur, car c'est lui qui interroge le DNS embarqué. Le test n'a de sens qu'avec au moins deux stacks démarrées.

# Depuis la stack order, la stack stock étant démarrée
docker compose exec api getent hosts database
docker compose exec api getent hosts redis
docker compose exec api bin/console dbal:run-sql "SELECT inet_server_addr()"

Sur une image Debian, getent hosts affiche une ligne par adresse trouvée (celui d'Alpine n'affiche que la première) : nous en attendons une seule. La requête SQL renvoie l'adresse du serveur qui a accepté la connexion, à comparer avec celle de getent. Si getent ne renvoie rien, l'API a perdu default : c'est l'oubli qui avait poussé la base sur le réseau partagé.

Sources