ADR-022: Custom domains through Cloudflare for SaaS

Status: accepted, 8 October 2026.

Context

Every shop has lived at {slug}.flowery.com.ua. Shops that already own a domain (myflowers.ua) and have printed it on cards and packaging cannot put their website on it, and the landing page has had to say so. The platform runs on one shared Forge server behind Cloudflare, with one *.flowery.com.ua certificate; it cannot hold a certificate for a hostname it does not control.

Decision

1. Cloudflare for SaaS custom hostnames. The flowery.com.ua zone is already on Cloudflare. Each connected domain becomes a custom hostname there: Cloudflare proves ownership (a TXT record), issues and renews the certificate, and proxies the traffic to our fallback origin. Shops point a CNAME at connect.flowery.com.ua. The first hundred hostnames are included in the plan; each one beyond costs $0.10 a month. The alternative, issuing Let’s Encrypt certificates per hostname on the origin, would put certificate issuance, renewal and a reverse proxy per host into our own operations on a shared server.
2. The storefront only. A shop’s own domain serves the storefront pages and the Storefront API, nothing else. The control panel, sign-in and the session cookie (.flowery.com.ua, ADR-006) stay on the subdomain, and the shop keeps its subdomain address throughout. The storefront and API routes are registered a second time on a host pattern that can never match the platform domain or a host under it, outside the web group; and the web group itself answers only on platform hosts, so sign-in and everything else are a 404 on a foreign host before a session is started.
3. One address per shop. GET /shop names the host customers use: the shop’s own domain once it is live, otherwise the subdomain. The storefront runtime answers a visit on any other host with a permanent redirect to it, except previews. Workspace::storefrontHost() is the one place that decides this; Workspace::controlPanelUrl() always builds subdomain links for staff.
4. Origin TLS. Cloudflare forwards the shop’s hostname unchanged in the Host header and the TLS name; overriding the Host header is an Enterprise feature. The origin presents its *.flowery.com.ua certificate (Let’s Encrypt, issued by Forge) for every host, so the zone must not check the certificate’s name for foreign hosts: the zone runs in encryption mode “Full” (a certificate is required, its name is not checked), which it already did when this was decided. Should the zone move to “Full (strict)” for its own hosts, a Configuration Rule keeps hosts not under flowery.com.ua on “Full”. The storefront runtime’s loopback API calls present and verify one fixed name the certificate covers (flowery.com.ua) while keeping the shop’s Host.
5. With or without www: the owner’s choice. (Amended 10 and 12 October 2026; the first version recommended www. and showed a TXT record as well; the second registered the twin unasked, which produced www.shop.kolovsky.dev for a subdomain in the first real run.) The owner types the address as the shop calls it; for a bare domain (shop.ua, shop.com.ua) or a www. name the form offers its twin as a checkbox, ticked by default, and a subdomain gets none. Both hostnames go to Cloudflare when the twin is chosen, so the site works whichever record the registrar can set: www is a plain CNAME everywhere, while a bare domain needs a provider that accepts a CNAME (or ALIAS) at the root, which Cloudflare DNS does and many registrars do not, since proxying bare domains at Cloudflare itself is an Enterprise feature. The shop is live as soon as either hostname is; the address customers use is the typed one when it is live, otherwise its twin, and the storefront redirects the other there. Ownership is validated from the CNAME itself (Cloudflare’s real-time validation); the TXT pre-validation record, which only serves zero-downtime moves of an existing site, is no longer shown. Two hostnames per shop halve the included quota to fifty shops.
6. Owner only, no plan gate. Connecting, checking and removing a domain needs the settings.domain permission, which only the owner has. One domain per workspace. Billing can gate it later.
7. Polling, not webhooks. A hostname’s state (pending, active, moved) has no webhook at Cloudflare; only certificate events do. A scheduled command checks pending domains every few minutes and live ones daily, and the settings page has a “check now” button.
8. The records are added for the shop where we can (11 October 2026). The page names the domain’s DNS provider from its name servers and links the provider’s CNAME help where known. When the DNS is on Cloudflare, “Connect with Cloudflare” sends the owner to Cloudflare’s consent screen for our OAuth client (self-service at Cloudflare; the authorization-code flow with PKCE); with the short-lived token the app adds a DNS-only CNAME to the target for each address of the pair in the owner’s zone, replacing any A/AAAA/CNAME already on that exact name and saying so, then revokes the token. Nothing of the owner’s is stored. The same one-click flow for every provider that supports the Domain Connect standard (Cloudflare, GoDaddy, IONOS, …) is item 9; the OAuth path stays for Cloudflare because it can replace conflicting records, which Domain Connect cannot.
9. Domain Connect (12 October 2026). Our template flowery.com.ua / storefront lives in the standard’s public repository: one CNAME on a host (www, or a subdomain) to connect.flowery.com.ua, hostRequired, because the standard forbids a CNAME on a bare apex — which is the limit we already tell shops about. Requests are signed with our RS256 key (private half only in the environment, public half as TXT _dcpubkeyv1.flowery.com.ua; rotation is a new id). The app finds the provider from the zone’s _domainconnect record, confirms it serves the template, and sends the owner to the provider’s own page; the owner signs in there, approves one record, and is sent back. No token ever reaches us. The provider’s answer is not trusted on its own: the address is checked against Cloudflare at once, as every other path is. Cloudflare exposes a provider’s template only after an onboarding by email; other providers read the repository.

Consequences

• workspace_domains: one row per hostname, two per shop (the typed address marked primary), with the hostname (lowercase punycode), its state (pending, active, moved, error), the Cloudflare id and timestamps. Only active resolves a request. The never-used workspaces.domain column is gone.
• IdentifyTenant resolves a host that is not under the platform domain by an active workspace_domains row; the root domain has no tenant, as before.
• The nginx site answers any hostname no other site on the shared server claims, the storefront map treats every host but the root and www as a storefront, and nginx takes the visitor’s address from CF-Connecting-IP (operations). All traffic already came through Cloudflare, so the last change also repairs Storefront API rate limiting, which had put every visitor in one bucket.
• The cart cookie is host-only, so a visitor who followed an old subdomain link starts with an empty cart on the shop’s domain. Cart merging was already deferred.
• Shop.domain joins the Storefront API contract; themes need no change because origin is already the shop’s address.
• The shop keeps its subdomain, so removing a domain never takes the shop offline: links on the old domain stop working, and the subdomain answers again at once.