OpenCaddyHost

Caddy expose une API REST complète pour lire et modifier sa configuration à chaud, sans redémarrage. C'est la fondation d'OpenCaddyHost.

Ce que fait l'Admin API

Par défaut, Caddy écoute sur 127.0.0.1:2019 pour les requêtes d'administration. Toute modification de configuration passe par cette API — y compris ce que fait la CLI caddy reload.

Endpoints principaux :

Structure d'une configuration Caddy (JSON)

Un reverse proxy Caddy en JSON ressemble à ça :

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "@id": "proxy-mon-app",
              "match": [{ "host": ["mon-app.example.com"] }],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [{ "dial": "localhost:8080" }]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Le champ @id est crucial : il permet d'accéder à une route précise via /id/proxy-mon-app pour la modifier ou la supprimer sans toucher au reste de la config.

Lire la configuration actuelle

curl http://127.0.0.1:2019/config/ | jq .

Sur une instance fraîche, la réponse est null — Caddy n'a aucune config chargée.

Créer un premier proxy via l'API

curl -X POST http://127.0.0.1:2019/load \
  -H "Content-Type: application/json" \
  -d '{
    "apps": {
      "http": {
        "servers": {
          "srv0": {
            "listen": [":80"],
            "routes": [
              {
                "@id": "proxy-test",
                "match": [{ "host": ["test.localhost"] }],
                "handle": [
                  {
                    "handler": "reverse_proxy",
                    "upstreams": [{ "dial": "localhost:3000" }]
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }'

Réponse : HTTP 200 sans corps = configuration chargée. Le proxy est actif immédiatement.

Supprimer un proxy par son ID

curl -X DELETE http://127.0.0.1:2019/id/proxy-test

Un seul appel. Caddy retire la route de la configuration active sans toucher aux autres proxies.

Activer le HTTPS automatique

Caddy gère Let's Encrypt automatiquement. Changer le port :80 en :443 dans la config JSON suffit :

{
  "handle": [
    {
      "handler": "reverse_proxy",
      "upstreams": [{ "dial": "localhost:8080" }]
    }
  ],
  "match": [{ "host": ["mon-app.example.com"] }],
  "terminal": true
}

Caddy détecte le nom de domaine, contacte Let's Encrypt, et obtient le certificat. Aucune config SSL à écrire.

Headers personnalisés

{
  "handler": "reverse_proxy",
  "upstreams": [{ "dial": "localhost:8080" }],
  "headers": {
    "request": {
      "set": {
        "X-Real-IP": ["{http.request.remote.host}"],
        "X-Forwarded-Proto": ["https"]
      }
    }
  }
}

{http.request.remote.host} est une variable de template Caddy — elle est résolue au moment de la requête, pas à la configuration.

Port de l'Admin API en production

Par défaut, l'Admin API est sur 127.0.0.1:2019 — accessible uniquement en local. Dans le docker-compose.yml d'OpenCaddyHost, elle est remappée sur 2020 pour éviter les conflits :

caddy:
  ports:
    - "2020:2019"  # Admin API exposée sur le port 2020 de l'hôte

CADDY_ADMIN_URL=http://caddy:2019 dans le conteneur dashboard — les deux services parlent via le réseau Docker interne, pas via l'hôte.

Vérifier la santé de Caddy

curl http://127.0.0.1:2019/config/
# 200 → API active
# Connection refused → Caddy arrêté ou Admin API désactivée

OpenCaddyHost expose un endpoint /api/caddy/health qui fait cette vérification et la renvoie au dashboard.