Chapter 07

Domains and HTTPS

Certificates are automatic and you never handle one. The single thing that can go wrong is DNS, and it goes wrong in a specific, recognisable way.

Publish in the right order

Certificates are issued by proving control of the domain over HTTP, which means the domain must already resolve to this box before you publish. The order that works:

Point the DNS record at the box and wait for it to propagate.
Confirm it resolves — dig +short app.example.com should return the box address.
Publish the site in the panel.

Publishing before DNS is correct is not destructive. The route is registered and the certificate simply stays pending, retrying in the background. The panel shows a DNS-not-ready warning on the site while that is the case. Once DNS resolves, the certificate is issued without further action from you.

Certificate pending looks like a broken site

While a certificate is pending, HTTPS requests fail — a browser warning or a connection error, depending on the client. The site is not broken and the container is fine. Check DNS first, and give it time before assuming something needs fixing.

What you get

Certificates: Issued and renewed automatically from Let's Encrypt. Nothing to install, configure or remember to renew.
HTTP: Handled at the edge. Your container only ever sees plain HTTP on port 80 from the proxy — write your app to trust the forwarded protocol headers rather than checking the scheme directly.
Wildcards: Not supported. Each domain gets its own certificate, so each one needs its own DNS record.

On a development box, expect a browser warning

Development installations typically use Let's Encrypt's staging environment, which issues certificates from an untrusted authority. The "your connection is not private" warning is expected there and does not indicate a misconfiguration. On production it should never appear.

Extra domains

A site can answer on more than one domain — www.example.com alongside example.com, a legacy domain, a vanity domain. These are added as aliases on the existing site rather than as separate sites.

Each alias behaves as its own route with its own certificate, so each one needs its own DNS record pointing at the box. An alias whose DNS is not ready stays pending exactly as a primary domain would.

Two properties worth knowing:

Aliases inherit the site's lock state. Locking a site locks every way of reaching it; you cannot bypass a lock by using an alias.
Aliases never affect your folder. The primary domain names the folder, and adding, removing or renaming aliases leaves the folder exactly where it is.

An alias can be promoted to become the primary domain. That is a rename, not a rebuild — no downtime, no re-provisioning, and the folder does not move. Which means a site's folder name and its primary domain can legitimately differ after a promotion, and that is fine.

Domains are unique across everything

A domain can be claimed once — by one site, one alias, or one internal service route. Attempting to reuse one is refused at the point you enter it, with a message naming what already holds it, rather than failing later.

Redirects between domains

The platform routes domains to your site; it does not redirect between them. If you want www.example.com to redirect to example.com rather than serve the same content, add it as an alias and handle the redirect in your application — a middleware or a route check comparing the request host. Both domains reach your app, so the decision is yours to make in code.