Installation de l'Agent

L'agent est un service leger a deployer sur chaque serveur ou tourne une instance Caddy.

Comment fonctionne le reload

Quand un vhost est mis a jour, l'agent ecrit le .caddyfile dans SITES_DIR puis recharge Caddy selon l'une de ces deux methodes :

1. Docker socket (prioritaire) : si /var/run/docker.sock est accessible, l'agent execute docker exec <caddy-container> caddy reload --config <CADDY_CONFIG_PATH> — CADDY_CONFIG_PATH est ici le chemin a l'interieur du conteneur Caddy.
2. Fallback API Caddy : si le socket n'est pas disponible, l'agent envoie le contenu du Caddyfile via POST a CADDY_API_URL/load — CADDY_CONFIG_PATH est alors lu par l'agent lui-meme (doit etre accessible via un volume).

Caddy en Docker

L'agent monte le socket Docker pour recharger Caddy via docker exec. Le dossier des sites est partage entre les deux conteneurs via un volume.

services:
  cadmin-agent:
    image: cletus/cadmin-agent:latest
    restart: unless-stopped
    environment:
      AGENT_TOKEN: ${AGENT_TOKEN}
      CADDY_API_URL: http://caddy:2019
      CADDY_LOG_FILE: /var/log/caddy/access.log
      SITES_DIR: /caddy/sites # chemin dans le conteneur agent
      CADDY_CONFIG_PATH: /etc/caddy/Caddyfile # chemin dans le conteneur Caddy
    ports:
      - '3002:3002'
    volumes:
      - /var/log/caddy:/var/log/caddy:ro
      - /opt/caddy/sites:/caddy/sites # chemin hote → chemin agent
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - caddy

  caddy:
    image: caddy:2-alpine
    volumes:
      - /opt/caddy/sites:/etc/caddy/sites # meme chemin hote → chemin Caddy
      - /var/log/caddy:/var/log/caddy
    networks:
      - caddy

networks:
  caddy:
    external: true

TIP

Le dossier hote (/opt/caddy/sites) est monte dans les deux conteneurs sous des chemins differents. L'agent y ecrit les fichiers, et CADDY_CONFIG_PATH est le chemin que Caddy voit a l'interieur de son propre conteneur.

Caddy en binaire (systemd)

Sans Docker, l'agent utilise le fallback API Caddy. Le dossier des sites et le Caddyfile doivent etre accessibles en lecture/ecriture par l'agent.

services:
  cadmin-agent:
    image: cletus/cadmin-agent:latest
    restart: unless-stopped
    environment:
      AGENT_TOKEN: ${AGENT_TOKEN}
      CADDY_API_URL: http://localhost:2019
      CADDY_LOG_FILE: /var/log/caddy/access.log
      SITES_DIR: /etc/caddy/sites # identique a l'hote (volume 1:1)
      CADDY_CONFIG_PATH: /etc/caddy/Caddyfile # identique a l'hote (volume 1:1)
    ports:
      - '3002:3002'
    volumes:
      - /var/log/caddy:/var/log/caddy:ro
      - /etc/caddy/sites:/etc/caddy/sites
      - /etc/caddy/Caddyfile:/etc/caddy/Caddyfile
    network_mode: host # pour atteindre localhost:2019

WARNING

network_mode: host est necessaire pour que l'agent puisse atteindre l'API Caddy sur localhost:2019. Le socket Docker n'est pas necessaire dans ce mode.

Variables d'environnement

Variable	Description	Defaut
AGENT_TOKEN	Token Bearer pour l'authentification (obligatoire)	—
CADDY_API_URL	URL de l'API admin Caddy	http://caddy:2019
CADDY_LOG_FILE	Chemin des logs d'acces Caddy (dans le conteneur)	/var/log/caddy/access.log
SITES_DIR	Dossier des fichiers .caddyfile par site (dans le conteneur agent)	/etc/caddy/sites
CADDY_CONFIG_PATH	Chemin du Caddyfile principal — dans le conteneur Caddy si Docker socket, dans le conteneur agent sinon	/etc/caddy/Caddyfile

Securite

L'agent expose un port HTTP qui permet de recharger la configuration Caddy. Il est imperatif de restreindre l'acces :

Recommandations

• Firewall : n'autoriser que l'IP du hub sur le port de l'agent (par defaut 3002)
• Token : utiliser un token long et unique pour chaque agent
• Reseau : si possible, placer l'agent sur un reseau prive (VPN, reseau interne)

Verification

curl http://localhost:3002/health

Reponse attendue :

{ "status": "ok" }

L'endpoint /health est le seul accessible sans authentification.