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 ETag response header on config GET requests for conditional route updates. Older versions that send it only as a trailer are refused. Check the installed version with caddy 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.email in 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 = "[email protected]"

The default directory is the Let's Encrypt production directory. Keepdirectory_url only when you need a staging or test CA:

[proxy.acme]
email = "[email protected]"
directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"

Validate and restart:

$ sudo voxeltrond config validate
$ sudo systemctl restart voxeltrond

Use 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.com

For a single deployment, pass --domain:

$ vxl deploy ghcr.io/you/api:1 --name api --server prod --domain api.example.com --wait

Caddy 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/healthz

vxl 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 --wait

The Cloudflare path needs a token and a zone. Check them before deploying:

$ vxl cloudflare doctor --zone example.com

vxl 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.com

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