Aller au contenu

Ingénierie12 min de lecture

Réseau Docker : de localhost à la production avec Coolify

localhost dans un conteneur, noms de service, ce que Coolify branche pour vous, et pourquoi un port publié passe à côté d'UFW.

Loïc Simon

Développeur Fullstack

Illustration de l'article « Réseau Docker : de localhost à la production avec Coolify »

Un soir, j'ai voulu surveiller mon VPS. Rien d'ambitieux : Prometheus pour collecter les métriques, cAdvisor pour lui dire ce que consomment les conteneurs. Deux services, un peu de YAML, un clic sur « Deploy » dans Coolify. Tout était vert.

Puis j'ai ouvert les logs de Prometheus :

dial tcp: lookup cadvisor on 127.0.0.11:53: no such host

« No such host. » cAdvisor tournait pourtant, juste là, sur la même machine. Je le voyais dans la liste des conteneurs. Prometheus, lui, affirmait calmement qu'il n'existait pas.

C'est le moment où le réseau Docker arrête d'être un détail. Tant que tout marche, on n'y pense pas. Le jour où ça casse, ça ressemble à de la magie noire, surtout avec une couche de plus comme Coolify par-dessus. Cet article est le modèle mental que j'aurais aimé avoir ce soir-là. Quatre images suffisent : des îles, une chambre, un bateau et un mur.

Pas besoin d'être administrateur système. Si vous avez déjà écrit un docker-compose.yml, vous avez tout ce qu'il faut.

Le modèle mental : des îles sur une mer

Imaginez votre VPS comme une mer calme. Chaque fois que vous lancez un projet Docker Compose, Docker y construit une petite île : un réseau rien qu'à lui. La documentation de Compose le dit sans détour : pour un projet dans un dossier myapp, « un réseau appelé myapp_default est créé », et chaque service le rejoint (Docker, Networking in Compose).

Croquis titré chaque projet Compose est une île. Sur une mer marquée votre VPS, une grande île myapp_default porte deux cabanes, web et db, reliées par un pointillé marqué db:5432, et un annuaire à 127.0.0.11. Une île plus petite, un autre projet, porte la cabane cadvisor, avec un point d'interrogation rouge entre les deux. Légende : sur l'île, les conteneurs s'appellent par leur nom de service ; de l'autre côté de la mer, l'annuaire répond no such host.

Sur une île, la vie est simple. Docker y tient un annuaire privé, un petit serveur DNS qui répond toujours à la même adresse, 127.0.0.11 (Docker, Networking overview). Si votre fichier contient un service web et un service db, web joint la base en écrivant simplement db :

YAML
services:
  web:
    build: .
    environment:
      DATABASE_URL: postgres://app:motdepasse@db:5432/app
  db:
    image: postgres:18

Pas d'adresse IP, et c'est voulu : les IP peuvent changer quand un conteneur est recréé, les noms restent. Notez aussi le port : entre services, on utilise le port du conteneur (5432 ici). Le port de l'hôte, celui de gauche dans ports:, ne sert que pour entrer depuis l'extérieur de l'île (Docker, Networking in Compose).

Vous pouvez maintenant relire mon message d'erreur. 127.0.0.11:53, c'est l'annuaire de l'île de Prometheus. Il a cherché cadvisor, et il a répondu honnêtement : pas d'habitant de ce nom ici. cAdvisor existait bien. Il vivait sur une autre île.

localhost, ou l'art de chercher sous son propre lit

Avant de construire des ponts, il faut régler le malentendu le plus courant, celui qui casse presque tout le monde le premier jour.

Dans un conteneur, localhost ne veut pas dire « le serveur ». Il veut dire « moi ». Chaque conteneur a sa propre pile réseau, avec sa propre boucle locale. Une app qui cherche sa base sur localhost:5432 regarde dans sa propre chambre, sous son propre lit. Elle peut chercher longtemps : la base vit dans la pièce d'à côté.

Croquis en coupe titré localhost = ma propre chambre. Dans la pièce de gauche, mon conteneur (web), un personnage perplexe près d'un lit demande localhost:5432 ? De l'autre côté du mur, dans la chambre d'à côté, une base de données marquée db attend, ignorée. Légende : dans un conteneur, localhost veut dire moi ; appelez les autres par leur nom, db:5432, et écoutez sur 0.0.0.0.

Le correctif, vous le connaissez déjà : remplacez localhost par le nom du service, db.

Le piège a une version miroir, plus sournoise, et je suis tombé dedans en conteneurisant mon CMS. Cette fois, c'est l'app qui écoute au mauvais endroit. En mode standalone, le petit serveur de Next.js écoute sur l'adresse donnée par la variable HOSTNAME (Next.js, output). Problème : dans un conteneur, Docker remplit déjà HOSTNAME avec l'identifiant du conteneur. Next.js écoute donc sur une seule adresse au lieu de toutes. Le proxy (ou le health check qui interroge localhost), qui n'arrive pas forcément par cette adresse-là, frappe à une porte que personne n'ouvre, et le navigateur affiche un 502 Bad Gateway. La ligne qui règle tout, dans mon Dockerfile :

Dockerfile
ENV HOSTNAME=0.0.0.0

0.0.0.0 veut dire « écoute sur toutes les interfaces du conteneur », donc aussi sur celle que voit le réseau de l'île. La documentation de Coolify donne d'ailleurs exactement ce conseil quand on obtient une erreur « No Available Server » : vérifier que le processus écoute sur 0.0.0.0 et pas seulement sur 127.0.0.1 (Coolify, Docker Compose).

Retenez la paire : on appelle les autres par leur nom, on écoute sur 0.0.0.0.

Parler au serveur lui-même : host.docker.internal

Parfois, ce que votre conteneur veut joindre n'est pas sur une île mais sur la terre ferme : un PostgreSQL installé directement sur le VPS, par exemple.

Sur Windows et macOS, Docker Desktop fournit un nom tout prêt, host.docker.internal, qui désigne votre machine. C'est avec lui que je teste l'image de mon CMS contre le PostgreSQL de mon PC. Sur un serveur Linux, ce nom n'existe pas par défaut. On le crée avec la valeur spéciale host-gateway, qui « se résout vers l'adresse IP interne de l'hôte » (Docker, docker container run) :

YAML
services:
  web:
    extra_hosts:
      - "host.docker.internal:host-gateway"

C'est là que la plupart des tutoriels s'arrêtent, et c'est là que beaucoup de gens restent bloqués. Le conteneur sait maintenant où est le serveur. Encore faut-il que quelqu'un réponde. Par défaut, PostgreSQL n'écoute que sur localhost, ce qui « n'autorise que les connexions locales de bouclage » (PostgreSQL, Connection settings). Vu de PostgreSQL, votre conteneur n'est pas local du tout. Il faut donc aussi :

  1. ajouter l'adresse de la passerelle Docker à listen_addresses dans postgresql.conf (évitez * : vous ouvririez la base à toutes les interfaces, y compris l'interface publique) ;
  2. autoriser le sous-réseau du conteneur dans pg_hba.conf. Ne le devinez pas : il dépend du réseau où vit le conteneur (Coolify en crée plusieurs), et docker network inspect <réseau> l'affiche dans le champ Subnet ;
  3. si UFW est actif, autoriser ce même sous-réseau sur le port 5432 (ufw allow from <sous-réseau> to any port 5432) : ce trafic-là, du conteneur vers l'hôte, passe bien par le pare-feu ;
  4. redémarrer PostgreSQL, car ce réglage n'est lu qu'au démarrage.

Honnêtement, si la base peut vivre dans un conteneur sur la même île que l'app, c'est souvent plus simple. C'est ce que je fais pour mon CMS : le PostgreSQL de production est une ressource Coolify, joignable uniquement par le réseau interne, et l'option « Make it publicly available » reste décochée.

Ce que Coolify branche pour vous, et ce qu'il vous laisse

Revenons à mon erreur. Coolify ajoute deux choses à notre carte : un bateau et un pont.

Le bateau : le proxy

Coolify installe un proxy, Traefik par défaut, dans un conteneur nommé coolify-proxy. C'est lui qui reçoit les visiteurs sur les ports 80 et 443 et les dépose devant la bonne app. Et voici le point que j'avais mal compris : vous n'avez pas à brancher votre app sur un réseau particulier pour que le proxy la trouve. Le proxy « rejoint le réseau coolify et les réseaux propres aux ressources » (Coolify, Networking in Coolify). Le bateau accoste tout seul sur chaque île.

Croquis titré le bateau accoste seul, les ponts c&#x27;est vous. Un voilier marqué proxy (Traefik) attend près de l&#x27;île mon app, avec une note : il rejoint seul le réseau de chaque ressource. À droite, deux îles, prometheus et cadvisor, reliées par un pont de planches marqué le réseau coolify (external: true), sur lequel se tient un bâtisseur en casque, un plan à la main. Légende : une app web derrière Coolify n&#x27;a rien à brancher ; deux ressources qui se parlent doivent toutes deux rejoindre le pont.

Ce que le proxy doit savoir, c'est sur quel port votre conteneur écoute. Dans une ressource Compose, on l'indique en suffixe du domaine, par exemple https://app.example.com:3000 : le suffixe « dit au proxy de Coolify quel port du conteneur reçoit la requête » (Coolify, Docker Compose).

Le pont : le réseau coolify

C'est un réseau partagé que Coolify crée sur chaque serveur (Coolify, Networking in Coolify). Il ne sert pas au proxy pour trouver votre app. Il sert quand deux ressources différentes doivent se parler. Et c'était exactement mon cas : j'avais déployé Prometheus et cAdvisor comme deux ressources séparées, donc sur deux îles. Le bateau accostait bien sur chacune, mais aucun pont ne les reliait.

La correction tient en quelques lignes. On déclare dans le Compose que le réseau coolify existe déjà (il est external), et on y branche les services concernés :

YAML
services:
  prometheus:
    image: prom/prometheus
    networks:
      - coolify

networks:
  coolify:
    external: true

Même chose côté cAdvisor. Pour une ressource Compose, Coolify propose aussi une case à cocher, Connect to Predefined Network, qui fait le branchement pour vous. Un détail à connaître : dans ce cas, Coolify peut préfixer les noms pour éviter les collisions, et sa documentation conseille de « vérifier le nom généré du conteneur ou du service avant de l'utiliser comme nom d'hôte » (Coolify, Docker Compose). Si votre no such host survit au pont, c'est la première chose à regarder.

Une fois les deux services sur le même réseau, Prometheus a trouvé cAdvisor du premier coup. L'erreur qui m'avait gâché la soirée était en fait une phrase très exacte : « je ne connais personne de ce nom sur mon île ».

Zéro port : pourquoi votre pare-feu ne vous protège pas

Reste le réflexe le plus dangereux, celui que j'ai eu moi aussi avant de comprendre les ponts : « ils n'arrivent pas à se parler, je vais ouvrir le port ».

YAML
services:
  prometheus:
    ports:
      - "9090:9090"   # « juste pour tester »

Ça marche, évidemment. Mais ce que vous venez d'écrire, c'est « ouvre le port 9090 de ce serveur au monde entier ». Et si vous comptiez sur UFW pour filtrer ça, mauvaise nouvelle : quand Docker publie un port, le trafic est routé « avant que les règles du pare-feu puissent s'appliquer », ce qui revient à « ignorer votre configuration de pare-feu » (Docker, Packet filtering and firewalls). Votre ufw status peut afficher fièrement « deny », la porte de côté est ouverte quand même.

Croquis de profil titré un port publié passe à côté d&#x27;UFW. Entre internet et votre VPS se dresse un mur marqué UFW avec une seule porte, 443, et un gardien sévère qui contrôle tous ceux qui entrent. Une flèche rouge en pointillés marquée ports: "9090:9090" passe sous terre, d&#x27;un inconnu curieux côté internet jusqu&#x27;à une boîte prometheus :9090, car Docker l&#x27;aiguille avant les règles du pare-feu. Légende : entre conteneurs, le réseau suffit ; pas besoin de navigateur, pas de ports, ou 127.0.0.1 seulement.

Coolify le dit aussi, en version courte : ne publiez pas un service avec ports: sauf s'il doit être joignable directement, car un port publié « contourne le routage du proxy par domaine et peut exposer un service interne » (Coolify, Docker Compose).

La bonne nouvelle, c'est que vous n'en avez presque jamais besoin :

  • Entre conteneurs, le réseau suffit. Prometheus lit cAdvisor sur cadvisor:8080 à travers le pont, sans qu'aucun port ne soit publié. Vu d'Internet, le 8080 n'existe pas.
  • Pour vos visiteurs, le proxy s'en charge. Côté applications, seuls le 80 et le 443 ont besoin d'être publiés, et c'est lui qui les tient.
  • Pour vous, en dépannage, publiez sur la boucle locale de l'hôte seulement, "127.0.0.1:9090:9090" (Docker, Compose file reference, ports), puis passez par un tunnel SSH. Le port existe, mais uniquement pour quelqu'un déjà connecté au serveur.

Votre VPS devient alors une petite ville privée : les services se parlent à voix basse entre eux, et seules quelques portes, bien gardées, donnent sur la rue.

Le test des deux minutes

Connectez-vous à votre serveur et lancez :

Terminal
docker ps --format "table {{.Names}}\t{{.Ports}}"

Regardez la colonne PORTS. Chaque entrée qui commence par 0.0.0.0: ou [::]: est ouverte au monde, UFW ou pas.

Ne vous affolez pas devant celles de Coolify lui-même : son tableau de bord publie le 8000, et le 6001 et le 6002 servent au temps réel et au terminal web. Sa documentation explique qu'une fois le tableau de bord servi par un domaine, derrière le proxy, on peut fermer l'accès public à ces trois ports, en gardant le 22, le 80 et le 443 (Coolify, Firewall). Ça se règle au niveau du serveur, pas dans votre Compose.

Pour toutes les autres, celles de vos propres services, demandez-vous : est-ce qu'un humain doit vraiment y accéder depuis un navigateur ? Si la réponse est non, supprimez la section ports:, ou rebranchez-la sur 127.0.0.1.

Ensuite, pour voir qui habite sur le pont :

Terminal
docker network inspect coolify --format '{{range .Containers}}{{.Name}} {{end}}'

Si deux services doivent se parler et qu'ils ne sont pas tous les deux dans cette liste (ni sur la même ressource), vous tenez probablement votre prochain no such host.

Ce qu'il faut retenir

Situation

Ce qu'on fait

Deux services du même Compose

Rien à faire : ils se joignent par leur nom de service et le port du conteneur.

Une app qui cherche sa base sur localhost

Remplacer localhost par le nom du service (db).

Un 502 ou « No Available Server »

Faire écouter l'app sur 0.0.0.0, et vérifier le port indiqué au proxy.

Joindre un service installé sur le serveur

host.docker.internal:host-gateway, et faire écouter le service sur l'adresse de la passerelle Docker.

Deux ressources Coolify qui doivent se parler

Les brancher toutes les deux sur le réseau coolify (external: true, ou la case « Connect to Predefined Network »), puis vérifier le nom réel.

Une app web derrière Coolify

Ne rien brancher : le proxy rejoint le réseau de la ressource tout seul.

La tentation d'ouvrir un port « pour tester »

Ne pas écrire ports:. À la rigueur 127.0.0.1:PORT:PORT et un tunnel SSH.

Depuis ce soir-là, ma règle maison tient en une phrase :

On s'appelle par son nom, on écoute sur 0.0.0.0, et on ne publie que ce qu'un navigateur doit voir.

Le réseau Docker n'a rien de magique. C'est une carte : des îles, des chambres, un bateau et un mur. Une fois qu'on sait sur quelle île vit chaque service, les messages d'erreur redeviennent ce qu'ils étaient depuis le début, des phrases parfaitement honnêtes. Le mien disait juste : « pas ici ». Il avait raison.

Sources


Je suis Loïc Simon, développeur web freelance en Bretagne. Je reprends, sécurise et documente les applications web laissées en plan par leurs développeurs d'origine ; j'en parle sur dev-relax.com. Les citations de cet article renvoient à la documentation officielle ; l'erreur cAdvisor et le 502 du CMS sont tirés de mes propres déploiements. Comme le reste de mon travail, cet article a été écrit avec l'aide d'un assistant IA, puis relu et vérifié par moi. Une erreur ? Dites-le-moi.