You give it a URL and a target IP:Port. It writes the Caddyfile and hot-reloads the running Caddy through the admin API, so a change is live in well under a second without restarting Caddy and without disturbing the Let's Encrypt certificates or any in-flight connections.

What it manages

Each entry is one site block:

Field	Meaning
`url`	Bare hostname, e.g. `umbraforge.bdmurphy.me`. No scheme, port or path.
`target`	`IP:Port` or `hostname:Port` of the backend.
auth user / password	Optional HTTP Basic Auth for that subdomain.

Saving an existing URL updates its target in place. Leaving the password blank on an edit keeps the credential that is already stored.

Running it

cd /home/bdm/cadprox
docker compose up -d --build

The UI is then on http://<host>:8090. Sign in as admin.

The password comes from CADPRox_Secrets in this directory, which is mounted read-only into the container and never written into docker-compose.yml:

cat CADPRox_Secrets          # the admin password, one line, mode 600

That file is in .gitignore. It is deliberately kept out of the compose file because the password contains a #, which YAML would read as the start of a comment, and because anything in the compose file is visible in docker compose config and docker inspect.

CADPRox_Secrets accepts either shape:

your-own-secret-here                         <- bare password, the common case

# comment lines and blank lines are ignored
CADPROX_ADMIN_PASSWORD=some-secret-here      <- key=value, for holding more later

If neither key is recognised, the whole file is treated as the password, so a bare password that happens to contain = still works.

To change the password, edit the file and docker compose up -d --build. The old one stops working immediately. If the file is missing, Docker silently creates a directory in its place; cadprox detects that and refuses to start rather than coming up with no password.

Why the port is not in the `docker ps` output

docker ps shows a PORTS column only for published ports, and publishing a port requires bridge networking. Bridge networking cannot reach Caddy's admin API, which binds to 127.0.0.1:2019 on the host loopback. Sharing the host network is therefore what makes the no-restart hot-reload possible, and host networking is exactly the mode that shows no ports.

Docker does not reject a ports: entry alongside network_mode: host; it prints WARNING: Published ports are discarded when using host network mode and carries on, which would look like a mapping that is not there. The port is therefore set as CADPROX_PORT: "8090" in the compose file, which is where it is actually authoritative, and is left out of ports: on purpose.

How a change is applied

The current Caddyfile is parsed into structured entries.
The new entry set is rendered back to a Caddyfile.
The result is validated with the real Caddy binary, via caddy validate --adapter caddyfile. An invalid config never reaches disk.
The file is written atomically (temp file plus os.replace).
It is pushed to the live instance with POST /load on 127.0.0.1:2019.
If Caddy rejects the load, the previous file is restored and the error is shown in the UI and written to the audit log.

Design notes worth knowing

The Caddyfile is the only source of state. cadprox deliberately keeps no parallel copy. Targets, encode gzip and the Basic Auth hashes all live in the Caddyfile, so re-reading it recovers everything, credentials included. A cached copy would let a hand-edited Caddyfile silently diverge from what the UI shows, and the next save would overwrite the operator's change.

Anything cadprox does not model is preserved byte-for-byte. If a site block contains a directive cadprox does not understand — a header block, multiple reverse_proxy upstreams, a redir, a load balancer policy — the block is kept verbatim, shown in the UI marked preserved, and cannot be edited there. It is never silently dropped or rewritten. Blocks cadprox does not recognise are listed as read-only rather than being lost.

Changes are validated, then rolled back. Nothing is written until Caddy has accepted the rendered text, and a failed reload restores the previous file.

Credentials. The admin password is compared with hmac.compare_digest. With CADPRox_Secrets in place it is read from that file on every start; if that is removed, cadprox falls back to generating a random password on first boot and recording its scrypt hash in data/admin.json. A session is a random token in an HttpOnly, SameSite=Strict cookie. Mutating requests also require an X-Cadprox header, which blocks cross-origin form posts. The Basic Auth password for a subdomain is hashed by Caddy itself and the hash is never returned to the browser.

Hashes are bcrypt, on purpose. caddy hash-password can emit argon2id, and that hash loads without complaint — but Caddy 2.11's HTTP Basic Auth provider only verifies bcrypt, so an argon2id hash silently rejects every login including the correct password. bcrypt at cost 14 is Caddy's own default for basic_auth.

What it deliberately does not do

It does not terminate TLS itself. Caddy keeps doing that, including automatic certificate issuance for new hostnames.
It does not restart Caddy, and it does not edit your Docker Compose file.
It is plain HTTP. It is meant for your LAN. Do not expose port 8090 to the internet as-is; put it behind Caddy with Basic Auth or an SSH tunnel if you need remote access.

Files

cadprox/
  app.py               the whole application, standard library only
  Dockerfile           caddy:2.11.4 + python3
  docker-compose.yml   host networking so the admin API on 2019 is reachable
  CADPRox_Secrets      the admin password, mode 600 (git-ignored)
  data/                audit log (git-ignored)
  tests/test_app.py    unit tests, including Caddy-backed parse/render tests
  tests/e2e.sh         end-to-end test against a throwaway Caddy

Tests

# unit tests. Caddy-backed tests skip automatically if the binary is missing.
python3 -m unittest discover -s tests -v

# point the Caddy-backed tests at a real Caddy
CADPROX_CADDY_BIN=/path/to/caddy python3 -m unittest discover -s tests

# end-to-end: spins up a throwaway Caddy, a backend and cadprox on spare
# ports, and never touches the live configuration.
./tests/e2e.sh

The end-to-end script asserts real behaviour, including that a correct Basic Auth password returns 200 and a wrong one returns 401, that a new proxy serves traffic immediately, and that a hand-written block survives a save intact.

Backups and recovery

/home/bdm/caddy is a git repository. Every meaningful change is a single-line diff, so history is a reliable record of who changed which target when:

git -C /home/bdm/caddy diff      # see the current change
git -C /home/bdm/caddy log -p    # full history

If the Caddyfile is ever left in a bad state, restore it and reload:

cd /home/bdm/caddy
git checkout Caddyfile
curl -X POST http://127.0.0.1:2019/load --data-binary @Caddyfile \
  -H 'Content-Type: text/caddyfile'

README.md

cadprox