blackroad-operating-system/docs/CLOUDFLARE_MIGRATION_GUIDE.md

Cloudflare DNS Migration Guide

Complete Step-by-Step Guide for BlackRoad Domains

Version: 1.0 Date: 2025-11-18 Estimated Time: 2-4 hours for all domains Skill Level: Intermediate

---

Overview

This guide walks you through migrating BlackRoad domains from GoDaddy DNS to Cloudflare DNS. The migration provides:

• ✅ Free SSL certificates (automatic renewal)
• ✅ Global CDN (faster page loads worldwide)
• ✅ DDoS protection (automatic threat mitigation)
• ✅ Better DNS performance (anycast network)
• ✅ Advanced features (Workers, Zero Trust, edge functions)
• ✅ Superior analytics (traffic insights, security events)

What you'll need:

• Cloudflare account (free tier is sufficient)
• GoDaddy account with domain access
• 2-4 hours of time
• Basic command line familiarity (optional, for automation)

---

Table of Contents

1. Pre-Migration Checklist
2. Phase 1: Set Up Cloudflare Account
3. Phase 2: Add Domains to Cloudflare
4. Phase 3: Update Nameservers at GoDaddy
5. Phase 4: Configure DNS Records
6. Phase 5: Configure SSL/TLS
7. Phase 6: Optimize Performance
8. Phase 7: Verify Migration
9. Phase 8: Automation Setup (Optional)
10. Troubleshooting
11. Rollback Plan

---

Pre-Migration Checklist

Before starting, gather this information:

• GoDaddy credentials - Username and password
• Current DNS records - Document existing configuration
• Email access - For Cloudflare verification
• Railway hostname - Your production app URL (e.g., your-app.up.railway.app)
• Current uptime - Note if services are running properly

⚠️ Important Notes:

• Migration happens with zero downtime if done correctly
• DNS propagation takes 5-60 minutes (sometimes up to 24 hours)
• Keep GoDaddy account active (domain registration stays there)
• Only DNS management moves to Cloudflare

---

Phase 1: Set Up Cloudflare Account

Step 1.1: Create Cloudflare Account

1. Go to https://dash.cloudflare.com/sign-up
2. Enter your email address
3. Create a strong password
4. Verify your email address

Step 1.2: Two-Factor Authentication (Recommended)

1. Click on your profile (top right)
2. Go to My Profile → Authentication
3. Enable Two-Factor Authentication
4. Save backup codes in a secure location

Step 1.3: Get API Token

1. Go to My Profile → API Tokens
2. Click Create Token
3. Select Edit zone DNS template
4. Configure permissions:
   • Zone - DNS - Edit
   • Zone - Zone - Read
5. Select Specific zones → (you'll add zones in Phase 2)
6. Click Continue to summary → Create Token
7. Copy the token immediately (you won't see it again!)
8. Save it securely (we'll use it later for automation)

---

Phase 2: Add Domains to Cloudflare

We'll start with the primary domain (blackroad.systems) and then add others.

Step 2.1: Add blackroad.systems

1. From Cloudflare dashboard, click Add a site
2. Enter: blackroad.systems
3. Click Add site
4. Select Free plan → Click Continue
5. Cloudflare will scan existing DNS records from GoDaddy
6. Wait 30-60 seconds for scan to complete

Step 2.2: Review Scanned Records

Cloudflare should detect existing records. Review them:

• ✅ Check for A records pointing to your server
• ✅ Check for CNAME records
• ✅ Check for MX records (email)
• ✅ Check for TXT records (SPF, verification)

Common issues:

• Some records might be missing → We'll add them manually later
• TTL values might be high → We'll adjust them

Step 2.3: Get Nameservers

After scanning, Cloudflare will show 2 nameservers like:

aaaa.ns.cloudflare.com
bbbb.ns.cloudflare.com

⚠️ IMPORTANT: Copy these nameservers! You'll need them in Phase 3.

Don't click "Done" yet - we'll do that after updating nameservers at GoDaddy.

---

Phase 3: Update Nameservers at GoDaddy

⏰ Estimated Time: 10 minutes + 5-60 minutes propagation

Step 3.1: Log in to GoDaddy

1. Go to https://account.godaddy.com
2. Sign in with your credentials
3. Go to My Products → Domains

Step 3.2: Update Nameservers for blackroad.systems

1. Find blackroad.systems in your domain list
2. Click the three dots (...) → Manage DNS
3. Scroll down to Nameservers section
4. Click Change → Select Enter my own nameservers (advanced)
5. Remove existing nameservers
6. Add the 2 Cloudflare nameservers from Phase 2, Step 2.3:

   aaaa.ns.cloudflare.com
   bbbb.ns.cloudflare.com
   

7. Click Save
8. Confirm the change

What happens now:

• GoDaddy will propagate the nameserver change
• This takes 5-60 minutes (sometimes up to 24 hours)
• Your site will continue working during this time

Step 3.3: Return to Cloudflare

1. Go back to Cloudflare dashboard
2. Click Done, check nameservers
3. Cloudflare will start checking for nameserver changes
4. You'll see status: Pending Nameserver Update

⏳ Wait time: 5-60 minutes for Cloudflare to detect the change

You can check status by:

• Refreshing the Cloudflare dashboard
• Running: dig NS blackroad.systems (should show Cloudflare nameservers)
• Using: https://dnschecker.org

---

Phase 4: Configure DNS Records

Once Cloudflare shows Active status, configure DNS records.

Step 4.1: Verify Existing Records

1. In Cloudflare dashboard, go to DNS → Records
2. Review scanned records
3. Remove any incorrect or outdated records

Step 4.2: Add/Update Primary Records

Root Domain (blackroad.systems)

Type	Name	Target	Proxy	TTL
CNAME	@	your-app.up.railway.app	✅ Proxied	Auto

Steps:

1. Click Add record
2. Type: CNAME
3. Name: @ (represents root domain)
4. Target: your-railway-app.up.railway.app (replace with actual Railway URL)
5. Proxy status: Proxied (orange cloud icon)
6. TTL: Auto
7. Click Save

WWW Subdomain

Type	Name	Target	Proxy	TTL
CNAME	www	blackroad.systems	✅ Proxied	Auto

Steps:

1. Click Add record
2. Type: CNAME
3. Name: www
4. Target: blackroad.systems
5. Proxy status: Proxied
6. Click Save

API Subdomain

Type	Name	Target	Proxy	TTL
CNAME	api	your-app.up.railway.app	✅ Proxied	Auto

OS Subdomain

Type	Name	Target	Proxy	TTL
CNAME	os	blackroad.systems	✅ Proxied	Auto

Step 4.3: Configure Email Records (If Applicable)

If you use Google Workspace, G Suite, or custom email:

SPF Record

Type	Name	Content	TTL
TXT	@	v=spf1 include:_spf.google.com ~all	Auto

MX Records

Type	Name	Content	Priority	TTL
MX	@	aspmx.l.google.com	1	Auto
MX	@	alt1.aspmx.l.google.com	5	Auto
MX	@	alt2.aspmx.l.google.com	5	Auto

Step 4.4: Verify Records

# Check DNS resolution
dig blackroad.systems
dig www.blackroad.systems
dig api.blackroad.systems

# Or use Cloudflare dashboard DNS checker

---

Phase 5: Configure SSL/TLS

Step 5.1: Set Encryption Mode

1. In Cloudflare dashboard, go to SSL/TLS
2. Set Encryption mode to Full (strict)
   • This ensures encryption between Cloudflare and Railway
   • Railway automatically provides SSL certificates

⚠️ Important: Do NOT use "Flexible" mode (insecure)

Step 5.2: Enable Always Use HTTPS

1. Go to SSL/TLS → Edge Certificates
2. Enable Always Use HTTPS
   • This redirects all HTTP traffic to HTTPS
3. Enable Automatic HTTPS Rewrites
   • Fixes mixed content warnings

Step 5.3: Enable HSTS (Optional but Recommended)

1. Still in Edge Certificates
2. Enable HTTP Strict Transport Security (HSTS)
3. Configuration:
   • Max Age: 6 months (15768000 seconds)
   • Include subdomains: ✅ Enabled
   • Preload: ❌ Disabled (enable later when stable)
   • No-Sniff header: ✅ Enabled

⚠️ Warning: HSTS is irreversible for the max-age period. Only enable when confident.

Step 5.4: Enable TLS 1.3

1. Go to SSL/TLS → Edge Certificates
2. Minimum TLS Version: Set to TLS 1.2 (or 1.3 if supported)
3. TLS 1.3: ✅ Enabled

Step 5.5: Verify SSL Configuration

1. Visit: https://blackroad.systems
2. Click the padlock icon in browser
3. Verify certificate is valid and issued by Cloudflare
4. Check expiry date (should auto-renew)

Test with SSL Labs:

https://www.ssllabs.com/ssltest/analyze.html?d=blackroad.systems

---

Phase 6: Optimize Performance

Step 6.1: Configure Caching

1. Go to Caching → Configuration
2. Caching Level: Standard
3. Browser Cache TTL: Respect Existing Headers

Step 6.2: Enable Auto Minify

1. Go to Speed → Optimization
2. Enable Auto Minify:
   • ✅ JavaScript
   • ✅ CSS
   • ✅ HTML

Step 6.3: Enable Brotli Compression

1. Still in Speed → Optimization
2. Enable Brotli compression (better than gzip)

Step 6.4: Create Page Rules

1. Go to Rules → Page Rules
2. Create rule for API bypass:

Rule 1: API Cache Bypass

URL: *blackroad.systems/api/*
Settings:
  - Cache Level: Bypass

Rule 2: WWW Redirect

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

Note: Free plan allows 3 page rules. Use them wisely!

---

Phase 7: Verify Migration

Step 7.1: DNS Verification

# Check DNS propagation
dig blackroad.systems

# Check with multiple tools
dig @8.8.8.8 blackroad.systems
dig @1.1.1.1 blackroad.systems

# Or use online tool
# https://dnschecker.org

Expected results:

• Should resolve to Cloudflare IP addresses
• CNAME records should point to Railway
• Nameservers should be Cloudflare

Step 7.2: HTTP/HTTPS Verification

# Test HTTP → HTTPS redirect
curl -I http://blackroad.systems
# Should return: 301 Moved Permanently
# Location: https://blackroad.systems/

# Test HTTPS
curl -I https://blackroad.systems
# Should return: 200 OK

# Test WWW → apex redirect
curl -I https://www.blackroad.systems
# Should redirect to https://blackroad.systems

Step 7.3: SSL Certificate Check

# Check SSL certificate
openssl s_client -connect blackroad.systems:443 -servername blackroad.systems

# Look for:
# - Issuer: Cloudflare
# - Valid dates
# - No errors

Step 7.4: Application Functionality

1. Visit https://blackroad.systems
2. Test all major features:
   • Page loads correctly
   • No mixed content warnings
   • API calls work
   • Authentication works
   • Static assets load (CSS, JS, images)

Step 7.5: Automated Validation

# Use the validation script
cd /path/to/BlackRoad-Operating-System
python scripts/cloudflare/validate_dns.py --domain blackroad.systems

# This checks:
# - DNS resolution
# - SSL certificate validity
# - HTTP accessibility
# - Redirect configuration

---

Phase 8: Automation Setup (Optional)

Step 8.1: Install Script Dependencies

# Navigate to project
cd /path/to/BlackRoad-Operating-System

# Install Python dependencies
pip install -r scripts/cloudflare/requirements.txt

Step 8.2: Set Up Environment Variables

# Create .env file (DO NOT COMMIT)
cat >> .env << EOF
CF_API_TOKEN=your-cloudflare-api-token
CF_ZONE_ID=your-zone-id
EOF

# Or add to shell profile
echo 'export CF_API_TOKEN="your-token"' >> ~/.bashrc
echo 'export CF_ZONE_ID="your-zone-id"' >> ~/.bashrc
source ~/.bashrc

Step 8.3: Update domains.yaml

Edit ops/domains.yaml to reflect your Cloudflare configuration:

domains:
  - name: "blackroad.systems"
    type: "root"
    provider: "cloudflare"
    mode: "dns"
    record:
      type: "CNAME"
      value: "your-actual-railway-app.up.railway.app"
      proxied: true

  - name: "blackroad.ai"
    type: "root"
    provider: "cloudflare"
    mode: "dns"
    record:
      type: "CNAME"
      value: "blackroad.systems"
      proxied: true

Step 8.4: Test Automation

# Dry run (shows what would change)
python scripts/cloudflare/sync_dns.py --dry-run

# Apply changes
python scripts/cloudflare/sync_dns.py

# Validate
python scripts/cloudflare/validate_dns.py --all

Step 8.5: Set Up GitHub Actions (Optional)

Add secrets to GitHub:

gh secret set CF_API_TOKEN
gh secret set CF_ZONE_ID

Create workflow file (.github/workflows/sync-cloudflare-dns.yml):

name: Sync Cloudflare DNS

on:
  push:
    paths:
      - 'ops/domains.yaml'
    branches:
      - main

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install -r scripts/cloudflare/requirements.txt
      - run: python scripts/cloudflare/sync_dns.py
        env:
          CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}

---

Troubleshooting

Issue: DNS Not Resolving

Symptoms: dig blackroad.systems returns no results

Causes:

• Nameservers not updated at GoDaddy
• DNS propagation not complete
• Records not configured in Cloudflare

Solutions:

1. Check nameservers at GoDaddy
2. Wait 5-60 minutes for propagation
3. Check Cloudflare zone status (should be "Active")
4. Verify DNS records exist in Cloudflare

Issue: SSL Certificate Errors

Symptoms: Browser shows "Not Secure" or certificate warning

Causes:

• SSL/TLS mode incorrect
• Railway app doesn't have valid certificate
• Certificate provisioning in progress

Solutions:

1. Set SSL/TLS mode to "Full (strict)"
2. Verify Railway app has SSL
3. Wait 5-10 minutes for certificate provisioning
4. Clear browser cache and retry

Issue: Site Not Loading (403/502 Errors)

Symptoms: Site returns 403 Forbidden or 502 Bad Gateway

Causes:

• Railway app not running
• Incorrect CNAME target
• Cloudflare firewall blocking

Solutions:

1. Check Railway app status and logs
2. Verify CNAME points to correct Railway URL
3. Check Cloudflare firewall rules
4. Disable Cloudflare proxy temporarily (DNS-only) to test

Issue: Mixed Content Warnings

Symptoms: Some assets load as insecure (http://)

Causes:

• Hard-coded HTTP URLs in code
• External resources using HTTP

Solutions:

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

Issue: Email Not Working

Symptoms: Emails not sending/receiving

Causes:

• MX records not migrated
• SPF/DKIM records missing

Solutions:

1. Add MX records in Cloudflare (from Phase 4.3)
2. Add SPF TXT record
3. Add DKIM records if using custom email
4. Verify with: dig MX blackroad.systems

---

Rollback Plan

If you need to revert to GoDaddy DNS:

Quick Rollback

1. Go to GoDaddy → Domains → blackroad.systems
2. Nameservers → Change to GoDaddy defaults
3. Wait 5-60 minutes for propagation
4. Site will revert to GoDaddy DNS

⚠️ Note: You can keep the Cloudflare account and try again later.

Gradual Rollback

If experiencing issues but want to keep trying:

1. In Cloudflare, change proxy status to DNS Only (gray cloud)
2. This bypasses Cloudflare's proxy but keeps DNS
3. Troubleshoot issues
4. Re-enable proxy when fixed

---

Next Steps After Migration

For All Remaining Domains

Repeat the process for:

• blackroad.ai
• blackroad.network
• blackroad.me
• lucidia.earth
• aliceqi.com
• blackroadqi.com
• roadwallet.com
• aliceos.io
• blackroadquantum.com

Pro tip: After doing blackroad.systems, the others are easier!

Monitoring and Maintenance

1. Set up monitoring:

   • Uptime monitoring (UptimeRobot, Pingdom)
   • SSL certificate expiry monitoring
   • Performance monitoring (Cloudflare Analytics)

2. Review quarterly:

   • DNS records (remove unused)
   • Page rules and caching
   • Security settings
   • Analytics and performance

3. Stay updated:

   • Review Cloudflare changelog
   • Test new features in sandbox
   • Keep API tokens rotated

---

Migration Checklist

Use this to track your progress:

Pre-Migration

• GoDaddy credentials ready
• Current DNS records documented
• Railway hostname confirmed
• Cloudflare account created

Cloudflare Setup

• API token generated and saved
• Domain added to Cloudflare
• DNS records scanned
• Nameservers noted

GoDaddy Update

• Nameservers updated at GoDaddy
• Change confirmed
• Propagation completed (zone shows "Active")

DNS Configuration

• Root domain CNAME added
• WWW subdomain added
• API subdomain added
• OS subdomain added
• Email records added (if applicable)

SSL/TLS

• Encryption mode set to Full (strict)
• Always Use HTTPS enabled
• Automatic HTTPS Rewrites enabled
• HSTS configured (optional)
• TLS 1.3 enabled

Performance

• Auto Minify enabled
• Brotli compression enabled
• Page rules configured
• Caching configured

Verification

• DNS resolution verified
• SSL certificate valid
• HTTP → HTTPS redirect working
• WWW → apex redirect working
• Site accessible and functional
• API endpoints working
• Email working (if applicable)

Automation (Optional)

• Python dependencies installed
• Environment variables set
• domains.yaml updated
• Automation scripts tested
• GitHub Actions configured (optional)

---

Resources

Documentation

• Cloudflare DNS Blueprint
• Scripts README
• Domain Configuration

External Links

• Cloudflare Dashboard
• Cloudflare API Docs
• DNS Checker Tool
• SSL Labs Test
• Railway Dashboard

Support

• Cloudflare Community: https://community.cloudflare.com/
• Railway Discord: https://discord.gg/railway
• BlackRoad GitHub Issues: https://github.com/blackboxprogramming/BlackRoad-Operating-System/issues

---

Congratulations! 🎉

You've successfully migrated to Cloudflare DNS. Your sites now benefit from:

• Global CDN and faster performance
• Free SSL with auto-renewal
• DDoS protection
• Advanced security features
• Better analytics and insights

Questions or issues? Check the troubleshooting section or open a GitHub issue.

---

Last Updated: 2025-11-18 Maintainer: BlackRoad DevOps Team Version: 1.0