A terminal UI for the sites Caddy serves for your self-hosted apps. Each site gives an app
on this machine a LAN name like jellyfin.home.arpa and is linked to the systemd service
that runs the app. It's the companion of ServiceMan: ServiceMan runs
your apps, and CaddyMan puts them behind Caddy. Navigation uses Emacs keys.
CaddyMan doesn't install or run Caddy. You run Caddy the normal way, as a system service,
and CaddyMan only manages the site entries. Everything CaddyMan owns stays in
~/.config/caddyman/, and your changes reach Caddy only when you apply them:
-
Saving a site (in the form, or
x/ delete) needs no sudo. It updatesconfig.jsonand the site's file in~/.config/caddyman/sites/, and checks the file with Caddy against your Caddyfile. -
Apply changes (
C-x C-s, orcaddyman apply) asks for your password, then:- copies the site files into
/etc/caddy/caddyman/; - removes the files of deleted or disabled sites;
- checks Caddy's whole config;
- runs
systemctl reload caddy.
If Caddy refuses, the previous files are put back. The top bar counts the changes not applied yet, and changed sites are marked
✎. - copies the site files into
-
Install Caddy as a normal system service, e.g. from Caddy's apt repository.
-
Import CaddyMan's sites in
/etc/caddy/Caddyfile, after your snippets (sites can only use a snippet defined before the import line):(trusted_only) { @untrusted not remote_ip private_ranges respond @untrusted "Forbidden" 403 } import caddyman/*.caddyThe first Apply changes creates
/etc/caddy/caddyman/. -
Install CaddyMan and check the setup:
make install # installs ~/.local/bin/caddyman and ~/.config/caddyman/config.json caddyman check # says what's missing and how to fix it caddyman # opens the TUI; c adds a site, C-x C-s applies
- If a config already exists,
make installasks whether to keep it (default), update it with new settings, or replace it (a backup is saved first). make uninstallremoves CaddyMan; see Uninstalling.
- Lists your sites with their address, what they serve, the service behind them and that service's state (active, failed, not found…), HTTPS, trusted only, and the redirect.
- Adds and edits sites in a form, with an optional preview of the site's file. Each enabled
site is one file,
<address>.caddy. If Caddy refuses a change, it isn't saved, and you see Caddy's error in the form. - Each site is either a reverse proxy to a port (
8096meanslocalhost:8096) or a static file server for a directory (Caddy's user must be able to read it). Its options:- Service: the systemd unit running the app, picked from the services ServiceMan
tracks. It comes first in the form, since picking one fills in the rest. Picking one
fills in an empty Upstream from its health URL. An app with a
caddyman-infocommand (it prints JSON describing itself;serviceman-infois the same command, for ServiceMan) is autoconfigurable, and the Service field says so, with its port. Picking it makes Upstream auto, and fills in a new site's name and suggested HTTPS, Trusted only and Redirect values; fields you changed are kept. An existing site keeps its other settings. Only binaries that contain the namecaddyman-infoare asked, so other programs are never run with an argument they don't know; each is asked again only when it or its config file changes. - Name: a short name or a full address (see below).
- Serves: a proxy or static files.
- Upstream (proxy) or Directory (static files). An auto Upstream can't be
edited: the config stores
"upstream": "auto", and CaddyMan asks the service for its port every time it writes the site's file (saving,caddyman apply), so the site follows the app's port. If the app has no port yet (it picks one on its first start), saving or applying stops and says so. Pick another service, or none, to type an Upstream by hand. - Redirect / to: sends requests for exactly
/elsewhere, e.g./web/. - HTTPS: a certificate from Caddy's own certificate authority (
tls internal). Turn it off for plain HTTP. - Trusted only: imports your
trusted_onlysnippet (named in the config). - Enabled: a disabled site stays in the list but has no file, so Caddy doesn't serve it.
- Service: the systemd unit running the app, picked from the services ServiceMan
tracks. It comes first in the form, since picking one fills in the rest. Picking one
fills in an empty Upstream from its health URL. An app with a
- Short names get the
domain_suffix(home.arpa):jellyfinis served atjellyfin.home.arpa. A name with a dot is used as it is. - In
/etc/caddy/caddyman/, only files CaddyMan wrote (they start with# Generated by caddyman) are ever replaced or deleted. Files you put there by hand are left alone.
HTTPS sites get certificates from Caddy's own certificate authority. Each device must trust
its root certificate once. With Caddy from apt, it's at
/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt, created when Caddy first
serves an HTTPS site. M-x Show root certificate shows its fingerprint and how to install
it on Linux, Android, iOS, Windows, macOS and Firefox.
Devices need to resolve the names to this machine. Until a local DNS server does that,
caddyman hosts (or M-x Show hosts lines) prints the /etc/hosts lines to add on
each device.
| Want to… | How |
|---|---|
| Put an app behind Caddy | c, a name, its Service (or port), C-c C-c, then C-x C-s |
| Serve a directory | c, Serves: Static files, C-c C-c |
| Change a site | e, then C-c C-c to save |
| Turn a site off for a while | x |
| See why an app is down | s (the service's systemd status) |
| Check on Caddy | i (Caddy's status), M-x Check Caddy setup |
| See what CaddyMan wrote | v (the site's file, and whether Caddy has it) |
| Send the changes to Caddy | C-x C-s (asks for your password) |
| Key | Does |
|---|---|
C-n / C-p |
Next / previous |
C-s |
Filter |
C-g |
Cancel |
c |
Add a site |
e / RET |
Edit the site |
x |
Disable / enable the site |
C-k / d |
Delete the site (asks first) |
s |
The service's status |
i |
Caddy's status |
C-x C-s |
Apply changes (sudo) |
r |
Reload Caddy (apply even with no changes) |
C-c C-c |
Save (in the Add / Edit Site form) |
q |
Quit (asks first if changes aren't applied) |
Every other command is in M-x: type to find it by name. ? lists all keys.
ESC works as Meta (ESC x = M-x).
The config is ~/.config/caddyman/config.json. It's the source of truth for the sites: their
files in ~/.config/caddyman/sites/ are generated from it, and hand edits to them are
overwritten. If you edit the config by hand, run caddyman apply. sites/ is generated, so
leave it out of a dotfiles repo.
| Setting | Meaning |
|---|---|
domain_suffix |
Added to names without a dot (home.arpa) |
caddy_bin |
The caddy command (caddy, from PATH) |
caddyfile |
Caddy's main Caddyfile (/etc/caddy/Caddyfile) |
caddy_sites_dir |
Where Apply changes copies the site files (/etc/caddy/caddyman) |
trusted_snippet |
The snippet "Trusted only" imports (trusted_only) |
root_cert |
Caddy's root certificate, for Show root certificate |
serviceman_config |
ServiceMan's config, for its tracked services (~/.config/serviceman/config.json) |
lan_ip |
This machine's address in the hosts lines (empty: found automatically) |
sites |
The sites (managed by CaddyMan) |
caddyman config version # your config's version vs. the current one
caddyman config update # add new settings (never changes existing ones)
caddyman config path # where the config is
caddyman config template # the default config
CaddyMan needs no secrets, so it has no .env file.
caddyman list # the sites
caddyman apply # copy the sites into Caddy's directory and reload Caddy (sudo)
caddyman check # check that Caddy runs and imports CaddyMan's sites
caddyman hosts # /etc/hosts lines for the sites
caddyman paths # where the files are
make uninstall # removes the caddyman binary
rm -rf ~/.config/caddyman # its config and site files
Caddy and its copy of the sites are left as they are. To take the sites out of Caddy, remove
the import caddyman/*.caddy line and /etc/caddy/caddyman, then reload Caddy.
See LICENSE.