🏗️ Coolify Gateway — Protocole d’Intervention Complet

1. PHILOSOPHIE

Coolify est le centre névralgique unique de toute l’infrastructure.
Toute intervention externe (web, réseau, certificats, déploiements, backups, monitoring) DOIT passer par Coolify.

🌐 Internet ──▶ Coolify (Traefik + Sentinel) ──▶ Services
                    │
                    ├─ Auto SSL (LetsEncrypt)
                    ├─ Backups automatiques (S3)
                    ├─ Notifications (Telegram)
                    ├─ Monitoring (Sentinel)
                    ├─ Auto-déploiement (Git webhooks)
                    └─ Rollback (versions précédentes)

2. ÉTAT DES LIEUX — Ce qui est actif vs ce qui manque

✅ Actif Aujourd’hui

❌ NON activé (Potentiel perdu)

3. PROTOCOLE D’INTERVENTION — Les 7 Piliers

Pilier 1 : 🛡️ SÉCURITÉ COOLIFY (CRITIQUE)

Avant toute chose, Coolify lui-même doit être sécurisé :

# 1.1 Mise à jour Coolify
# Via UI : Settings → Update → Check for updates
# Via CLI :
docker pull ghcr.io/coollabsio/coolify:latest
docker compose up -d

# 1.2 Changement du mot de passe admin par défaut
# UI : Settings → Security → Change Password

# 1.3 Activer 2FA si disponible
# UI : Settings → Security → Two Factor Authentication

# 1.4 Restreindre l'accès UI
# Option A : IP whitelist (Cloudflare ou UFW)
sudo ufw allow from <VOTRE_IP> to any port 8000
# Option B : Coolify derrière Cloudflare Tunnel (recommandé)
# Option C : SSH tunnel uniquement (actuel)

# 1.5 Audit des tokens API
# UI : Settings → Tokens → Révoquer les tokens inutilisés

# 1.6 Journalisation des accès Coolify
docker logs coolify --tail 100 > ~/coolify-gateway/logs/coolify-$(date +%Y-%m-%d).log

Pilier 2 : 🔔 NOTIFICATIONS (CRITIQUE)

Coolify doit ALERTER en temps réel sur :

• Échec de déploiement
• Service down
• Backup échoué
• Certificat SSL expiré
• Disque plein

Configuration Telegram :

# Via UI Coolify :
# 1. Settings → Notifications → Add Notification
# 2. Choisir "Telegram"
# 3. Entrer :
#    - Bot Token : (depuis @BotFather)
#    - Chat ID : (depuis @userinfobot ou envoyer /start au bot)
#    - Events à notifier :
#      ✅ Deployment Success
#      ✅ Deployment Failure
#      ✅ Backup Success  
#      ✅ Backup Failure
#      ✅ SSL Certificate Renewal
#      ✅ Server Unreachable
#      ✅ Disk Usage Warning
# 4. Tester la connexion

Configuration des événements minimaux :

Pilier 3 : 💾 BACKUPS AUTOMATIQUES (CRITIQUE)

Coolify peut sauvegarder TOUT (bases de données, configuration, volumes) vers S3.

Configuration S3 (Backblaze B2 recommandé — 10Go gratuit) :

# 1. Créer un bucket Backblaze B2
# 2. UI Coolify : Settings → S3 Storage → Add
#    - Provider : Backblaze (ou AWS/MinIO/DO Spaces)
#    - Bucket : coolify-backups
#    - Region : us-east-005
#    - Endpoint : https://s3.us-east-005.backblazeb2.com
#    - Access Key : (depuis Backblaze App Keys)
#    - Secret Key : (depuis Backblaze App Keys)

# 3. Configurer les backups automatiques :
#    UI : Projets → Chaque service → Backup
#    - S3 Bucket : coolify-backups
#    - Fréquence : Quotidienne (4h)
#    - Rétention : 7 jours (rotation auto)
#    - Inclure : Volumes + DB dump

Plan de backup par service :

Pilier 4 : 🩺 HEALTH CHECKS & RECOVERY (CRITIQUE)

Coolify doit DÉTECTER et RÉPARER automatiquement les défaillances :

# Pour chaque service dans Coolify :
# UI : Service → Health Check
#    - Type : HTTP
#    - Path : /health ou /
#    - Port : (port interne du service)
#    - Interval : 30s
#    - Timeout : 10s
#    - Retries : 3
#    - Start Period : 60s (grace period au démarrage)
#    - ✅ Auto-restart on unhealthy

# Actuellement, plusieurs services sont unhealthy :
# - llm-council (exited:unhealthy)
# - PostgreSQL (exited:unhealthy)

Pilier 5 : 📡 MONITORING COMPLET (HAUTE)

Coolify Sentinel + notifications pour un monitoring temps réel :

# Sentinel est déjà déployé (coolify-sentinel)
# UI : Server → Settings → Sentinel
# Vérifier :
# - ✅ CPU monitoring
# - ✅ RAM monitoring
# - ✅ Disk monitoring  
# - ✅ Network monitoring
# - ❌ Alerts thresholds configurés

# Seuils recommandés :
# - CPU > 80% pendant 5 min → ALERT
# - RAM > 85% → ALERT
# - Disk > 80% → WARN, > 90% → ALERT
# - Load > CPU cores * 2 → ALERT

Pilier 6 : 🔄 AUTO-DÉPLOIEMENT (HAUTE)

Chaque service doit pouvoir se déployer automatiquement depuis Git :

# Pour un nouveau déploiement via Coolify :
# UI : Projets → Nouveau → Application
# 1. Type : Private Repository (GitHub/GitLab)
# 2. Repository : (URL du repo)
# 3. Branch : main
# 4. Build Pack : 
#    - Dockerfile (si Dockerfile existant) → RECOMMANDÉ
#    - Nixpacks (auto-détection)
#    - Static (pour sites statiques)
# 5. Domaine : (FQDN)
# 6. ✅ Auto-deploy on push
# 7. Port : (port exposé par le conteneur)

# Rollback :
# UI : Service → Deployments → Rollback
# Via API :
curl -X POST "https://cool.iatuto.com/api/v1/deploy?force=false" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"rollback": true, "tag": "previous"}'

Pilier 7 : 🔐 RÈGLES DE SÉCURITÉ STRICTES

Ce qui est INTERDIT :

1. ❌ docker run -p 0.0.0.0:XXXX — Tout port exposé directement
2. ❌ sudo certbot — SSL manuel, Traefik gère
3. ❌ Modifier /etc/nginx/sites-enabled/ — By-pass Coolify
4. ❌ ssh -L tunnel permanent — Provisoire seulement
5. ❌ Éditer les labels Docker direct — Doit passer par Coolify UI
6. ❌ Exposer Coolify UI (port 8000) sur Internet — SSH tunnel uniquement

Ce qui est OBLIGATOIRE :

1. ✅ Toute exposition web → Déclarer dans Coolify avec FQDN
2. ✅ Tout SSL/TLS → Traefik LetsEncrypt auto
3. ✅ Tout déploiement → Via Coolify (git push deploy)
4. ✅ Tout backup → Coolify S3 schedule
5. ✅ Tout monitoring → Coolify Sentinel + notifications
6. ✅ Tout redémarrage → Health check auto-recovery

4. CHECKLIST D’INTERVENTION

À chaque intervention sur l’infrastructure, répondre en format court + tracker d’étapes (préférence BF) : étape active en gras, progression (étape X / Y), uniquement le contenu utile de l’étape courante.

## Checklist Intervention
- [ ] 1. Action définie → passera par Coolify ?
- [ ] 2. Notification configurée ? (Telegram)
- [ ] 3. Backup avant modification ? (S3)
- [ ] 4. SSL/TLS via Traefik ? (LetsEncrypt)
- [ ] 5. Health check configuré ?
- [ ] 6. Monitoring Sentinel OK ?
- [ ] 7. Rollback possible ?
- [ ] 8. Port non exposé directement ?
- [ ] 9. Si gateway Telegram/Hermes : prouver que le conteneur Coolify cible porte le gateway actif, pas un service natif parallèle.

Checklist spéciale Hermes Gateway dans Coolify

- [ ] App Coolify cible identifiée par UUID/FQDN
- [ ] Statut Coolify cible = running:healthy avant de conclure connecté
- [ ] Volume host Hermes monté vers le chemin attendu dans le conteneur (`/home/bf/.hermes` → `/home/hermes/.hermes` pour image `nousresearch/hermes-agent`)
- [ ] Commande de démarrage = `hermes gateway run`
- [ ] Logs du conteneur Coolify montrent `telegram connected`/polling récent
- [ ] Absence ou arrêt planifié du gateway natif concurrent (`hermes-gateway.service`) seulement après validation Coolify
- [ ] Secrets redacted ; ne jamais afficher token Telegram/Coolify

Si une action API/Coolify modifie l’app (storage/env/start/deploy), obtenir un accord explicite type “go” avant d’exécuter.

5b. API REST COOLIFY — Déploiement Programmatique

Quand l’UI Coolify est inaccessible, tout est faisable via l’API REST avec un token Sanctum généré depuis le conteneur.

Générer un token API

docker exec coolify php artisan tinker --execute='
$user = \App\Models\User::first();
$token = $user->tokens()->create([
    "name" => "deploy-token",
    "token" => hash("sha256", $plain = \Illuminate\Support\Str::random(40)),
    "abilities" => ["*"],
    "team_id" => 0,
]);
echo $plain . PHP_EOL;
'

Endpoints clés

Créer une app publique (Dockerfile)

Payload minimal :

{
  "project_uuid": "...",
  "server_uuid": "...",
  "environment_name": "production",
  "name": "Mon App",
  "git_repository": "https://github.com/user/repo",
  "git_branch": "main",
  "build_pack": "dockerfile",
  "ports_exposes": "8787",
  "instant_deploy": true,
  "domains": "https://app.domain.com",
  "connect_to_docker_network": true,
  "force_domain_override": true
}

⚠️ Pitfalls API

• team_id est NOT NULL dans personal_access_tokens → utiliser $user->tokens()->create([..., "team_id" => 0]) PAS createToken()
• Cloudflare bloque les appels Python/Bots (Error 1010) → exécuter les appels depuis un terminal direct sur le serveur
• domains doit être une URL complète avec protocole (https://...) — pas juste le nom de domaine nu

Script utilitaire

Voir scripts/coolify-api.py — script complet avec toutes les actions (list, create, envs_set, password, deploy).

5c. PITFALL — Conflit File Provider vs Docker Provider

Symptôme : 504 Gateway Timeout sur un domaine, conteneur healthy et accessible.

Cause : Deux routes Traefik concurrentes :

• File provider (/data/coolify/proxy/dynamic/*.yml) → backend mort (socat tué, IP changée)
• Docker provider (labels conteneur) → conteneur vivant

Quand le file provider prend le pas sur un backend mort, Traefik renvoie 504.

Fix : sudo rm /data/coolify/proxy/dynamic/<nom>.yml — Traefik détecte via file.watch.

Prévention : Ne jamais créer de fichier manuel dans /data/coolify/proxy/dynamic/ pour un service déjà géré par les labels Docker. Si Coolify génère automatiquement ce fichier, vérifier qu’il pointe vers 10.0.1.X:PORT (le conteneur), pas 10.0.1.1:PORT (gateway réseau, nécessite socat).

5d. URGENCE — PROCÉDURE DE CRISE

Si Coolify est down ou inaccessible :

# 1. Vérifier l'état Docker
docker ps | grep coolify

# 2. Logs en temps réel
docker logs coolify --tail 50 -f

# 3. Redémarrer Coolify proprement
docker compose -f /data/coolify/source/docker-compose.yml restart

# 4. Vérifier Traefik
docker logs coolify-proxy --tail 30

# 5. Fallback nginx si indisponibilité prolongée
# backup configs dans ~/coolify-gateway/backups/

6. PITFALLS OPÉRATIONNELS (concrets)

🔴 Dashboard entryPoint websecure invalide

Le label Traefik traefik.http.routers.dashboard.entrypoints: websecure n’existe pas dans Coolify Traefik. Les entrypoints valides sont : http, https, traefik. Le service fonctionne quand même via un second routeur, mais les logs sont spammés toutes les 3 secondes.

Correction : Modifier le label en entrypoints: https dans le docker-compose du service dashboard, ou recréer le conteneur.

🔴 Docker Compose échoue — Network externe manquant

Quand Coolify tente de lancer un service (docker compose up -d) et échoue avec :

network <uuid> declared as external, but could not be found

Le problème : Coolify déclare le réseau comme external: true dans le docker-compose, mais Docker n’a pas créé le réseau automatiquement (bug ou cycle de vie).

Fix :

1. Créer le réseau : docker network create <network_name>
2. Copier le docker-compose + .env depuis le conteneur Coolify :

   docker cp coolify:/var/www/html/storage/app/services/<uuid>/docker-compose.yml /tmp/compose.yml
   docker cp coolify:/var/www/html/storage/app/services/<uuid>/.env /tmp/service.env

3. Créer une version patchée du docker-compose avec les variables d’env INLINÉES (évite les permissions .env) :
   • Lire les valeurs de .env via hexdump / base64 decoding
   • Inliner TOUTES les variables ${VAR} dans le compose
   • Nettoyer les env_file: pour éviter les permissions denied
4. Lancer avec : docker compose -f /tmp/compose-patched.yml up -d

Alternative (si docker non disponible dans le conteneur Coolify) : La commande docker compose fonctionne depuis le HOST (pas depuis l’intérieur du conteneur). Utiliser docker cp pour extraire les fichiers → patcher → exécuter sur le host.

Pitfalls :

• Les credentials dans .env peuvent être tronqués/redacted par Hermes — utiliser hexdump/xxd ou base64 pour les valeurs brutes
• docker exec coolify docker compose ne fonctionne PAS (docker binaire absent du conteneur)
• sh -c "docker compose ..." non plus — exécuter depuis le host directement
• Les volumes existants ont un project déférent du dossier /tmp — warning inoffensif

🔴 Ports directs Docker — Bypass Traefik

Le conteneur dashboard a -p 0.0.0.0:3000:3000 → accessible directement sans SSL ni routage. Coolify ne gère plus rien.

Détection : docker ps | grep '0.0.0.0:' | grep -v coolify

🔴 Claude Code timeout sur opérations système

Claude Code (via claude -p) timeout systématiquement (600s) sur :

• Commandes sudo (nginx, certbot)
• Modifications dans /etc/
• Redémarrage de services système

Workaround : Ne PAS déléguer ces opérations à Claude Code. Préparer les commandes en copy-paste pour l’utilisateur. Utiliser no_agent=True pour les scripts simples.

🔴 Agent Coolify → Serveur injoignable ✅ FIXÉ

Symptôme : Serveur localhost (uowsows...) marqué is_reachable: false, unreachable_count > 300, UI affiche “Underlying server is not functional”. Déploiements échouent avec "error in libcrypto" ou "Permission denied".

Causes racines (6 problèmes en cascade) :

Fix sommaire : Voir references/2026-05-30-artisan-recovery.md → §1 pour le diagnostic complet, le cast encrypted et le reformatage de la clé.

Workaround containers manuels (si SSH toujours cassé) :

docker run -d --network coolify -v <volume>:/var/lib/postgresql/data \
  --restart unless-stopped postgres:17-alpine
docker exec coolify-db psql -U coolify \
  -c "UPDATE standalone_postgresqls SET status='running:healthy' WHERE uuid='<uuid>';"

🛠️ Technique bonus — Docker mount pour écriture sudoers :

docker run --rm -v /etc/sudoers.d/:/mnt alpine \
  sh -c 'echo "bf ALL=(ALL) NOPASSWD:ALL" > /mnt/bf-nopasswd && chmod 440 /mnt/bf-nopasswd'

Utilisable dès que tu as accès au socket Docker, même sans sudo. S’applique à tout fichier système montable.

🔴 mot de passe PostgreSQL standalone = nouvel hash si recréé manuellement

Quand on démarre PostgreSQL manuellement via Docker (workaround ci-dessus), le mot de passe est défini fraîchement. Si le volume de données existait déjà, les données sont préservées mais l’auth utilise le nouveau password. Prévenir l’utilisateur.

Voir la section « Docker Compose échoue — Network externe manquant » ci-dessus pour le patron complet de recovery.

🔴 MCP Coolify lent (180s timeout)

Les appels MCP Coolify peuvent prendre jusqu’à 180s. Pour les audits rapides, préférer les commandes Docker directes :

docker inspect <container> --format '{{json .Config.Labels}}'
docker logs coolify-proxy --tail 30

7. LIENS UTILES

Références

• references/hermes-agent-telegram-coolify-verification.md — Prouver et basculer un gateway Telegram Hermes vers l’app Coolify cible sans confondre avec un service natif.

• references/bugs-et-quirks.md — Bugs concrets, entrypoint invalide, ports directs, health checks manquants

• references/docker-compose-network-recovery.md — Recovery réseau Docker manquant (compose patching)

• references/agent-ssh-unreachable.md — Artisan Tinker: reachable flags, SSH ciphertext, deployment queue, schema PostgreSQL

• references/2026-05-30-artisan-recovery.md — Artisan Tinker: reachable flags, SSH ciphertext, deployment queue, schema PostgreSQL

Scripts

• scripts/coolify-audit.py — Audit périodique (cron toutes les 6h). Exit codes: 0=OK, 1=WARN, 2=CRIT Cron ID: 0b9095fe1eb0 (no_agent=True)

Chevauchement avec infrastructure-integration

Ce skill (coolify-gateway) définit la POLITIQUE (quoi faire, quelles règles).
Le skill infrastructure-integration définit la MISE EN ŒUVRE (comment faire, pas à pas).
Ils sont complémentaires : coolify-gateway → règles, infrastructure-integration → exécution.

8. PROCHAINES ACTIONS PRIORITAIRES

Absorbed: Hermes Deployment on Coolify

references/hermes-deployment.md — Deploy and manage Hermes Agent + WebUI as Coolify applications: SSH key fix, DB operations, volumes, persistent storage. Previously a standalone skill (coolify-hermes-deployment).

Additional references absorbed:

• references/hermes-agent-webui-relationship.md — Agent/WebUI coupling and shared resources
• references/gateway-diagnostics.md — Gateway-specific diagnostic procedures
• references/coolify-schema.md — Coolify database schema reference