Skip to main content

ADR-007 — Déploiement Docusaurus (nginx:alpine) sur Coolify

Date : 2026-04-28 · Statut : Accepté

Contexte​

Docusaurus est servi via nginx:alpine dans un Docker Compose multi-services géré par Coolify v4. Lors du premier déploiement en production, deux problèmes bloquants ont empêché le service docs d'être accessible, malgré un nginx qui démarrait correctement :

  1. Le container docs était systématiquement marqué unhealthy par Docker
  2. Traefik retournait "no available server" même quand nginx répondait

Options considérées​

Problème 1 — Health check qui échoue

  • Option A : HEALTHCHECK CMD wget -q --spider http://localhost/ (existant)
  • Option B : HEALTHCHECK CMD wget -q --spider http://127.0.0.1/
  • Option C : Ajouter listen [::]:80; dans nginx.conf pour écouter aussi en IPv6

Problème 2 — Traefik "no available server"

  • Option A : Laisser Coolify gérer automatiquement le réseau (existant)
  • Option B : Connecter explicitement le service docs au réseau Docker externe coolify
  • Option C : Ajouter des labels Traefik manuels dans le compose

Décision​

Problème 1 → Option B (127.0.0.1 dans le HEALTHCHECK)

Sur Alpine Linux, localhost résout en ::1 (IPv6) via /etc/hosts. nginx:alpine n'écoute que sur IPv4 (0.0.0.0:80) par défaut, car notre nginx.conf custom remplace le fichier par défaut avant que le script 10-listen-on-ipv6-by-default.sh ne puisse y ajouter [::]:80. Résultat : wget http://localhost/ échoue toujours → container unhealthy → Traefik refuse de router. Utiliser 127.0.0.1 force l'IPv4 et résout le problème sans modifier nginx.conf.

Problème 2 → Option B (réseau coolify explicite)

Traefik (coolify-proxy) est configuré avec --providers.docker.network=coolify. Sans connexion explicite au réseau coolify, Traefik détecte les labels du container mais ne trouve pas de backend valide sur ce réseau. L'app Next.js fonctionnait car elle partage une autre route réseau, mais le service docs en était exclu. La solution propre est de déclarer le réseau coolify comme externe dans le compose et d'y connecter le service docs.

Conséquences​

Positives :

  • Le container docs est healthy dès le premier health check
  • Traefik route correctement vers nginx
  • La solution est déclarative dans le compose, pérenne entre les redéploiements

Risques acceptés :

  • Dépendance au nom du réseau Docker coolify (propre à Coolify v4) — si Coolify change le nom de réseau, le compose doit être mis à jour

Pattern à généraliser : Ces deux fixes s'appliquent à tout service non-Node.js dans un compose Coolify :

  • Toujours utiliser 127.0.0.1 (jamais localhost) dans les HEALTHCHECK sur Alpine
  • Toujours connecter les services au réseau coolify externe pour activer le routing Traefik

Révision​

Cette décision sera remise en question si Coolify change son réseau proxy par défaut, ou si nginx:alpine ajoute le support IPv6 par défaut dans ses versions futures.