Domains and TLS
Voxeltron writes routes to Caddy on the same host. Caddy obtains and renews the certificate with ACME for public domains or its internal CA for local domains. Cloudflare Tunnel is optional and is selected explicitly.
Before the first deploy
- Install Caddy 2.8 or later. Voxeltron requires the
ETagresponse header on config GET requests for conditional route updates. Older versions that send it only as a trailer are refused. Check the installed version withcaddy version. - Create an A record for the hostname that points at the server's public address.
- Open port 80 for the ACME HTTP challenge and port 443 for HTTPS.
- Set
proxy.acme.emailin the daemon configuration.
Without an email, a deploy that requests a public domain using ACME fails with an error namingproxy.acme.email. That is deliberate: a domain route with no certificate path would look successful while serving nothing.
Configure automatic HTTPS
Edit /etc/voxeltron/voxeltron.toml:
[proxy]
http_port = 80
https_port = 443
[proxy.acme]
issuer = "acme"
email = "ops@example.com"The default directory is the Let's Encrypt production directory. Keepdirectory_url only when you need a staging or test CA:
[proxy.acme]
email = "ops@example.com"
directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"Validate and restart:
$ sudo voxeltrond config validate
$ sudo systemctl restart voxeltrondUse local domains or an internal CA
Domains ending in .test, .localhost, .local,.internal, or .home.arpa use Caddy's internal TLS issuer automatically. These routes do not require an ACME email or a public DNS record. Resolve the hostname to the Caddy host with local DNS or your hosts file.
To use the internal CA for every domain, including public names, set:
[proxy.acme]
issuer = "internal"issuer accepts only acme and internal. The default is acme. Public domains still require an email unless you explicitly select internal. Internal policies do not useemail or directory_url.
Trust Caddy's root CA on each client that connects to these HTTPS routes. For a local test against Caddy on port 443, you can bypass certificate verification:
$ curl -k --resolve app.test:443:127.0.0.1 https://app.test/Use -k only for testing. It disables certificate verification.
Add a domain
In a manifest, set app.domain. vxl up selects the Caddy edge automatically when any component has a domain:
app:
image: hello:latest
port: 8080
domain: hello.example.comFor a single deployment, pass --domain:
$ vxl deploy ghcr.io/you/api:1 --name api --server prod --domain api.example.com --waitCaddy receives the route and obtains the certificate. The first request after a deploy can fail while issuance is in progress; retry after a few seconds.
Check the route
$ vxl doctor route --server prod --deployment-id <deployment-id> --public-url https://api.example.com/healthz
$ curl -v https://api.example.com/healthzvxl doctor route compares the verified origin, the provider route and the public deployment marker. If a certificate or DNS check fails, vxl doctor remote checks the daemon, proxy and DNS together.
Use the Cloudflare edge
vxl deploy defaults to --edge caddy. Ask for Cloudflare explicitly:
$ vxl deploy ghcr.io/you/api:1 --name api --server prod --domain api.example.com --edge cloudflare --waitThe Cloudflare path needs a token and a zone. Check them before deploying:
$ vxl cloudflare doctor --zone example.comvxl cloudflare doctor reports token, zone and route capabilities. A deploy with--cloudflare-preflight stops before submission when the token or zone cannot support the route.
Adopt routes from an earlier install
If Caddy already contains routes before Voxeltron takes ownership, the daemon refuses to mutate those domains until an operator adopts them:
$ vxl edge adopt
$ vxl edge adopt api.example.comWith no arguments, vxl edge adopt lists the routes that need adoption and the proposed owner. With a domain, it adopts exactly that route. Removing a route requires the offline voxeltrond edge remove-route command with the route index and digest that the daemon reported.
What Voxeltron does not do
- It does not issue wildcard certificates.
- It does not run a second ACME client or store certificates in its own data directory.
- It does not use Cloudflare unless you ask for it with
--edge cloudflare.
HTTP 404 with No app is deployed at this address. means no app route matches this host, including after vxl down.