Skip to content

Custom domains

Point your own domain (e.g. app.example.com or example.com) at a static app, service, or container. An automatic Let's Encrypt certificate covers the domain.

Add a domain

In the portal go to Domains → Add a domain. Enter the domain. Pick the target type and target app. Or use the API:

POST /v1/custom-domains
{ "domain": "app.example.com", "targetType": "service", "targetId": "<id>" }

targetType is static-app, service, or container. The domain starts pending. It becomes active once the system issues a certificate.

Point DNS at althost

  • Subdomain (app.example.com) → CNAME to the althost ingress host.
  • Apex (example.com) → A/AAAA (or ALIAS/ANAME) to the ingress IP. CNAME is not allowed at the apex.

Once DNS resolves to althost, requests route by exact Host immediately (over HTTP). The system issues the certificate automatically (below).

Automatic Let's Encrypt certificates

Certificate issuance is opt-in on the control plane. It needs a public deployment reachable on ports 80/443:

ACME_ENABLED=1
ACME_EMAIL=admin@example.com
# ACME_DIRECTORY_URL=staging   # optional: use Let's Encrypt staging while testing

With it enabled, the control plane:

  • answers HTTP-01 challenges on ACME_HTTP_PORT (default 80),
  • serves per-domain certs via SNI on the HTTPS ingress (TLS_PORT, default 443),
  • issues on first sight of a verified custom domain,
  • auto-renews each cert (within 30 days of expiry) in the background.

Althost answers the ACME challenge for the domain. Successful issuance is proof you control the domain. The system requires no separate DNS TXT step.

What your app sees

The proxy preserves the original host via X-Forwarded-Host. It sets X-Forwarded-Proto. Apps that build absolute URLs or vhost by host work correctly behind a custom domain. (The upstream Host is the loopback address of the app on its runner.)