How it works
Why a published app lives in the configuration
expose add used to write a Caddy file straight onto the machine and
reload Caddy. It worked, but it left the only record of the site on the
machine: rebuild from the configuration, and the sites expose had
written never came back.
So the record moved. A route is a field of the workspace that owns it:
workspaces:
- name: acme
routes:
- {host: app.example.com, port: 8080}
expose add writes that line. sync renders one file per workspace,
acme-routes.caddy, into the sites.d folder the caddy package
provides, and reloads Caddy when the file changed. expose rm deletes
the line (and the name’s DNS record, see below). There is one direction — configuration to machine — devmachine
never reads the machine to learn what should be published, only to check
it agrees.
Why expose does not wait for sync
sync runs the machine’s whole play: every package, every workspace. That
takes minutes, and a new subdomain should take seconds. So expose add
and expose rm also apply the one file the route changes, right after
they record it:
- Render the workspace’s routes file from
config.ymlwith the same codesyncuses. Same bytes, same path, ownerroot:root, mode0644— so the nextsyncfinds nothing to change. - Write it next to the real file, under a name the Caddyfile’s
sites.d/*.caddyimport does not match. - Set the old file aside (and any one-host file the old
exposewrote for one of these hosts), and move the new one in. - Run
caddy validateon the whole/etc/caddy/Caddyfile. The new file has to be in place for this: nothing else would check the full configuration with it. - Reload Caddy (
systemctl reload caddy, thencaddy reloadif that fails), and delete what was set aside. A Mac has no systemd: its Caddy runs under launchd, andcaddy reloadreaches it through Caddy’s own admin endpoint.syncreloads it the same way there.
If Caddy refuses the file in step 4 or 5, the old files go back, Caddy never loads the new one, and the command prints Caddy’s own error. Caddy reads the files only on a reload, so the short time the new file sits in place changes nothing it serves.
Only that workspace’s file is touched, and it is rendered from the whole
configuration, not patched: if the machine’s copy has drifted, it comes
back to what config.yml says. Other workspaces’ files wait for sync.
It runs over the same SSH connection devmachine run shares, as the
machine’s admin login (through sudo -n when that login is not root). A
machine that cannot be reached, or a machine with caddy in the
configuration but not installed yet, is not an error: the route stays
pending and sync publishes it. A self machine
always waits for sync.
--no-apply skips all of this and only records the route.
What sync takes away
When the configuration owns a host, sync also removes the one-host file
the old expose wrote for it, since Caddy refuses to reload with one
host named twice. A workspace whose last route was removed gets its
<workspace>-routes.caddy removed, not emptied — an empty file would
still serve.
Nothing else in sites.d is touched. A file another package added, or
written by hand, is not the configuration’s to delete; expose list
reports it as unmanaged and says how to adopt it.
A file another package adds to sites.d — like the one caddy-sites
writes — also reloads Caddy when sync changes or removes it. Without that
reload, Caddy would keep serving the old file until something else
reloaded it.
Why DNS is still pointed by add
The DNS record is not in the configuration, and sync does not write it.
A name that does not resolve fails minutes later, in Caddy’s certificate
log, where nobody is looking — so add points the name in the same
breath, printing the record to create by hand if the machine is
unreachable.
Why rm removes the record only while it points at the machine
A name left pointing at a machine that no longer serves it still
resolves: visitors reach Caddy, which has no site for it and refuses the
TLS handshake. So rm takes the record off too, right after Caddy.
But the record is not in the configuration, so rm cannot know it made
it. It works out the record add would have made — the serving
machine’s first public address, the same one add uses — and asks the
provider that holds the zone for the name’s A records. Only a record
with exactly that value is deleted. A different value means somebody
repointed the name, maybe at a new server, and deleting it would take
that down. A provider that cannot list the zone deletes nothing: a
delete it cannot check first is a guess.
The DNS step never undoes or blocks the Caddy step. When it fails, the site is still off Caddy, and the record to remove by hand is printed.
workspaces destroy does the same for every site of the workspace, each
on the machine that serves it, after the account is gone: once the
workspace leaves the configuration, nothing would remember those names
pointed at the machine.
When a record is printed instead of written or removed, the line above it says why: the machine could not be reached (the provider runs on it), no DNS provider is installed there, or no installed provider holds the zone.
--no-apply means “touch no machine”, and a DNS provider runs on the
machine, so rm --no-apply leaves the record and prints the dns rm
to run later. add --no-apply still points the name: a name that
resolves early does no harm, and one that does not stops the
certificate on the next sync.
Publishing through another machine
A machine the internet cannot reach — a VM on your desk, a box behind NAT — can still have its port published, by a machine that the internet does reach and that runs Caddy:
workspaces:
- name: acme
machine: lab
routes:
- {host: app.example.com, port: 8080, via: edge}
expose add acme 8080 --host app.example.com --via edge writes that line.
The name points at edge, and edge’s Caddy proxies to lab. Nothing is
installed on lab.
There is no “main” machine. Which machine serves a site is written on
the route, so a configuration with three machines and two Caddys means
the same thing to everybody. Without via, a route is served by its
workspace’s machine, as before. When that machine has no caddy, expose
refuses and names the machines that have it, instead of picking one.
The address comes from lab’s hosts, not from a VPN. The CLI
resolves them the way it does to connect (see
addresses and fallback) and takes the first
address a network package gave, since that is a private network both
machines can be on; then any other; never a loopback one, which would
name edge itself. Tailscale, Headscale, plain WireGuard or a LAN address
all work the same way, because the CLI only ever sees an address.
It is resolved every time, never stored. expose and sync resolve it
when they write edge’s file, so a machine that moves is followed by the
next sync. When the address cannot be found from your computer — the
private network is off here — sync leaves that workspace’s file on edge
exactly as it is and says so: the site keeps answering the way it did,
instead of disappearing because of where you ran the command.
edge owns the file. It is acme-routes.caddy in edge’s sites.d, the
same name sync uses everywhere. A machine with caddy owns the routes file
of every workspace in the configuration: written when it serves one of
its routes, removed otherwise. Taking the last via: edge off a route
therefore also takes the file off edge on its next sync, and
workspaces destroy removes it there before the workspace leaves the
configuration — afterwards nothing would. For the same reason
workspaces rm refuses while one of the workspace’s sites goes through
another machine, and machines rm refuses a machine that still serves a
site for another one: expose rm the host first.
expose add checks the path once. After Caddy has the site, edge
tries to open a connection to lab’s port. When it cannot, the site stays
published and the command says what to look at, because otherwise every
visitor gets a bare 502: the service listening only on 127.0.0.1, a
firewall on lab, or the two machines not on the same private network.