Domains and TLS

A domain is a hostname kamal-proxy serves an environment on. Add one and it goes into the destination config as a proxy host; kamal-proxy obtains a Let’s Encrypt certificate for it and serves it.

KamalCloud never writes DNS. You point the record; KamalCloud checks whether you did.

Adding one

Environment → Domains → Add. Paste a hostname or a whole URL – a URL is accepted and only the hostname kept. It needs at least two labels; a bare hostname resolves nowhere useful. An IP address is rejected, and a hostname can be used only once across the account, since two environments cannot both be served on it.

Point an A record (and AAAA, if you have IPv6) at the machine in the proxy role, then deploy. The proxy picks the hostname up and requests a certificate on first request.

DNS check

Check DNS resolves the hostname and compares it to the addresses of the machines the environment actually runs on. It tells you what it found and what it expected. A domain that does not resolve where it should shows up under Attention on the environment page – it is not blocking, because DNS is often in flight while you are setting things up.

A hostname behind Cloudflare resolves to Cloudflare rather than to your machine. That is a working setup, so Cloudflare’s addresses count as pointed.

Inspection

Inspect fetches the hostname as a browser would and reports back: whether it is reachable, what certificate is being served, when that certificate expires, and the response headers. Use it to answer “is it actually live” without leaving the page.

KamalCloud also inspects every domain on its own, from an hourly job that picks up anything not checked recently. The certificate.expiring notification fires from those inspections for a certificate that is expiring or invalid.

When you have to supply a certificate

kamal-proxy only obtains a certificate of its own for a single host. Let’s Encrypt issuance is not shared between machines, so as soon as an environment has more than one machine in the proxy role, automatic certificates stop being an option and somebody has to supply a pair.

The certificate form is on the environment’s Domains and Hosts pages. Paste the full-chain certificate and the private key. KamalCloud checks that the key belongs to the certificate before accepting them – a mismatched pair is the failure that silently serves nothing, because kamal-proxy takes both and only fails at the handshake.

The pair is stored as two secrets, because that is how Kamal reads one. The certificate can be read back; the private key is write-only – it goes in and never comes out.

What a supplied certificate means

• It covers every hostname on that environment, so it needs to name all of them. A wildcard SAN counts.
• Nothing renews it. KamalCloud tracks the expiry and warns, but replacing it before it expires is yours to do.

Certificates and ports the proxy cannot front

An app serving a protocol that is not HTTP – mail on 993, say – needs a certificate on that listener, and kamal-proxy is not in that path. Those services have to get their own certificate, usually by a DNS-01 challenge, since the proxy holds 80 and 443 and HTTP-01 cannot be answered from behind it. See Ports.