Domains
A service is private by default. It answers inside its environment and nowhere else. A domain is what changes that: it gives the service a public hostname, terminates HTTPS in front of it, and routes traffic to the port it listens on.
There are two kinds of domains. A platform domain is one click and works immediately, and a service has one of them. A custom domain is a hostname you own, which takes two DNS records and a few minutes, and a service can have as many as it needs.
Both need the service to have a port. A service that does not listen on one has nothing to route to.
Platform domains
Open the service, go to Settings → Networking → Platform Domain, and click Generate Domain. You get something like:
vouch-development-ee6tz.lucity.app
The name is built from the service, the environment, and a short random suffix that keeps it unique across the platform. DNS resolution and HTTPS both work pretty much instantly: there are no records to add and no certificate to wait for.
This is the right choice for development environments, for previews, and for anything internal where the URL does not need to be memorable. When you want a hostname of your own, add a custom domain alongside it: the platform domain keeps working, so nothing breaks while you set the other one up.
Custom domains
Under Settings → Networking → Custom Domains, enter the hostname you want and Lucity shows you the DNS records to add at your provider, with the exact values ready to copy.
Every custom domain needs two records: one that proves you control the domain, and one that points traffic at the platform. Which routing record you add depends on whether you are pointing a subdomain or the domain itself.
Subdomain
For api.example.com, www.example.com, or anything else below the domain:
| Type | Host | Value |
|---|---|---|
TXT | _lucity-verify.example.com | A challenge string unique to your workspace and domain |
CNAME | api.example.com | lb.lucity.app |
Apex domain
For example.com itself, with nothing in front of it:
| Type | Host | Value |
|---|---|---|
TXT | _lucity-verify.example.com | A challenge string unique to your workspace and domain |
A | example.com | The platform's IP address, shown with the record |
An apex domain uses an A record because DNS does not allow a CNAME at the root of a zone. Everything else about it works the same way.
Notice that the TXT record is identical in both cases: it goes on the domain, not on the hostname you are adding. One of them covers every hostname under that domain, so the second and third you add need only their own routing record.
Verification and certificates
Lucity picks up a record as soon as your DNS provider is serving it, without waiting for caches elsewhere to expire. The check runs every couple of minutes on its own, and the Check button next to the domain runs it immediately.
Once both records verify, two things happen. The route goes live, so the hostname reaches your service. And a certificate is requested from Let's Encrypt, which usually takes a few seconds and occasionally a minute. HTTPS starts working on that hostname when the certificate is issued, and renews itself from then on.
Troubleshooting
Each domain shows a DNS state and a TLS state, and between them they say what is holding things up.
| State | What it means |
|---|---|
| DNS pending | Neither record has been seen yet. Normal for the first few minutes after you add them. |
| DNS misconfigured | One record is right and the other is not. Almost always the TXT record on the wrong name, or a routing record that does not resolve to the expected target. |
| DNS error | The lookup itself failed, usually a nameserver problem on the domain rather than a wrong record. |
| TLS provisioning | The certificate has been requested and is not issued yet. |
| TLS error | Issuance failed. Check that the domain still resolves to the platform, and that a CAA record is not blocking Let's Encrypt. |
The most common cause of a domain that never verifies is a proxying DNS provider. If your provider hides the target behind its own network, such as Cloudflare with the orange cloud switched on, a lookup of your hostname returns their addresses instead of the CNAME target, and the check cannot confirm that traffic reaches Lucity. Set the record to DNS-only.
Removing a domain
The X next to a domain removes it. The route disappears straight away and the hostname stops reaching your service, though whatever you put in DNS stays there until you delete it too.
Removing a custom domain also removes its certificate. Add the same hostname again later and a fresh one is issued, so there is no benefit to leaving a domain attached to a service you are no longer serving from it.
Under the hood
Domains are Gateway API(opens in a new tab) objects. Each custom domain gets its own listener and its own cert-manager(opens in a new tab) certificate in your environment's namespace, with an HTTPRoute pointing at your service. Platform domains attach to a shared listener with a wildcard certificate already in place, which is why they need no issuance step.
That is all standard Kubernetes, so an ejected project keeps its routing and its certificates without Lucity in the picture.
Next steps
- Services for the port a domain routes to
- Environments for keeping production hostnames separate from development ones
- Deployments for what happens to traffic during a release