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/wildcards with zone and provider_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.