This repository contains a recommended layout and tooling to manage Caddy site configurations in one place and deploy them safely to a system Caddy installation or container.

Layout

Caddyfile — top-level that imports sites/*.caddy.
sites/*.caddy — per-site small files (one site per file).
deploy/ — helper scripts and example hooks.

Quick example

On the server, create a checkout path, e.g. /srv/caddy-config.
Ensure the system Caddyfile (e.g. /etc/caddy/Caddyfile) imports the checked-out Caddyfile or sites/*.caddy:

import /srv/caddy-config/Caddyfile

Use the provided deploy/deploy.sh locally (or a CI job) to sync and run validation+reload, or push to a server bare repo and use the deploy/post-receive hook.

Safe deploy pattern

Always run caddy validate --config /etc/caddy/Caddyfile (or caddy adapt) before reloading.
Use the deploy/validate-and-reload.sh script as a canonical check-and-reload.
Grant the git or deploy user the narrow sudo permission to reload Caddy by adding the line from deploy/deploy-sudoers.example to /etc/sudoers.d/infra-caddy-deploy.

Post-receive hook (server)

Create a bare repo (e.g. /home/git/infra-caddy.git) and set the post-receive hook to the contents in deploy/post-receive.
Ensure the checked-out working tree path in the hook (/srv/caddy-config) matches your system and that the validate-and-reload.sh is executable.

The included .github/workflows/validate-and-deploy.yml validates the Caddyfile using the official caddy:2 image and demonstrates an rsync deploy step (requires DEPLOY_USER, DEPLOY_HOST secrets).

Security notes

Do not store private keys or secrets in this git repo.
Use Vault, environment variables, or other secret stores for API keys or TLS private keys.

Adding a new site

Add sites/<hostname>.caddy with the host block and rules.
Push; CI or post-receive will validate and deploy.