blackroad-operating-system/infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md

Cloudflare DNS Blueprint

Complete DNS Configuration for BlackRoad Universe

Version: 1.0 Date: 2025-11-18 Purpose: Canonical DNS configuration for all BlackRoad domains via Cloudflare

---

Overview

This document provides the complete DNS setup for migrating all BlackRoad domains from GoDaddy DNS to Cloudflare DNS.

Why Cloudflare?

• Free tier includes: DNS, SSL, CDN, DDoS protection, Web Analytics
• Global anycast network (faster DNS resolution)
• CNAME flattening (allows root domain CNAMEs to Railway)
• Better security (WAF, rate limiting available)
• Future-ready for Workers, Zero Trust, edge functions

---

Migration Process

Step 1: Add Domain to Cloudflare

For each domain:

1. Log in to Cloudflare dashboard
2. Click "Add a site"
3. Enter domain (e.g., blackroad.systems)
4. Select Free plan
5. Cloudflare auto-scans existing DNS records from GoDaddy
6. Review scanned records, make adjustments (see configurations below)
7. Cloudflare provides 2 nameservers (e.g., aaaa.ns.cloudflare.com, bbbb.ns.cloudflare.com)

Step 2: Update Nameservers at GoDaddy

For each domain:

1. Log in to GoDaddy
2. Go to My Domains → select domain → Manage DNS
3. Scroll to Nameservers section
4. Click Change → Select Custom
5. Enter Cloudflare nameservers (from Step 1)
6. Click Save
7. Wait 5-60 minutes for DNS propagation

Step 3: Verify & Configure SSL

1. Return to Cloudflare dashboard
2. Wait for status to change from "Pending" to "Active"
3. Go to SSL/TLS → Set encryption mode to "Full (strict)"
4. Go to SSL/TLS → Edge Certificates → Enable "Always Use HTTPS"
5. Enable "Automatic HTTPS Rewrites"
6. Enable "HTTP Strict Transport Security (HSTS)" (optional, but recommended)

Step 4: Optimize Performance

1. Go to Speed → Optimization
2. Enable Auto Minify (HTML, CSS, JS)
3. Enable Brotli compression
4. Enable Rocket Loader (optional - test first)
5. Go to Caching → Set Browser Cache TTL to "Respect Existing Headers"

---

DNS Records Configuration

Domain: blackroad.systems

Purpose: Flagship corporate site + OS application

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackroad-os-production.up.railway.app	Auto	✅ Proxied	Root domain → Railway (CNAME flattening)
CNAME	www	blackroad.systems	Auto	✅ Proxied	www redirects to apex
CNAME	os	blackroad.systems	Auto	✅ Proxied	Alternative OS alias
CNAME	api	blackroad-os-production.up.railway.app	Auto	✅ Proxied	Explicit API subdomain
CNAME	prism	blackroad-os-production.up.railway.app	Auto	✅ Proxied	Prism Console subdomain
CNAME	docs	blackboxprogramming.github.io	Auto	✅ Proxied	GitHub Pages for docs
CNAME	cdn	blackroad.systems	Auto	✅ Proxied	CDN alias (for future asset delivery)
TXT	@	v=spf1 include:_spf.google.com ~all	Auto	-	SPF record (if using Google Workspace)
MX	@	1 aspmx.l.google.com	Auto	-	Gmail MX (priority 1)
MX	@	5 alt1.aspmx.l.google.com	Auto	-	Gmail MX (priority 5)
MX	@	5 alt2.aspmx.l.google.com	Auto	-	Gmail MX (priority 5)

Page Rules (Optional):

• www.blackroad.systems/* → Forwarding URL (301) → https://blackroad.systems/$1

---

Domain: blackroad.ai

Purpose: Product console, admin interface

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	os.blackroad.systems	Auto	✅ Proxied	Alias to main OS
CNAME	www	blackroad.ai	Auto	✅ Proxied	www → apex redirect
CNAME	console	os.blackroad.systems	Auto	✅ Proxied	Explicit console subdomain

Page Rules:

• www.blackroad.ai/* → Forwarding URL (301) → https://blackroad.ai/$1

---

Domain: blackroad.network

Purpose: Developer hub, documentation, community

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackboxprogramming.github.io	Auto	✅ Proxied	GitHub Pages for docs
CNAME	www	blackroad.network	Auto	✅ Proxied	www → apex redirect
CNAME	api	blackroad-os-production.up.railway.app	Auto	✅ Proxied	API access for developers
CNAME	sandbox	blackroad-os-staging.up.railway.app	Auto	✅ Proxied	Staging/sandbox environment

CNAME File (for GitHub Pages): Create file CNAME in your docs/ or GitHub Pages root:

blackroad.network

Page Rules:

• www.blackroad.network/* → Forwarding URL (301) → https://blackroad.network/$1

---

Domain: blackroad.me

Purpose: Personal identity portal, Pocket OS

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	os.blackroad.systems	Auto	✅ Proxied	Identity portal via main OS
CNAME	www	blackroad.me	Auto	✅ Proxied	www → apex redirect
CNAME	id	os.blackroad.systems	Auto	✅ Proxied	Explicit identity subdomain

---

Domain: lucidia.earth

Purpose: Narrative experiences, interactive storytelling (Phase 2)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackboxprogramming.github.io	Auto	✅ Proxied	GitHub Pages (Phase 2)
CNAME	www	lucidia.earth	Auto	✅ Proxied	www → apex redirect
CNAME	studio	lucidia-studio.vercel.app	Auto	✅ Proxied	Lucidia Studio (Phase 3)

CNAME File (for GitHub Pages):

lucidia.earth

---

Domain: aliceqi.com

Purpose: ALICE QI research showcase (Phase 2)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackboxprogramming.github.io	Auto	✅ Proxied	GitHub Pages
CNAME	www	aliceqi.com	Auto	✅ Proxied	www → apex redirect
CNAME	research	aliceqi.com	Auto	✅ Proxied	Research portal
CNAME	docs	aliceqi.com	Auto	✅ Proxied	Technical documentation

---

Domain: blackroadqi.com

Purpose: Financial/quantitative intelligence product (Phase 2)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackroadqi-app.up.railway.app	Auto	✅ Proxied	Dedicated QI app (Phase 2)
CNAME	www	blackroadqi.com	Auto	✅ Proxied	www → apex redirect
CNAME	api	blackroadqi-api.up.railway.app	Auto	✅ Proxied	QI API endpoint

---

Domain: roadwallet.com

Purpose: Wallet interface (alias to OS)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	os.blackroad.systems	Auto	✅ Proxied	Alias to main OS wallet
CNAME	www	roadwallet.com	Auto	✅ Proxied	www → apex redirect

---

Domain: aliceos.io

Purpose: Legacy alias (points to main OS)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	os.blackroad.systems	Auto	✅ Proxied	Legacy domain
CNAME	www	aliceos.io	Auto	✅ Proxied	www → apex redirect

---

Domain: blackroadquantum.com

Purpose: Quantum research hub (Phase 2)

Type	Name	Target	TTL	Proxy	Notes
CNAME	@	blackboxprogramming.github.io	Auto	✅ Proxied	GitHub Pages
CNAME	www	blackroadquantum.com	Auto	✅ Proxied	www → apex redirect
CNAME	lab	quantum-lab.up.railway.app	Auto	✅ Proxied	Quantum Lab app (Phase 2)

---

Advanced Configuration

SSL/TLS Settings

For all domains:

1. Encryption Mode: Full (strict)

   • Cloudflare ↔ Railway: encrypted with valid cert

2. Edge Certificates:

   • ✅ Always Use HTTPS
   • ✅ Automatic HTTPS Rewrites
   • ✅ Certificate Transparency Monitoring
   • ✅ TLS 1.3 (enabled by default)

3. HSTS (HTTP Strict Transport Security):

   • ✅ Enable HSTS
   • Max Age: 6 months (15768000 seconds)
   • ✅ Include subdomains
   • ❌ Preload (wait until stable, then enable)

Caching Rules

Static Assets (CSS, JS, images):

Cache Level: Standard
Browser Cache TTL: Respect Existing Headers
Edge Cache TTL: 1 month

API Endpoints (/api/*):

Cache Level: Bypass
(Don't cache API responses)

Page Rules Example (blackroad.systems):

Rule 1: *blackroad.systems/api/*
  - Cache Level: Bypass
  - Disable Apps
  - Disable Performance

Rule 2: *blackroad.systems/*.css
  - Cache Level: Cache Everything
  - Edge Cache TTL: 1 month
  - Browser Cache TTL: 1 day

Rule 3: *blackroad.systems/*.js
  - Cache Level: Cache Everything
  - Edge Cache TTL: 1 month
  - Browser Cache TTL: 1 day

Rule 4: www.blackroad.systems/*
  - Forwarding URL: 301 redirect to https://blackroad.systems/$1

Firewall Rules

Block known bots (optional):

Field: User Agent
Operator: contains
Value: "BadBot|Scraper|AhrefsBot"
Action: Block

Rate Limiting (protect API):

Field: URI Path
Operator: starts with
Value: /api/
Rate: 100 requests per minute
Action: Challenge (CAPTCHA)

Security Headers

Via Cloudflare Workers (optional, advanced):

Create a Worker to add security headers:

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const response = await fetch(request)
  const newHeaders = new Headers(response.headers)

  // Security headers
  newHeaders.set('X-Frame-Options', 'DENY')
  newHeaders.set('X-Content-Type-Options', 'nosniff')
  newHeaders.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  newHeaders.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: newHeaders
  })
}

---

Verification Checklist

After DNS setup for each domain:

• DNS Propagation: Check with dig <domain> or https://dnschecker.org
• SSL Certificate: Visit https://<domain> - should show valid cert (🔒)
• WWW Redirect: Visit https://www.<domain> - should redirect to apex
• HTTP → HTTPS: Visit http://<domain> - should redirect to HTTPS
• API Endpoint: Test curl https://<domain>/health (if applicable)
• Cloudflare Analytics: Check Cloudflare dashboard → Analytics tab

---

Implementation Files

This blueprint is now implemented in the following files:

1. DNS Records Configuration

File: infra/cloudflare/records.yaml

This file is the single source of truth for all DNS records across all BlackRoad domains. It includes:

• Complete record definitions (type, name, content, TTL, proxy status)
• Domain metadata (zone ID, phase, priority)
• Human-readable comments for each record
• Organized by phase (Phase 1 active domains, Phase 2 future domains)

Quick reference: See records.yaml for the exact DNS configuration to apply.

2. Migration Guide

File: infra/cloudflare/migrate_to_cloudflare.md

A step-by-step guide for migrating DNS from GoDaddy to Cloudflare. Designed for human operators (Alexa) with:

• Detailed instructions with screenshots references
• Mobile-friendly (can be done from iPhone)
• Troubleshooting section
• Verification steps
• Checklist for tracking progress

Quick reference: Follow this guide to migrate each domain from GoDaddy DNS to Cloudflare DNS.

3. Automation Script

File: infra/cloudflare/cloudflare_dns_sync.py

An idempotent Python script that syncs DNS records from records.yaml to Cloudflare via API. Features:

• Reads structured YAML configuration
• Creates, updates, and optionally deletes DNS records
• Dry-run mode for safe testing
• Domain and phase filtering
• Comprehensive logging

Usage:

# Set Cloudflare API token
export CF_API_TOKEN="your-cloudflare-api-token"

# Dry run (safe - shows changes without applying)
python infra/cloudflare/cloudflare_dns_sync.py --dry-run

# Sync specific domain
python infra/cloudflare/cloudflare_dns_sync.py --domain blackroad.systems

# Sync all Phase 1 domains
python infra/cloudflare/cloudflare_dns_sync.py --phase 1

# Apply all changes
python infra/cloudflare/cloudflare_dns_sync.py

Requirements:

pip install pyyaml requests

How These Files Connect to Railway + GitHub

DNS → Railway Flow

1. Cloudflare DNS receives user request for os.blackroad.systems
2. CNAME record (from records.yaml) points to blackroad-os-production.up.railway.app
3. Cloudflare CDN proxies request (SSL, caching, DDoS protection)
4. Railway receives request and routes to FastAPI backend
5. FastAPI serves Pocket OS frontend from backend/static/

Railway Custom Domains

For each subdomain pointing to Railway, you must also:

1. Add the custom domain in Railway dashboard:

   • Service → Settings → Networking → Custom Domains
   • Add domain (e.g., os.blackroad.systems)
   • Railway auto-provisions SSL certificate (Let's Encrypt)

2. Wait for Railway to show green checkmark (SSL ready)

3. Verify: Visit https://os.blackroad.systems - should show valid SSL 🔒

GitHub Actions Integration

The DNS sync script can be automated via GitHub Actions:

Workflow file (create at .github/workflows/dns-sync.yml):

name: Sync Cloudflare DNS

on:
  push:
    paths:
      - 'infra/cloudflare/records.yaml'
  workflow_dispatch:

jobs:
  sync-dns:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install pyyaml requests

      - name: Sync DNS records
        env:
          CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
        run: |
          python infra/cloudflare/cloudflare_dns_sync.py --phase 1

Required GitHub Secrets:

• CF_API_TOKEN - Cloudflare API token with Zone.DNS edit permissions

How it works:

1. Push changes to records.yaml
2. GitHub Action runs automatically
3. Script syncs DNS records to Cloudflare
4. Changes are live within seconds

---

Troubleshooting

DNS Not Resolving

Problem: dig blackroad.systems returns no results

Solutions:

1. Check nameservers are updated at GoDaddy
2. Wait 5-60 minutes for propagation
3. Verify zone is "Active" in Cloudflare dashboard
4. Check DNS records exist in Cloudflare

SSL Certificate Errors

Problem: Browser shows "Not Secure" or certificate error

Solutions:

1. Check SSL/TLS mode is "Full (strict)" in Cloudflare
2. Verify Railway app has valid SSL cert
3. Check "Always Use HTTPS" is enabled
4. Wait a few minutes for edge certificate provisioning

Site Not Loading

Problem: Domain resolves but site doesn't load

Solutions:

1. Check Railway app is deployed and healthy
2. Verify custom domain is added in Railway dashboard
3. Check Railway logs for errors: railway logs --service backend
4. Test Railway URL directly (e.g., your-app.up.railway.app)

Mixed Content Warnings

Problem: Page loads but some assets show as insecure

Solutions:

1. Enable "Automatic HTTPS Rewrites" in Cloudflare
2. Update hard-coded http:// URLs to https:// in code
3. Use protocol-relative URLs: //example.com/asset.js

---

Maintenance

Monthly:

• Review Cloudflare analytics
• Check SSL certificate status
• Review firewall logs (if WAF enabled)

Quarterly:

• Audit DNS records (remove unused)
• Review page rules and caching
• Update security headers if needed

Annually:

• Review Cloudflare plan (consider Pro if traffic grows)
• Audit all domain registrations (renew at GoDaddy)
• Review and update security policies

---

References

• Cloudflare Docs: https://developers.cloudflare.com/dns/
• Railway Custom Domains: https://docs.railway.app/deploy/custom-domains
• DNS Checker: https://dnschecker.org
• SSL Labs Test: https://www.ssllabs.com/ssltest/

---

This blueprint ensures all BlackRoad domains are properly configured with Cloudflare for optimal performance, security, and reliability.