Skip to content
objectiveproverPublic

About

Management for your Caddy entries—Keep your self-hosted web applications organized.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

CaddyMan

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 updates config.json and the site's file in ~/.config/caddyman/sites/, and checks the file with Caddy against your Caddyfile.

  • Apply changes (C-x C-s, or caddyman apply) asks for your password, then:

    1. copies the site files into /etc/caddy/caddyman/;
    2. removes the files of deleted or disabled sites;
    3. checks Caddy's whole config;
    4. 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 ✎.

Quick start

  1. Install Caddy as a normal system service, e.g. from Caddy's apt repository.

  2. 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/*.caddy
    

    The first Apply changes creates /etc/caddy/caddyman/.

  3. 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 install asks whether to keep it (default), update it with new settings, or replace it (a backup is saved first).
  • make uninstall removes CaddyMan; see Uninstalling.

What it does

  • 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 (8096 means localhost: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-info command (it prints JSON describing itself; serviceman-info is 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 name caddyman-info are 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_only snippet (named in the config).
    • Enabled: a disabled site stays in the list but has no file, so Caddy doesn't serve it.
  • Short names get the domain_suffix (home.arpa): jellyfin is served at jellyfin.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 on your devices

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.

Finding the sites

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.

Common tasks

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)

Keys

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).

Configuration

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.

Command line

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

Uninstalling

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.

License

See LICENSE.

About

Management for your Caddy entries—Keep your self-hosted web applications organized.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages