Add a custom domain

View Markdown

Use a custom domain when the generated deliberate. hostname should not be your customer-facing address. A domain belongs to one Project Environment and points at an explicit route in that same Environment.

1. Declare the hostname and route

Add both resources below .deliberate/:

resource: domain
hostname: app.example.com

---
resource: route
host: app.example.com
visibility: public
rules:
  - path: /
    to: app

The hostname and route host must match. Apply them together:

deliberate apply --env production

2. Add the DNS records

Inspect the instructions generated for this binding:

deliberate domains show app.example.com --env production

For a subdomain, the command prints the CNAME target. For an apex domain, it prints the required A and ownership TXT records instead. Add exactly those records at your DNS provider.

DNS changes can take time to reach the resolver used for verification. Check the current state without changing it:

deliberate domains list --env production
deliberate domains show app.example.com --env production

3. Verify and issue TLS

After the records resolve, verify ownership:

deliberate domains verify app.example.com --env production

Verification starts certificate issuance. Re-run domains show to inspect the binding status and any last error. Once active, HTTPS traffic for the hostname is sent to the matching route.

Change or remove a domain

Treat a hostname change as an ordinary desired-state change: add the replacement domain and route, configure and verify its DNS, switch users to it, then remove the old declarations and apply again. This avoids dropping the working hostname before its replacement is ready.

deliberate domains delete <hostname> --env <env> is an explicit operational detach. For version-controlled configuration, remove the resources from YAML and apply so the repository continues to describe the Environment.

Current security boundary

Custom domains receive TLS, but they are not currently covered by the tenant origin WAF. Platform-generated public hostnames are covered. In either case, the WAF is only a safety net and never replaces security inside your application. Read Troubleshoot blocked web traffic for the precise coverage and responsibility boundary.