Document preview hosts and custom domain name rules on Fabric by dawsontoth · Pull Request #718 · HarperFast/documentation

dawsontoth · 2026-10-07T19:07:46Z

⊙ Problem

Fabric is adding preview hosts: Colocated and Dedicated clusters will serve isolated applications under app. and their own host name, with no setting. The docs describe neither those hosts nor the custom domain name rules that HarperFast/central-manager#917 adds.

🤔 Should the page describe preview hosts before they deploy?

Chosen: no. This PR merges only once HarperFast/central-manager#917 and HarperFast/host-manager#244 are live, so the page never describes hosts that do not work yet. The alternative is merging now with a note that previews are coming.

💡 Solution

Preview hosts: pr-42.app.<cluster name>.<organization subdomain>.harperfabric.com reaches the isolated application that lists it, and any other host gets no response.
When an existing cluster starts serving them: one instance at a time, within about seven weeks.
What sharing a site with production means for cookies and SameSite.
Custom domain name rules: case-insensitive, valid hostnames, never a cluster's host name or a name under it, and one organization per name.

Depends-on: #715

Merge order

Document isolated applications, branched databases, and per-PR CI previews #715, which adds the isolated-applications section this page links to.
HarperFast/central-manager#917, then HarperFast/host-manager#244, deployed.
This PR, once those are live.

🤔 Should the page admit that previews are intermittent on existing clusters?

Chosen: yes. Until every instance has renewed, a request that reaches an instance without the new certificate gets no response, and the page says so. The alternative is waiting for the fleet to renew, about seven weeks after deploy, and merging then.

🤔 Is documenting the same-site boundary enough?

Chosen: yes. The page tells customers to preview only code they would trust in production, to use __Host- cookies and CSRF or Origin checks, and that Harper's own session cookie cannot take that prefix. Separating them would mean serving previews from another domain.

🔧 Changes

fabric/cluster-creation-management.md adds the Preview Hosts section:
- the host name shape, and that Fabric creates the DNS record and certificate with no setting;
- that only isolated applications answer, and a preview host is exactly one label below app. and the cluster's host name;
- which clusters and when existing ones start serving them;
- what sharing a site with production means: cookies, __Host- names, Harper's session cookie, SameSite, and that what production serves only from a custom domain is a different site.
fabric/custom-domains.md adds the name rules under Adding a Custom Domain, linking to preview hosts.

✅ Verification

Docs-only. npx prettier --check is clean on both files.
Each statement was checked against the companion code in HarperFast/central-manager#917, HarperFast/host-manager#244 and Harper's session handling.
Nothing here is observable end to end until #917 and Fix Open Graph images to render well across all social media sites #244 deploy; the deployed canary in #917's rollout covers it.

Statements checked

The host name shape and the one-label rule match central-manager's *.app.<cluster> record and host-manager's wildcard application routing, which covers one label.
"Only isolated applications" and "no response" match host-manager never routing the wildcard to the shared workers.
The instance host names, central-manager's <location>-<n>.<cluster host name>, sit outside app., so no preview host can be one.
The renewal timing matches host-manager's 40-day renewal threshold on 90-day certificates.
Harper's session cookie name is fixed: security/auth.ts builds it as [origin-]hdb-session.
The custom domain rules match customDomains.js and clusterHostNames.

🤖 Generated with Claude Code

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,cursor-kimi,cursor-muse; rounds=5; full=1 @ 2af7c0f}

_{Review-Attention: skim ~2m (decisions: previews-same-site-as-production, always-on-previews, renewal-driven-rollout, fabric-owned-preview-hosts) @ 2af7c0f}

A Fabric custom domain can be a wildcard such as *.preview.example.com, covering one label below its base, so per-PR preview hosts need one registration instead of one each. The page now covers where its TXT record goes (_fabric.<base>), its CNAME, that a more specific domain wins, and that its certificate is the customer's: Fabric's automatic certificates use Let's Encrypt's HTTP-01 challenge, and Let's Encrypt issues wildcards only through DNS-01. The certificate is added with add_certificate against the cluster's Operations API. Also notes that domain names are case-insensitive and claimable by one organization once verified. Companion to HarperFast/central-manager#917 and HarperFast/host-manager#244; merge after both ship. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…s API URL, replication Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-07T19:12:27Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

Customer wildcard custom domains were dropped from HarperFast/central-manager#917. The page keeps the rules that still hold: names are case-insensitive and stored lowercase, must be valid hostnames, and belong to one organization once verified. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-07T19:24:46Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

A cluster can now serve isolated applications under *.preview.<cluster hostname> (HarperFast/central-manager#917, HarperFast/host-manager#244): Fabric creates the DNS record and orders the wildcard on each instance's certificate, so a preview needs only a deploy. Documents what reaches a preview host, the one-label rule, which clusters qualify, and the API request that turns it on until Studio has a setting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…osts on Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

HarperFast/central-manager#917 now keys each cluster's preview namespace on its ID, *.<cluster id>.preview.<organization subdomain>.harperfabric.com, instead of the cluster's hostname, so the page shows that shape, drops the default-hostname requirement, and says where the ID is before the URL needs it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-08T03:54:41Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

Preview hosts move from a per-cluster namespace turned on through the Fabric API to the wildcard of the cluster's own host name, which every cluster gets: pr-42.<cluster name>.<org>.harperfabric.com. Documents when existing clusters start serving them, and the cookie boundary between a cluster and its previews, recommending __Host- cookie names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

A preview runs under the cluster's own host name: recommend previewing only code trusted in production, give the attributes a __Host- cookie needs, note that Harper's own session cookie cannot take the prefix and that SameSite does not separate the two, and say that previews on an older multi-instance cluster are intermittent until every instance's certificate renews. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-08T18:31:13Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

Fabric now serves previews at pr-42.app.<cluster>.<org>.harperfabric.com: Let's Encrypt will not issue *.<cluster host name> beside the cluster's instance names, which sit one label under it. A host directly under the cluster's host name no longer reaches a preview, and the instance names no longer overlap preview names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-09T16:31:40Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

kriszyp

Nice

_{🤖 Reviewed with Codex}

…site caution to the cluster host name Self-hosted clusters get no preview hosts, so the section no longer opens with "every cluster". The same-site caution covers what production serves from the cluster's host name: what it serves only from a custom domain is a different site from the previews. A preview reaching an instance that has not renewed now gets no response, as host-manager#244 routes a preview host only once the instance's certificate carries the wildcard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-12T14:42:17Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

dawsontoth · 2026-10-12T16:26:33Z

i'm marking this as draft until we get the depends-on merged

dawsontoth and others added 2 commits October 7, 2026 14:53

Tighten the wildcard steps from review: separate TXT records, Studio'…

a21e8fd

…s API URL, replication Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This comment was marked as outdated.

Sign in to view

github-actions Bot temporarily deployed to pr-718 October 7, 2026 19:12 Inactive

dawsontoth changed the title ~~Document wildcard custom domains on Fabric~~ Document custom domain name rules on Fabric Oct 7, 2026

github-actions Bot temporarily deployed to pr-718 October 7, 2026 19:24 Inactive

dawsontoth and others added 3 commits October 7, 2026 16:07

Say where the Fabric API and the cluster ID are for turning preview h…

66811a8

…osts on Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dawsontoth changed the title ~~Document custom domain name rules on Fabric~~ Document preview hosts and custom domain name rules on Fabric Oct 8, 2026

github-actions Bot temporarily deployed to pr-718 October 8, 2026 03:54 Inactive

dawsontoth and others added 4 commits October 8, 2026 12:45

Say a cluster's host names cannot be custom domains

33f9dcd

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Say a preview is the same site as production, without bounding the site

79ff368

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions Bot temporarily deployed to pr-718 October 8, 2026 18:31 Inactive

dawsontoth marked this pull request as ready for review October 8, 2026 19:51

dawsontoth requested a review from a team as a code owner October 8, 2026 19:51

github-actions Bot temporarily deployed to pr-718 October 9, 2026 16:31 Inactive

kriszyp approved these changes Oct 12, 2026

View reviewed changes

Comment thread fabric/cluster-creation-management.md Outdated

Comment thread fabric/cluster-creation-management.md Outdated

github-actions Bot deployed to pr-718 October 12, 2026 14:42 View deployment

dawsontoth mentioned this pull request Oct 12, 2026

[Epic] PR preview deployments HarperFast/harper#3042

Open

2 of 33 tasks

dawsontoth marked this pull request as draft October 12, 2026 16:26

Navigation Menu

Repository navigation

Document preview hosts and custom domain name rules on Fabric - #718

Document preview hosts and custom domain name rules on Fabric#718
dawsontoth wants to merge 12 commits into
mainfrom
docs/fabric-wildcard-custom-domains

dawsontoth commented Oct 7, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions Bot commented Oct 7, 2026

Uh oh!

github-actions Bot commented Oct 7, 2026

Uh oh!

github-actions Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

kriszyp left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

dawsontoth commented Oct 12, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dawsontoth commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⊙ Problem

🤔 Should the page describe preview hosts before they deploy?

💡 Solution

🤔 Should the page admit that previews are intermittent on existing clusters?

🤔 Is documenting the same-site boundary enough?

🔧 Changes

✅ Verification

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions Bot commented Oct 7, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 7, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 8, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 8, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 9, 2026

🚀 Preview Deployment

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 12, 2026

🚀 Preview Deployment

Uh oh!

dawsontoth commented Oct 12, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dawsontoth commented Oct 7, 2026 •

edited

Loading