Skip to content

Harrier Domain Setup

This guide covers the manual setup for the two first Harrier public surfaces:

harrier.theplatformlayer.com        Product website
docs.harrier.theplatformlayer.com   Documentation site

The recommended setup uses Cloudflare as the authoritative DNS provider and Cloudflare Pages for hosting. theplatformlayer.com should be active in Cloudflare before the Harrier custom domains are added.

Target Architecture

Surface Cloudflare Pages project Default Pages URL Custom domain
Product website harrier-site harrier-site.pages.dev harrier.theplatformlayer.com
Docs site harrier-docs harrier-docs.pages.dev docs.harrier.theplatformlayer.com

Before You Start

Confirm these are available:

  • Access to the Cloudflare account that will host Pages projects.
  • Cloudflare DNS access for theplatformlayer.com.
  • GitHub repository access for the-platform-layer/harrier-emr-mcp.
  • Optional GitHub secrets for automated deploys:

text CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_ZONE_ID

Step 1: Create The Website Pages Project

In Cloudflare:

  1. Open Workers & Pages.
  2. Select Create application.
  3. Select Pages.
  4. Connect GitHub.
  5. Choose:

text the-platform-layer/harrier-emr-mcp

  1. Configure the project:
Setting Value
Project name harrier-site
Production branch main
Root directory website
Build command npm run build
Build output directory dist
  1. Deploy once.
  2. Confirm the default Pages URL works:

text https://harrier-site.pages.dev

Step 2: Create The Docs Pages Project

In Cloudflare:

  1. Open Workers & Pages.
  2. Select Create application.
  3. Select Pages.
  4. Connect the same GitHub repository:

text the-platform-layer/harrier-emr-mcp

  1. Configure the project:
Setting Value
Project name harrier-docs
Production branch main
Root directory repository root
Build command python -m pip install -r docs/requirements.txt && python -m mkdocs build --strict
Build output directory site
  1. Deploy once.
  2. Confirm the default Pages URL works:

text https://harrier-docs.pages.dev

Step 3: Add Cloudflare Pages Custom Domains

In the harrier-site Pages project:

  1. Open Custom domains.
  2. Add:

text harrier.theplatformlayer.com

In the harrier-docs Pages project:

  1. Open Custom domains.
  2. Add:

text docs.harrier.theplatformlayer.com

Cloudflare will wait for DNS records before the custom domains become active.

Step 4: Add Cloudflare DNS Records

In Cloudflare:

  1. Open Websites.
  2. Select:

text theplatformlayer.com

  1. Open DNS.
  2. Add or update these records:
Type Name Target Proxy status
CNAME harrier harrier-site.pages.dev DNS only first
CNAME docs.harrier harrier-docs.pages.dev DNS only first

Do not include https:// in the CNAME value.

Step 5: Verify DNS

Run:

dig harrier.theplatformlayer.com CNAME +short
dig docs.harrier.theplatformlayer.com CNAME +short

Expected output:

harrier-site.pages.dev.
harrier-docs.pages.dev.

DNS changes can take a few minutes. If older records existed for either name, propagation may take longer.

Step 6: Verify HTTPS

After Cloudflare marks both custom domains as active, run:

curl -I https://harrier.theplatformlayer.com
curl -I https://docs.harrier.theplatformlayer.com

Expected:

HTTP/2 200

or a successful HTTP/3/HTTP/2 response depending on the client.

Step 7: Enable GitHub Deploy Workflows

The repository has two deployment workflows:

Workflow Cloudflare Pages project Domain
.github/workflows/deploy-website.yml harrier-site harrier.theplatformlayer.com
.github/workflows/deploy-docs.yml harrier-docs docs.harrier.theplatformlayer.com

Add these GitHub repository secrets:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

Recommended token permission:

Account / Cloudflare Pages / Edit

Then run the workflows manually once from GitHub Actions, or push a change under website/ or docs/.

Optional Automation

The repository includes dry-run-first scripts for repeatable domain setup.

Show the full plan without making changes:

make domain-plan

This runs:

scripts/domain/configure-cloudflare-dns.sh
scripts/domain/configure-cloudflare-pages-domain.sh

Apply Cloudflare Pages custom domains:

export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ACCOUNT_ID="..."
APPLY=1 scripts/domain/configure-cloudflare-pages-domain.sh

Apply Cloudflare DNS CNAME records:

export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ZONE_ID="..."
APPLY=1 scripts/domain/configure-cloudflare-dns.sh

Verify DNS and HTTPS:

make domain-verify

If DNS is still propagating and you only want to check CNAME records:

VERIFY_HTTPS=0 scripts/domain/verify-harrier-domains.sh

Script defaults:

Variable Default Purpose
DOMAIN theplatformlayer.com Root domain used to derive Harrier hostnames
APPLY 0 Dry-run mode unless set to 1
TTL 1 Cloudflare automatic TTL
PROXIED false Create DNS-only CNAME records first
VERIFY_HTTPS 1 Also check HTTPS endpoints during verification

The automation assumes the Cloudflare Pages projects already exist:

harrier-site
harrier-docs

GoDaddy Registrar Versus Cloudflare DNS

GoDaddy remains the domain registrar, but Cloudflare is authoritative for DNS after the nameserver delegation. DNS records for Harrier should be created in Cloudflare, not GoDaddy.

That setup lets Cloudflare Pages validate custom domains and keeps future DNS automation in the Cloudflare API.

Troubleshooting

Symptom Likely Cause Fix
Cloudflare custom domain stays pending Cloudflare CNAME is missing, misspelled, or points to the wrong Pages project Recheck the CNAME Name and Target fields in Cloudflare DNS
dig returns no result DNS record has not propagated or was added under the wrong name Confirm harrier and docs.harrier are the exact Cloudflare DNS names
dig returns a different target An old DNS record still exists Delete or replace the old record
Browser shows an SSL error Cloudflare certificate is still being issued Wait and retry after Cloudflare marks the custom domain active
Cloudflare returns an unexpected site The custom domain was attached to the wrong Pages project Remove and re-add it to the correct Pages project
Website deploy succeeds but domain shows older content Browser/CDN cache or old deployment Check Cloudflare Pages deployment history and hard-refresh
GitHub workflow fails during deploy Missing or under-scoped Cloudflare token Check CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and token permissions

Manual Checklist

  • [ ] harrier-site Pages project created.
  • [ ] harrier-docs Pages project created.
  • [ ] https://harrier-site.pages.dev loads.
  • [ ] https://harrier-docs.pages.dev loads.
  • [ ] harrier.theplatformlayer.com added to harrier-site.
  • [ ] docs.harrier.theplatformlayer.com added to harrier-docs.
  • [ ] Cloudflare CNAME harrier -> harrier-site.pages.dev added.
  • [ ] Cloudflare CNAME docs.harrier -> harrier-docs.pages.dev added.
  • [ ] dig returns both expected CNAMEs.
  • [ ] Both custom domains load over HTTPS.
  • [ ] GitHub deployment secrets are configured.
  • [ ] Deploy workflows have run successfully.