Network
Domains: redirects, passwords, headers and wildcard certificates
A domain can redirect to another of its app's domains, an app can ask for a password and add headers to its responses, and zones can share one wildcard certificate obtained through their DNS provider.
The first three are in the app's Settings tab (Domains, Password and headers). Changing any of them redeploys a running app, without downtime (Health checks).
Redirects
PATCH /api/domains/{id} with redirect_to, another domain of the same
app that serves it (not one redirecting itself: no chains or loops), or
null to serve the app again. Requests to the domain then get a 301 to the
other, with the path and query kept: www.example.com/shop?x=1 to
https://example.com/shop?x=1, or the other way round. The domain keeps
its certificate, so https requests are redirected too. Removing a domain
makes those that redirected to it serve the app again.
Password
GET/PUT /api/apps/{id}/route-extras, basic_auth: users and
passwords (8 to 72 characters), kept as bcrypt hashes; a user sent without
a password keeps the one saved. With any, every domain of the app asks for
one of them (HTTP basic auth, over https), its processes routed under
paths too. Health checks aren't asked.
Previews get the app's, which keeps them private.
Response headers
response_headers, name to value, added to every response (and replacing
the app's own under the same name): Strict-Transport-Security,
X-Frame-Options, Content-Security-Policy… Names of letters, digits,
- and _; no line breaks in values; not Set-Cookie, Location,
Content-Length, Transfer-Encoding, Connection or Host. 30 at most.
Wildcard certificates
Every domain normally gets its own Let's Encrypt certificate, proven over HTTP (HTTP-01): the domain must already point at the servers, and each host counts against Let's Encrypt's limit of 50 certificates a week per registered domain. Previews, one host per pull request, reach it quickly.
A wildcard domain (Settings → System → Wildcard certificates, admins)
covers a zone with one certificate for *.<zone> and <zone>, proven
through the zone's DNS provider instead (DNS-01), so it's issued before
any record points here.
- DNS providers (
POST /api/dns-providers): Cloudflare (an API token with Zone → DNS → Edit) or DigitalOcean (a token with domain read and write). The token is checked, then kept sealed. - Wildcard domains (
POST /api/wildcardswithzoneandprovider_id): checked to be in one of the provider's zones.
Every domain (an app's, a store's, the panel's) that is the zone or one
label under it is then served with the wildcard's certificate: the
longest covering zone wins, and a.b.<zone> isn't covered (a wildcard
covers one label). Until the wildcard's certificate is obtained, hosts
keep their own.
Issuing one can take a few minutes: stackd waits up to 150 s for the DNS records it creates to show in public DNS, and removes them afterwards. Renewal and retries are as for other certificates, and failures show on the wildcard, on the domains it covers, and as Certificate failing alerts.
Removing a wildcard domain lets its hosts get their own certificates again; the wildcard's keeps serving them until those arrive.
Publishing address records
Wherever the panel asks for a name to be pointed at servers, an admin can publish the records at a DNS provider kept for wildcard certificates (Cloudflare or DigitalOcean, Settings → System) instead of by hand: an app's domain while it waits for DNS, a store's public endpoint, the panel's host (Panel HA), a preview domain's wildcard (every online server), and a server's own name (so a reverse DNS record naming it is trusted, which mail receivers check). Mail domains have their own, with every record they need (Mail services).
POST /api/dns-providers/{id}/records takes records (A and AAAA only,
for full domain names or a *. wildcard), apply and replace, and
answers record by record: whether it's published, will be created, or
conflicts with what's at its name (another address, a CNAME, an address
proxied through Cloudflare). Without apply, it's a preview; applying
creates what's missing and, only with replace, replaces what conflicts.
Nothing else at the names is touched. Once anything is created, the names'
certificates are tried again at once. Admins only, since the token is
everyone's.