Custom domains

Point a domain at any application or environment. Certificates are issued and renewed for you - there is nothing to install or rotate.

Default URLs#

Every deployed environment already has a URL, built from the branch, the app, and your organization:

{branch}-{app}-{org}.light-cloud.io

The main branch of an app called storefront in the acme org serves at main-storefront-acme.light-cloud.io. These subdomains are covered by a wildcard certificate and need no DNS setup. A custom domain sits on top of this; remove it and the environment reverts to its subdomain.

Add a domain#

Custom domains come with every paid plan, from Lite at $5 a month, with SSL included. On Free, apps keep their light-cloud.io address, and adding a domain is refused with the plan that includes it. A domain that is already on a Free workspace, attached before custom domains became paid or kept after moving to Free, keeps working for 14 days after we email the owner. After that it goes on hold: visitors see a holding page, the site keeps serving at its light-cloud.io address, and moving to a paid plan brings the domain back within a minute.

1. Deploy first. A domain can only be attached to an app or environment that is live.

2. Open the Domain tab of the environment and enter the address people should use, without https://: www.example.com, app.example.com, or the bare example.com.

3. For www.example.com or example.com, both are set up at once: the one you entered is the main address, the other redirects to it (over HTTPS, keeping the path). A subdomain such as app.example.com is set up on its own.

4. The tab lists the DNS records per hostname. Each record shows the name the way your provider's form asks for it (www, @ for the root), the full name under it, what the record is for, and a copy button:

   Hostname	Type	Name	Value	Needed
   www.example.com	CNAME	www	light-cloud.io	required
   www.example.com	TXT	_acme-challenge.www	shown in the console	optional
   example.com	ALIAS / ANAME	@	light-cloud.io	required
   example.com	TXT	_acme-challenge	shown in the console	required

   • Required records are all a domain needs. For a subdomain (www, app) that is the one CNAME: the certificate is issued on its own once the name points here.
   • Optional records sit behind "optional records: switch without downtime". They matter only when the domain already has visitors on another host: add them first, wait for Active, then change the CNAME. They can be deleted once the domain is active.
   • A root domain keeps its TXT records required.
   • A CAA record appears only when your domain already limits who may issue its certificates.

5. If the tab shows Delete these records, remove them at your provider: an old A record, or a registrar's forwarding or parking, sends the domain somewhere else and the new record cannot take effect beside it.

6. The tab checks your DNS when it opens and again on Check again. Each record is marked found, not found, or different value with what public DNS answers now. DNS changes usually land in minutes but can take up to 48 hours. Each hostname is marked active once its records are in place and the certificate is issued.

From then on, traffic to the domain reaches that environment over HTTPS.

Root domains (example.com)#

A root domain cannot carry a CNAME. It needs an ALIAS record - some providers call it ANAME or CNAME flattening. The Domain tab detects your DNS provider and says what to do:

• Has ALIAS / ANAME (Name.com, Namecheap, Cloudflare, DNSimple, Vercel DNS, ...): add the root as that record type, pointing at light-cloud.io.
• No ALIAS (GoDaddy, Squarespace, Route 53, OVH, Hover, DigitalOcean, ...): use www.example.com as the main address. The root still works for http:// links through your provider's forwarding, but not for https://, so it cannot be the main address.

Do not use a registrar's "URL forwarding" or "URL redirect" for a root that should serve HTTPS: those services answer plain HTTP only, so https://example.com fails in every browser.

One domain, one target#

A domain can be attached to exactly one application or environment across the platform. Point example.com at production and give staging its own hostname, say staging.example.com, on the staging environment. Each domain gets its own certificate (TLS 1.2 minimum).

Domains work on preview environments too - a long-lived staging branch with a real hostname is a normal setup.

Certificates#

• Issued automatically once DNS verification passes; renewed automatically before expiry.
• HTTPS is always on - the default subdomains and every custom domain serve TLS 1.2 or newer.
• Nothing to upload, install, or rotate. There is no way to bring your own certificate, and no need to.

Troubleshooting#

• Stuck on pending. Click Check again: it names the record that is still missing or has a different value, and lists records to delete. Fix those at your provider and check again. Propagation can take up to 48 hours depending on the provider and the record TTLs.
• https://example.com fails, www works. The root still points at a forwarding service that has no HTTPS. Replace it with an ALIAS / ANAME record to light-cloud.io, or make www the main address.
• Certificate is not issued. If your domain has CAA records, add the CAA records the tab lists.
• Root redirect never turns active. On a provider with no ALIAS record the root is marked optional: the main www address is complete without it.
• Verification failed. Use Retry connection on the domain tab - it discards the pending setup and starts verification fresh.
• Wrong domain. Use Change, or remove the domain and add the right one; the environment falls back to its *.light-cloud.io subdomain in the meantime, so nothing goes dark.
• Works on the subdomain, not the domain. The CNAME is missing or still propagating - dig CNAME app.example.com should answer light-cloud.io.

Related#