Skip to content
SiteSwarm Platform Documentation

Cloudflare For Platforms And Domain Ingress

Cloudflare for Platforms, Custom Hostnames & External Domain Onboarding

1. Executive Summary & Core Objectives

SiteSwarm uses Cloudflare for Platforms—specifically Custom Hostnames combined with Cloudflare Workers Routes—to serve each client’s production web application on the client’s own domain without requiring the client to transfer domain ownership or migrate authoritative nameservers to our Cloudflare account.

This architecture satisfies three core requirements:

  1. External Domain Ownership Preserved: Clients who already own and manage their domains on external platforms (GoDaddy, Namecheap, Squarespace, Wix, AWS Route 53, or their own separate Cloudflare account) retain full registrar and DNS control while delegating only web traffic to SiteSwarm.
  2. Zero Email Disruption: Because authoritative nameservers never move, the client’s existing MX, SPF, DKIM, and DMARC records (for Google Workspace, Microsoft 365, etc.) remain untouched at their current DNS provider.
  3. Production-Only Custom Hostnames & Single-Level Platform Subdomains: Only the client’s live production application is served on the client’s custom hostname. Platform-hosted CNAME targets (<client>-ingress.<platform-domain>) and non-production staging and client preview environments (<client>-staging.<platform-domain>, <client>-preview.<platform-domain>, see CI_DEPLOYMENT_ENVIRONMENTS.md and NON_PRODUCTION_ENVIRONMENT_TAXONOMY.md) always use single-level hyphenated subdomains under our canonical corporate platform domain (jpsoftwareassociates.com, configured via platform.config.ts) because standard TLS wildcards (*.<platform-domain>, RFC 6125) only match a single DNS label and Cloudflare’s free Universal SSL covers only <platform-domain> and *.<platform-domain> (whereas multi-level nested subdomains like staging.bakery.<platform-domain> would fail TLS hostname validation unless a paid \$10/mo Advanced Certificate Manager add-on is purchased).
flowchart LR
    ExternalDNS["Client's Existing DNS Provider\nCNAME www -> <client>-ingress.<platform-domain>"] --> CustomHostnames["SiteSwarm Platform Zone\n(Custom Hostnames: Auto DCV & TLS)"]
    CustomHostnames --> WorkerRoute["Dual Worker Routes\n(Custom Hostname + Target Hostname)"]
    WorkerRoute --> ClientWorker["Client Public Worker\n(apps/<client>)"]

2. Foundational Concepts: Zones, Proxy Status & Originless Workers

Understanding how external client domains route into SiteSwarm requires three foundational Cloudflare concepts:

  1. Cloudflare Zone:
    • A zone in Cloudflare represents a single registered domain (such as SiteSwarm’s <platform-domain>, or a client’s clientbusiness.com if they use Cloudflare) along with its DNS records, SSL/TLS certificates, WAF rules, cache state, and Worker routes inside a Cloudflare account.
  2. DNS Proxy Status (Orange Cloud vs. Grey Cloud):
    • DNS-Only (Grey Cloud): Cloudflare acts strictly as a standard authoritative DNS resolver, returning the raw IP address or CNAME target directly to the requester without intercepting HTTP/TLS traffic on that zone.
    • Proxied (Orange Cloud): Cloudflare hides the underlying target and returns Cloudflare anycast edge IP addresses in DNS responses so all HTTP/TLS traffic enters that zone’s edge pipeline (TLS termination, WAF, caching, and Workers).
  3. Origin vs. Originless Execution:
    • In a traditional CDN setup, an origin server is the backend server (such as an AWS EC2 instance or VPS with a public IP) that Cloudflare forwards HTTP requests to after terminating TLS at the edge.
    • In SiteSwarm, client applications run entirely inside Cloudflare Workers at the edge. Because the Worker intercepts the request at the edge and generates the response directly without forwarding traffic to any external backend server, the setup is originless.

3. Onboarding Clients Who Own Domains on External Platforms

3.1 The “Fallback Origin” & Why Dummy IPs (100:: / 192.0.2.0) Are Used

  • What the Fallback Origin Is: Cloudflare’s Custom Hostnames feature requires the platform zone to designate a single proxied DNS record as its Fallback Origin. This record anchors the Custom Hostnames subsystem on our platform zone and serves as the default target for custom hostname resolution.
  • The fallback Naming Convention: Naming that DNS record fallback.<platform-domain> (or proxy-fallback.<platform-domain>) is simply a naming convention from Cloudflare’s documentation—the literal word fallback is not required by the protocol. In addition, Cloudflare recommends creating per-client or friendly CNAME target records (such as <client>-ingress.<platform-domain>) as proxied CNAME aliases pointing to fallback.<platform-domain>.
  • Why AAAA 100:: or A 192.0.2.0 Are Used: Even in an originless setup where a Worker handles 100% of requests at the edge and Cloudflare never connects to a backend IP, Cloudflare’s DNS dashboard still requires a syntactically valid IP address field to create an Orange-Cloud (Proxied) DNS record for the Fallback Origin. 100::/64 (RFC 6666 IPv6 Discard Prefix) and 192.0.2.0/24 (RFC 5737 TEST-NET-1 documentation range) are IETF-reserved, non-routable dummy IP addresses officially recommended by Cloudflare so traffic can never accidentally leak to a random public server if a Worker route were ever misconfigured.

3.2 Zero-Downtime Pre-Validation & Cutover for External Registrars

  1. Register Custom Hostname: SiteSwarm registers the client’s hostname (e.g., www.clientbusiness.com) under Custom Hostnames in the SiteSwarm Cloudflare zone.
  2. Pre-Validate SSL via TXT Record (Zero Downtime): While the client’s legacy website remains live on their old platform (e.g., Squarespace or Wix), the client adds the Cloudflare Domain Control Validation (DCV) TXT record at their existing DNS provider so Cloudflare can issue the production SSL certificate ahead of time.
  3. Cut Over Web Traffic via CNAME: Once the certificate is active, the client updates their www CNAME record at their registrar to point to their assigned CNAME target on our platform domain (<client>-ingress.<platform-domain>). Traffic immediately routes through SiteSwarm with zero SSL provisioning delay and zero impact on MX email records.

3.3 What an @ (Apex) Domain Is & Why Standard CNAME Records Cannot Be Used at @

  • What an @ (Zone Apex) Domain Is: The zone apex (represented by the @ symbol in DNS editors, and also called the root or naked domain) is the bare domain name without any subdomain prefix—for example, clientbusiness.com rather than www.clientbusiness.com.
  • Why RFC 1034 Prohibits Standard CNAME Records at @: Under the DNS specification (RFC 1034 / RFC 1912), a CNAME record declares that a hostname is an alias for another name across all DNS record types, and prohibits any other record types from coexisting at that same node. Because the root domain (@) must hold mandatory NS (nameserver), SOA, and MX (email delivery for user@clientbusiness.com) records, placing a standard CNAME at @ would legally conflict with and break the client’s email and zone authority.
  • How We Onboard Root Domains (Without Enterprise Plans):
    1. Registrar CNAME Flattening (ALIAS / ANAME): If the client’s DNS provider supports apex flattening (e.g., AWS Route 53, Porkbun, DNSimple, or Cloudflare), the provider resolves our CNAME target behind the scenes and returns synthetic A/AAAA records at @, allowing the bare domain to point to SiteSwarm without conflicting with MX email records.
    2. Canonical www with Registrar Redirect: On registrars that do not support apex flattening (such as GoDaddy or Namecheap), www.clientbusiness.com is configured as the CNAME pointing to SiteSwarm, and the registrar’s root forwarding redirects clientbusiness.com $\to$ https://www.clientbusiness.com.

4. Clients on Their Own Cloudflare Account: Grey Cloud vs. O2O, Resilience & Routing

When a client already manages their domain inside their own independent Cloudflare account, their domain is a separate Cloudflare Zone from SiteSwarm’s platform zone. Pointing their CNAME to SiteSwarm crosses two Cloudflare zones, and how Cloudflare routes the request depends on whether the client sets their CNAME record to Grey Cloud (DNS-Only) or Orange Cloud (Proxied / O2O) in their own Cloudflare dashboard:

  • Grey Cloud (DNS-Only on Client Zone): The client’s Cloudflare zone acts purely as authoritative DNS. Visitor traffic goes directly to SiteSwarm’s Cloudflare zone in a single hop.
  • Orange-to-Orange (O2O — Orange Cloud on Both Zones): Visitor traffic passes through the client’s Cloudflare zone first (applying the client’s SSL settings, WAF, cache rules, and Workers) and is then handed off internally (tagged with the HTTP header cf-connecting-o2o: 1) to SiteSwarm’s Cloudflare zone second.

4.1 Why a Naive Single-Route Setup Breaks If a Client Toggles Orange/Grey Cloud

In Cloudflare’s Worker routing engine, specific hostname routes behave differently depending on the customer’s proxy toggle:

  • If a platform only binds a Custom Hostname Route (www.clientbusiness.com/*), Cloudflare invokes the Worker only when the client’s record is Grey Cloud (DNS-Only). If the client intentionally or accidentally clicks the Orange Cloud toggle in their Cloudflare dashboard, the Custom Hostname route stops matching and the site breaks!
  • Conversely, if a platform only binds a Target Hostname Route (<client>-ingress.<platform-domain>/*), Cloudflare invokes the Worker only when the client’s record is Orange Cloud (O2O) and fails when the client is Grey Cloud!

4.2 How SiteSwarm Achieves 100% Resilience to Both Modes (Dual-Route Binding)

To ensure that SiteSwarm never breaks if a client toggles between Grey Cloud and Orange Cloud on their own accord without coordinating with us:

  1. Per-Client CNAME Target Subdomain: Instead of having all clients point to a single undifferentiated fallback.<platform-domain> hostname, each client is assigned a dedicated CNAME target subdomain on our platform zone (<client>-ingress.<platform-domain>, which is a proxied CNAME pointing to fallback.<platform-domain>).
  2. Dual Worker Route Registration: Each client application (apps/<client>/wrangler.jsonc) binds both route patterns to its Worker:
    • Custom Hostname Route (www.clientbusiness.com/*): Matches when the client is on Grey Cloud (DNS-Only) or on a non-Cloudflare registrar (GoDaddy, Route 53, etc.).
    • Target Hostname Route (<client>-ingress.<platform-domain>/*): Matches when the client is on Cloudflare and toggles their CNAME to Orange Cloud (O2O).
Worker Route Bound to <client> Worker Client CNAME is Grey Cloud (or Non-Cloudflare DNS) Client CNAME is Orange Cloud (O2O) Combined Result for <client> Worker
Custom Hostname Route (www.clientbusiness.com/*) ✅ Invoked ❌ Bypassed ✅ Always Invoked in Both Modes
Target Hostname Route (<client>-ingress.<platform-domain>/*) ❌ Bypassed ✅ Invoked ✅ Always Invoked in Both Modes

4.3 Grey Cloud vs. O2O Trade-Offs & Platform Recommendation

Even though our dual-route architecture is resilient to both modes at the routing layer, Grey Cloud and O2O have important operational differences across speed, cache invalidation, and support risk:

Dimension Grey Cloud (DNS-Only on Client Zone) Orange-to-Orange (O2O — Proxied on Both Zones)
Speed / Latency Faster (Single-Zone Pipeline): Requests enter SiteSwarm’s zone directly and serve from SiteSwarm’s edge cache in one pass. Slower (Double-Zone Pipeline): Requests evaluate the client’s zone pipeline (WAF, rules, cache lookup) before handing off internally to SiteSwarm’s zone.
Direct Platform Cost Identical (\$0 difference): Uses the same Custom Hostname slot and Worker invocation billing on SiteSwarm’s account. Identical (\$0 difference): No extra Cloudflare fee to SiteSwarm, though higher indirect support cost if the client misconfigures their zone.
Instant CMS Cache Purge 100% Guaranteed: Only SiteSwarm’s zone caches the HTML, so SiteSwarm’s cache purge service (APP_SERVING_CACHE.md) invalidates stale pages globally in milliseconds. Stale Cache Risk if Client Caches HTML: Client zone settings execute before SiteSwarm’s zone. If the client adds a “Cache Everything” rule on their own Cloudflare account, SiteSwarm cannot purge the client’s external zone cache.
SSL & Rule Precedence 100% Controlled by SiteSwarm: SiteSwarm’s Custom Hostname TLS settings and WAF rules govern the connection cleanly. Client Zone Overrides Platform: If the client sets their zone SSL mode to Flexible (sending HTTP upstream), they can trigger infinite redirect loops (ERR_TOO_MANY_REDIRECTS), and client Page Rules/Workers can block traffic before it reaches SiteSwarm.
SSL Pre-Validation Supports Zero-Downtime TXT Pre-Validation: Certificate can be issued before CNAME cutover. Real-Time Validation Only: Because the client’s Orange Cloud intercepts pre-cutover checks, validation completes in real time once the CNAME is pointed.
  • Platform Recommendation: We recommend Grey Cloud (DNS-Only) by default during client onboarding for single-hop speed, guaranteed instant CMS cache invalidation, and immunity from client-side Flexible SSL or caching misconfigurations—while always deploying the Dual-Route Binding (www.clientbusiness.com/* + <client>-ingress.<platform-domain>/*) so that if a client flips the switch intentionally (e.g., to run their own WAF/Bot Management rules) or accidentally, their site stays online.

4.4 Why Native Worker Routes Are Used Instead of custom_origin_server or a Custom Proxy

  • Why custom_origin_server Is Bypassed: Cloudflare Custom Hostnames includes a per-hostname Custom Origin Server (custom_origin_server) setting (available at no extra cost on Free, Pro, and Business plans since May 2025). However, custom_origin_server only routes to traditional origin servers after the Worker layer—when a Zone Worker Route matches incoming traffic, the Worker handles the request before custom_origin_server resolution ever occurs.
  • No Hand-Rolled Reverse Proxy or Paid Dispatch Service: Because native Cloudflare Workers Routes on our platform zone route each client’s Custom Hostname and Target Hostname directly to that client’s Worker (apps/<client>), we do not need to maintain a custom router Worker or pay for the separate Workers for Platforms dispatch namespace service.

5. Cloudflare for Platforms & Custom Hostnames Pricing (Free Tier vs. One Plan Up)

Because SiteSwarm uses native Workers Routes with Custom Hostnames rather than untrusted third-party code sandboxes, we do not need the \$25/mo Workers for Platforms dispatch plan. At the zone level (<platform-domain>), Custom Hostnames pricing across the Free Zone Plan (\$0/mo) and One Plan Up (Pro Zone Plan — \$20/mo) is:

Feature / Quota Free Zone Plan (\$0/mo) One Plan Up: Pro Zone Plan (\$20/mo) Operational Notes
Included Custom Hostnames 100 Custom Hostnames Free 100 Custom Hostnames Free Requires a payment method on file to enable Custom Hostnames on a Free zone.
Additional Custom Hostnames \$0.10 / hostname / month \$0.10 / hostname / month Billed only past the first 100 hostnames. Hostnames count toward quota as soon as created (including pending_validation) until deleted.
Max Custom Hostnames 50,000 hostnames 50,000 hostnames Raised from 5,000 to 50,000 on self-serve plans in May 2025.
Custom Hostname SSL Certs \$0 (Included) \$0 (Included) Automatic DV certificate issuance and renewal per Custom Hostname.
Platform Universal SSL \$0 (Included) \$0 (Included) Covers <platform-domain> and single-level *.<platform-domain>. (Optional Advanced Certificate Manager for multi-level wildcards is \$10/mo/zone, avoided via <app>-staging.<platform-domain>).
Custom Origin Server \$0 (Included) \$0 (Included) Unlocked for Free and Pro plans in May 2025.

6. Related Runbooks & Implementation References