Installation

The README has the commands. This page explains the choices behind them.

Pick a layout

Caddyman asks once how it reaches Caddy. The choice cannot be changed later without disconnecting (see Caddy settings).

	Shared files	Network only
Where Caddy runs	Next to Caddyman, usually in the same Docker network	Anywhere Caddyman can reach over the network
Base Caddyfile	Caddy's own file, mounted read-only into Caddyman	A copy you paste into Caddyman
Route files	In Caddy's sites directory, mounted into Caddyman	In Caddyman's data volume
What a reload sends	The base Caddyfile; Caddy reads the route files from disk	The base Caddyfile and every route in one piece
Caddy needs	import /etc/caddy/sites/*.caddy at the end of its Caddyfile	To run with caddy run --resume

Pick Shared files whenever you can mount Caddy's files. Caddy and Caddyman then see the same files, and Caddy starts with your routes even when Caddyman is down.

Pick Network only for a Caddy on another machine. Every push replaces Caddy's whole configuration, so the base Caddyfile you paste has to contain everything that is not a route, including the site in front of the admin API. Without --resume, a restart of Caddy drops every route; the status page notices when that has happened.

The admin API login

Caddy's admin API has no login of its own. Caddyman expects a small site in front of it with basic auth, on port 2020 by default (the block is in the README). Do not publish that port. In "Network only", give that site a real hostname, so it gets a certificate and the password does not cross the network in the clear.

The status page still accepts a plain admin :2019, but marks "Admin API asks for a login" as missing: anything that reaches that address can reconfigure Caddy.

First start

1. Start the container with docker/compose.yml. Adjust the host paths and the network proxy-net.
2. Open http://<host>:5052/setup. The token is in docker logs caddyman, unless you set CADDYMAN_SETUP_TOKEN yourself.
3. Create the first account. It gets every right.
4. Fill in Caddy settings. "Save and check" goes on to the status page, which lists what the base Caddyfile still lacks.

Moving from another install? Choose "Import a backup" on the setup dialog instead; see System#backup-and-import.

Put Caddyman behind HTTPS

Until Caddyman has a route of its own, your password crosses the network in the clear. The status page shows a button Add a route for Caddyman that opens the route form with the right target filled in. Once that route works, open Caddyman under its name.

Keep port 5052 published anyway: it is the way back in if that route breaks. To refuse plain HTTP completely, see "Only answer over HTTPS" in Users and security.

Set the secret key

CADDYMAN_SECRET_KEY signs sessions and mail links and encrypts the stored passwords and two-factor keys. Without it, Caddyman generates one into the data volume, next to what it protects. Create one with openssl rand -base64 32 and put it in .env. Changing it later logs everybody out and makes the stored admin API and mail passwords unreadable; the status page then asks you to type them again.