morethanadiagnosis-hub/CLOUDFLARE_DNS_SETUP.md

# Cloudflare DNS Configuration Guide

**Domain**: mtd.runfoo.run
**Target**: nexus-vector (216.158.230.94 - PUBLIC IP)
**Job ID**: MTAD-IMPL-2025-11-18-CL
**Date**: 2025-11-18

---

## 🎯 QUICK START (5 minutes)

### What You Need
- Cloudflare account (free tier works great)
- Domain: mtd.runfoo.run
- Target IP: **216.158.230.94** (nexus-vector PUBLIC IP - NOT Tailscale!)

### 5-Step Setup

1. **Add domain to Cloudflare** (1 min)
2. **Change nameservers** (1 min)
3. **Add DNS records** (2 min)
4. **Configure SSL/TLS** (1 min)

**Total time**: ~5 minutes

---

## 📋 STEP-BY-STEP SETUP

### Step 1: Sign Up / Login to Cloudflare

1. Go to https://dash.cloudflare.com
2. Create account or login with existing credentials
3. You're now in the Cloudflare dashboard

### Step 2: Add Domain to Cloudflare

1. Click **"Add a site"** button
2. Enter domain: `mtd.runfoo.run`
3. Click **"Add site"**
4. Select **"Free"** plan (or your preferred plan)
5. Click **"Continue"**

Wait a few seconds for Cloudflare to scan your domain...

### Step 3: Review Existing DNS Records

Cloudflare will show existing DNS records. You should see something like:

```
Type    | Name              | Content          | TTL
--------|-------------------|------------------|--------
A       | mtd.runfoo.run    | 1.1.1.1          | Auto
```

**Delete or update existing records** - we'll create new ones.

Click on any existing record and delete it with the trash icon.

### Step 4: Change Nameservers (CRITICAL STEP)

Cloudflare shows you 2 nameservers:

```
ns1.cloudflare.com
ns2.cloudflare.com
```

**You must change nameservers at your domain registrar** (wherever you bought mtd.runfoo.run):

1. Log into your domain registrar (GoDaddy, Namecheap, etc.)
2. Find "Nameservers" or "DNS Management"
3. Replace existing nameservers with:
   ```
   ns1.cloudflare.com
   ns2.cloudflare.com
   ```
4. Save changes
5. Wait 10-48 hours for propagation (usually 30 min)

**You can verify propagation**:
```bash
# Run this command to check nameservers
nslookup -type=NS mtd.runfoo.run
# Should show: ns1.cloudflare.com, ns2.cloudflare.com
```

### Step 5: Add DNS Records in Cloudflare

In Cloudflare dashboard, click **"DNS"** in the left menu.

#### Add Main A Record

1. Click **"+ Add Record"**
2. Set:
   - **Type**: A
   - **Name**: mtd.runfoo.run (or just `@`)
   - **IPv4 address**: **216.158.230.94** (PUBLIC IP)
   - **TTL**: Auto (or 3600)
   - **Proxy status**: **Proxied** (orange cloud) ⭐ IMPORTANT
3. Click **"Save"**

#### Add WWW Subdomain (Optional)

1. Click **"+ Add Record"**
2. Set:
   - **Type**: A
   - **Name**: www
   - **IPv4 address**: **216.158.230.94** (PUBLIC IP)
   - **TTL**: Auto
   - **Proxy status**: **Proxied**
3. Click **"Save"**

Your DNS records should now look like:

```
Type | Name              | Content         | TTL  | Status
-----|-------------------|-----------------|----- |--------
A    | mtd.runfoo.run    | 216.158.230.94  | Auto | Proxied
A    | www               | 216.158.230.94  | Auto | Proxied
```

### Step 6: Configure SSL/TLS

1. Click **"SSL/TLS"** in left menu
2. Click **"Overview"**
3. Select **"Full (strict)"** mode

This ensures Cloudflare encrypts traffic between users and Cloudflare, and between Cloudflare and your origin (nexus-vector).

---

## 🔐 SSL/TLS Configuration Details

### SSL/TLS Modes Explained

| Mode | Cloudflare → Origin | Uses | Security |
|------|-------------------|------|----------|
| Off | No encryption | No | ⚠️ Not recommended |
| Flexible | No encryption | HTTP origin | ⚠️ Not recommended |
| Full | Self-signed OK | Any | ✅ Recommended |
| Full (Strict) | Valid cert required | HTTPS origin | ✅✅ Best |

**We recommend: "Full (Strict)"** since your backend uses Let's Encrypt certificates.

### How to Set

1. Go to **SSL/TLS** → **Overview**
2. Select **"Full (strict)"**
3. Wait for automatic configuration

---

## 🚀 ADVANCED CLOUDFLARE SETTINGS

### Page Rules (Optional but Recommended)

1. Click **"Rules"** → **"Page Rules"**
2. Click **"Create Page Rule"**

#### Rule 1: Cache Everything for APIs

```
URL Pattern: mtd.runfoo.run/api/*
Actions:
  - Cache Level: Bypass
  - Browser Cache TTL: 30 minutes
```

This prevents caching of API responses (they change frequently).

#### Rule 2: Security for Admin

```
URL Pattern: mtd.runfoo.run/admin/*
Actions:
  - Security Level: High
  - Challenge: On
```

Adds CAPTCHA for admin endpoints.

### WAF (Web Application Firewall)

1. Click **"Security"** → **"WAF"**
2. Enable **"OWASP ModSecurity Core Ruleset"**

This protects against common web attacks (XSS, SQL injection, etc.).

### Rate Limiting

1. Click **"Security"** → **"Rate Limiting"**
2. Click **"Create Rate Limiting Rule"**

```
URL Pattern: mtd.runfoo.run/api/auth/*
Threshold: 10 requests per 10 seconds
Action: Block for 10 minutes
```

This prevents brute force attacks on authentication.

---

## ✅ VERIFICATION CHECKLIST

After setup, verify everything:

### 1. DNS Propagation
```bash
# Check if nameservers updated (may take up to 48 hours)
nslookup -type=NS mtd.runfoo.run

# Should show:
# nameserver = ns1.cloudflare.com
# nameserver = ns2.cloudflare.com
```

### 2. A Record Resolution
```bash
# Check if A record points to correct IP
nslookup mtd.runfoo.run

# Should show:
# Address: 216.158.230.94
```

### 3. HTTPS Accessibility
```bash
# Check if HTTPS works
curl -I https://mtd.runfoo.run/health

# Should return 200 OK and security headers
```

### 4. Cloudflare Dashboard Checks

In Cloudflare dashboard:

- [ ] Domain shows "Active" (green checkmark)
- [ ] A records show as "Proxied" (orange cloud)
- [ ] SSL/TLS mode is "Full (Strict)"
- [ ] No DNS errors
- [ ] Traffic showing as proxied through Cloudflare

### 5. API Endpoint Test
```bash
curl -I https://mtd.runfoo.run/api/v1/health

# Expected response:
# HTTP/2 200 OK
# server: cloudflare
# cf-ray: <ray-id>
# content-type: application/json
```

---

## 🔧 COMMON ISSUES & FIXES

### Issue: "DNS SERVFAIL" Error

**Cause**: Nameservers not updated yet

**Fix**:
1. Wait 24 hours for DNS propagation
2. Verify nameservers were changed at registrar
3. Use online tool to check: https://mxtoolbox.com/

### Issue: "SSL Certificate Error"

**Cause**: SSL/TLS mode mismatch

**Fix**:
1. Go to SSL/TLS → Overview
2. Change to "Full (strict)"
3. Wait 5 minutes for certificate validation
4. Try HTTPS connection again

### Issue: Origin Server Unreachable

**Cause**: Cloudflare can't reach backend

**Fix**:
1. Verify backend is running on 100.95.3.92
2. Check firewall allows Cloudflare IPs
3. Try accessing directly: `curl -I https://100.95.3.92/health`
4. Add Cloudflare IP ranges to firewall whitelist:

```bash
# Cloudflare IPv4 ranges (whitelist these)
103.21.244.0/22
103.22.200.0/22
103.31.4.0/22
# ... (complete list: https://www.cloudflare.com/ips/)
```

### Issue: Timeout Errors

**Cause**: Cloudflare timeout settings too low

**Fix**:
1. Go to **Network** → **Timeout**
2. Set to **30 seconds** or higher
3. Save

### Issue: "Too Many Redirects"

**Cause**: HTTP to HTTPS redirect loop

**Fix**:
1. Ensure backend sends proper headers
2. Don't create redirect rules in Cloudflare
3. Let Cloudflare handle HTTPS automatically

---

## 📊 CLOUDFLARE SETTINGS SUMMARY

### Recommended Configuration

```
DNS:
├── A Record: mtd.runfoo.run → 100.95.3.92 (Proxied)
├── A Record: www → 100.95.3.92 (Proxied)
└── CNAME: api → mtd.runfoo.run (Proxied)

SSL/TLS:
├── Mode: Full (Strict)
├── Minimum TLS Version: 1.2
└── Certificate: Auto-managed by Cloudflare

Security:
├── WAF: OWASP ModSecurity Core Ruleset Enabled
├── DDoS Protection: Advanced
├── Rate Limiting: 10 req/10s on /api/auth/*
└── Bot Management: Challenge (free tier)

Performance:
├── Caching: Default
├── Minify: JavaScript, CSS, HTML
├── Brotli Compression: Enabled
└── HTTP/2: Enabled

Rules:
├── Cache Bypass: /api/* (no caching)
├── Security High: /admin/* (CAPTCHA enabled)
└── Always HTTPS: Enabled
```

---

## 🌍 CUSTOM SUBDOMAIN SETUP (Optional)

If you want subdomains like `api.mtd.runfoo.run`:

### Add Subdomain A Record

1. In DNS menu, click **"+ Add Record"**
2. Set:
   - **Type**: A
   - **Name**: api
   - **IPv4 address**: **216.158.230.94** (PUBLIC IP)
   - **Proxy status**: Proxied
3. Click **"Save"**

Now `api.mtd.runfoo.run` will work!

### Common Subdomains to Add

```
api.mtd.runfoo.run         → 216.158.230.94 (API endpoints)
admin.mtd.runfoo.run       → 216.158.230.94 (Admin panel)
docs.mtd.runfoo.run        → 216.158.230.94 (API docs)
status.mtd.runfoo.run      → 216.158.230.94 (Status page)
```

---

## 📈 MONITORING CLOUDFLARE

### View Analytics

1. Click **"Analytics"** in left menu
2. See real-time metrics:
   - Requests (cached vs uncached)
   - Bandwidth saved
   - Security events
   - Performance metrics

### Set Up Alerts

1. Click **"Notifications"**
2. Click **"Alert Policy"**
3. Create alerts for:
   - Origin server down
   - High error rate
   - High traffic spike
   - SSL/TLS certificate expiring

---

## 🚀 NEXT STEPS AFTER DNS SETUP

### 1. Verify Everything Works (immediately)
```bash
# Test HTTP redirect to HTTPS
curl -I http://mtd.runfoo.run
# Should redirect to HTTPS

# Test HTTPS
curl -I https://mtd.runfoo.run/health
# Should return 200 OK
```

### 2. Update Backend Configuration (if needed)

In `/srv/containers/mtad-api/.env`:

```bash
# Add Cloudflare origin verification
TRUSTED_PROXIES=["0.0.0.0/0"]  # Trust Cloudflare headers
```

### 3. Deploy Backend (if not done)

Follow `DEPLOYMENT_GUIDE.md` to deploy FastAPI backend.

### 4. Test Full Flow

```bash
# Signup
curl -X POST https://mtd.runfoo.run/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","display_name":"Test User"}'

# Login
curl -X POST https://mtd.runfoo.run/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'
```

---

## 💡 CLOUDFLARE PRO TIPS

### Tip 1: Use Cloudflare Page Rules Wisely
- Don't cache API endpoints (use Cache Level: Bypass)
- Cache static assets aggressively (1 month TTL)
- Use robots.txt to control crawling

### Tip 2: Monitor Origin Performance
- Check Analytics → Origin status
- Cloudflare shows if origin is slow/down
- Adjust timeouts if needed

### Tip 3: Use Cloudflare Workers (Advanced)
- Create serverless functions at edge
- Redirect traffic, modify headers, etc.
- Free tier includes 100,000 requests/day

### Tip 4: Enable Auto HTTPS Rewrites
- In SSL/TLS → Edge Certificates
- Enable "Automatic HTTPS Rewrites"
- Fixes mixed content warnings

### Tip 5: Use Cloudflare Tunnel (Advanced)
- Instead of exposing IP directly
- Securely connect origin behind NAT
- Premium feature but very secure

---

## 📋 CLOUDFLARE SETUP CHECKLIST

Before considering DNS fully configured:

- [ ] Domain added to Cloudflare
- [ ] Nameservers changed at registrar
- [ ] A record created (mtd.runfoo.run → 100.95.3.92)
- [ ] A record set to "Proxied" (orange cloud)
- [ ] SSL/TLS mode set to "Full (strict)"
- [ ] DNS propagation verified (nslookup works)
- [ ] HTTPS accessible (curl https://mtd.runfoo.run works)
- [ ] API endpoints responding (curl https://mtd.runfoo.run/api/v1/health works)
- [ ] WAF rules enabled
- [ ] Rate limiting configured
- [ ] SSL certificate valid (https://crt.sh or browser check)
- [ ] Analytics showing traffic
- [ ] Alerts configured

---

## 🔄 TROUBLESHOOTING FLOW

```
Problem occurs
    ↓
Check Cloudflare Dashboard
    ↓
Is domain "Active"?
    ├─ No → Verify nameservers changed at registrar
    └─ Yes ↓
Check DNS record
    ↓
Is A record correct (100.95.3.92)?
    ├─ No → Edit A record to 100.95.3.92
    └─ Yes ↓
Is A record "Proxied"?
    ├─ No → Click record, toggle to Proxied
    └─ Yes ↓
Check SSL/TLS mode
    ↓
Is mode "Full (strict)"?
    ├─ No → Change to Full (strict)
    └─ Yes ↓
Is backend running?
    ├─ No → Deploy backend (see DEPLOYMENT_GUIDE.md)
    └─ Yes ↓
Test connectivity
    ↓
Can you curl https://mtd.runfoo.run/health?
    ├─ No → Check firewall, backend logs
    └─ Yes ↓
✅ Cloudflare DNS configured!
```

---

## 📞 SUPPORT RESOURCES

- **Cloudflare Docs**: https://developers.cloudflare.com
- **DNS Propagation Checker**: https://mxtoolbox.com
- **SSL Checker**: https://www.ssllabs.com/ssltest
- **Status Page**: https://www.cloudflarestatus.com

---

## 🎯 WHAT HAPPENS AFTER SETUP

Once Cloudflare DNS is configured:

1. **All traffic routes through Cloudflare**
   - Users → Cloudflare → nexus-vector (100.95.3.92)

2. **HTTPS is automatic**
   - Cloudflare provides SSL/TLS
   - Your backend also has SSL/TLS (Let's Encrypt)
   - Double encryption for maximum security

3. **Security features active**
   - DDoS protection
   - WAF protection
   - Rate limiting
   - Bot protection

4. **Performance optimized**
   - CDN caching
   - Automatic compression
   - HTTP/2 enabled
   - Global edge network

5. **Monitoring enabled**
   - Real-time analytics
   - Performance metrics
   - Security events
   - Uptime monitoring

---

## ✅ SUCCESS CRITERIA

You'll know DNS is properly configured when:

✅ `nslookup mtd.runfoo.run` shows `216.158.230.94`
✅ `curl https://mtd.runfoo.run/health` returns 200 OK
✅ `curl https://mtd.runfoo.run/api/v1/health` returns API response
✅ Browser shows padlock icon (HTTPS)
✅ Cloudflare dashboard shows "Active" domain
✅ Analytics show incoming traffic
✅ SSL certificate is valid

---

**Status**: Ready for Cloudflare configuration
**Estimated Time**: 5-10 minutes setup + 24-48 hours propagation
**Difficulty**: Easy (beginner-friendly)
**Support**: Cloudflare has excellent documentation

---

**Job ID**: MTAD-IMPL-2025-11-18-CL
**Last Updated**: 2025-11-18
**Domain**: mtd.runfoo.run
**Target**: nexus-vector (216.158.230.94 - PUBLIC IP)

**Ready to configure Cloudflare? Start with Step 1! 🚀**