miracles_in_motion/docs/deployment/CLOUDFLARE_SETUP.md

# ☁️ Cloudflare Setup Guide for mim4u.org

This guide provides step-by-step instructions for configuring Cloudflare for the Miracles in Motion application.

---

## 📋 Prerequisites

- Cloudflare account
- Domain `mim4u.org` registered
- Access to domain registrar DNS settings
- Cloudflare API token (optional, for automation)

---

## 🚀 Step-by-Step Setup

### Step 1: Add Domain to Cloudflare

1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com)
2. Click **"Add a site"**
3. Enter your domain: `mim4u.org`
4. Select a plan (Free plan is sufficient)
5. Cloudflare will scan your existing DNS records

### Step 2: Update Nameservers

1. Cloudflare will provide you with nameservers (e.g., `ns1.cloudflare.com`, `ns2.cloudflare.com`)
2. Go to your domain registrar
3. Update nameservers to Cloudflare's nameservers
4. Wait for DNS propagation (24-48 hours, usually faster)

### Step 3: Configure DNS Records

Once nameservers are updated, configure DNS records:

#### Option A: Using Cloudflare Dashboard

1. Go to **DNS** → **Records**
2. Delete any existing A records for `@` (apex domain)
3. Add the following records:

| Type | Name | Content | Proxy Status | TTL |
|------|------|---------|---------------|-----|
| CNAME | www | lemon-water-015cb3010.3.azurestaticapps.net | ✅ **Proxied** | Auto |
| CNAME | @ | lemon-water-015cb3010.3.azurestaticapps.net | ⚠️ **DNS Only** | Auto |

**Important Notes:**
- For apex domain (`@`), Cloudflare uses CNAME Flattening automatically
- Set apex domain to **DNS Only** (gray cloud) initially for Azure validation
- After Azure validation, you can enable proxying (orange cloud)

#### Option B: Using Azure Static Web App Validation

If Azure requires TXT validation:

1. Get validation token from Azure:
   ```bash
   az staticwebapp hostname show \
     --name mim-prod-igiay4-web \
     --resource-group rg-miraclesinmotion-prod \
     --hostname "mim4u.org" \
     --query "validationToken" -o tsv
   ```

2. Add TXT record in Cloudflare:
   - **Type:** `TXT`
   - **Name:** `_asuid` or `asuid`
   - **Content:** (validation token from Azure)
   - **TTL:** Auto

### Step 4: Configure SSL/TLS

1. Go to **SSL/TLS** → **Overview**
2. Set encryption mode to **Full (strict)**
3. Enable **Always Use HTTPS**:
   - Go to **SSL/TLS** → **Edge Certificates**
   - Toggle **Always Use HTTPS** to ON
4. Enable **Automatic HTTPS Rewrites**:
   - Toggle **Automatic HTTPS Rewrites** to ON

### Step 5: Configure Page Rules

1. Go to **Rules** → **Page Rules**
2. Create the following rules:

**Rule 1: Force HTTPS**
- URL: `*mim4u.org/*`
- Settings:
  - Always Use HTTPS: ✅ ON
  - SSL: Full (strict)

**Rule 2: Cache Static Assets**
- URL: `*mim4u.org/assets/*`
- Settings:
  - Cache Level: Cache Everything
  - Edge Cache TTL: 1 month

**Rule 3: Cache JS/CSS**
- URL: `*mim4u.org/*.js` or `*mim4u.org/*.css`
- Settings:
  - Cache Level: Cache Everything
  - Edge Cache TTL: 1 week

### Step 6: Configure Security Settings

1. Go to **Security** → **Settings**
2. Configure:
   - **Security Level:** Medium
   - **Challenge Passage:** 30 minutes
   - **Browser Integrity Check:** ✅ On
   - **Privacy Pass Support:** ✅ On

### Step 7: Configure Firewall Rules

1. Go to **Security** → **WAF** → **Custom rules**
2. Create rules:

**Rule: Block Bad Bots**
- Expression: `(http.user_agent contains "bot" and not http.user_agent contains "Googlebot")`
- Action: Block

**Rule: Rate Limiting for API**
- Expression: `(http.request.uri.path contains "/api/")`
- Action: Challenge
- Rate: 100 requests per minute

### Step 8: Configure Speed Optimization

1. Go to **Speed** → **Optimization**
2. Enable:
   - ✅ Auto Minify (JavaScript, CSS, HTML)
   - ✅ Brotli compression
   - ✅ Rocket Loader (optional)
   - ✅ Mirage (optional, for mobile)

### Step 9: Configure Analytics

1. Go to **Analytics** → **Web Analytics**
2. Enable **Web Analytics** for your domain
3. (Optional) Add tracking script to your application

### Step 10: Add Custom Domain to Azure

After DNS is configured and validated:

```bash
# Add custom domain to Static Web App
az staticwebapp hostname set \
  --name mim-prod-igiay4-web \
  --resource-group rg-miraclesinmotion-prod \
  --hostname "mim4u.org"

az staticwebapp hostname set \
  --name mim-prod-igiay4-web \
  --resource-group rg-miraclesinmotion-prod \
  --hostname "www.mim4u.org"
```

---

## ✅ Verification Steps

### 1. Verify DNS Resolution

```bash
# Check DNS records
dig mim4u.org
dig www.mim4u.org

# Check CNAME
dig www.mim4u.org CNAME

# Check Cloudflare proxy status
curl -I https://mim4u.org | grep -i "cf-"
```

Expected headers:
- `CF-Cache-Status: DYNAMIC`
- `CF-Ray: [unique-id]`
- `Server: cloudflare`

### 2. Verify SSL/TLS

```bash
# Test HTTPS
curl -I https://mim4u.org

# Check SSL certificate
openssl s_client -connect mim4u.org:443 -servername mim4u.org
```

### 3. Verify Cloudflare Configuration

```bash
# Test Cloudflare headers
curl -I https://mim4u.org | grep -i "cf-"

# Test caching
curl -I https://mim4u.org/assets/ | grep -i "cf-cache"
```

---

## 🔧 Automation (Optional)

### Using Cloudflare API

If you have a Cloudflare API token:

```bash
# Set environment variables
export CLOUDFLARE_API_TOKEN="your-api-token"
export CLOUDFLARE_ZONE_ID="your-zone-id"

# Create CNAME record via API
curl -X POST "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "CNAME",
    "name": "www",
    "content": "lemon-water-015cb3010.3.azurestaticapps.net",
    "proxied": true
  }'
```

---

## ⚠️ Important Notes

1. **DNS Propagation:** Changes can take 24-48 hours to propagate globally
2. **SSL Certificate:** Azure will automatically provision SSL certificates after DNS validation
3. **CNAME Flattening:** Cloudflare automatically handles CNAME flattening for apex domains
4. **Proxy Status:** Keep apex domain as DNS Only until Azure validation completes
5. **Cache Purging:** Use Cloudflare dashboard to purge cache when deploying updates

---

## 🔍 Troubleshooting

### Issue: DNS not resolving
- **Solution:** Wait for DNS propagation (up to 48 hours)
- Check nameservers are correctly set at registrar
- Verify DNS records in Cloudflare dashboard

### Issue: SSL certificate errors
- **Solution:** Ensure SSL mode is "Full (strict)"
- Verify DNS records are correct
- Wait for Azure SSL certificate provisioning

### Issue: Site not loading through Cloudflare
- **Solution:** Check proxy status (should be orange cloud for www)
- Verify CNAME records point to correct Azure endpoint
- Check Cloudflare firewall rules

### Issue: Cache not updating
- **Solution:** Purge cache in Cloudflare dashboard
- Adjust cache TTL settings
- Use cache rules for specific paths

---

## 📊 Performance Optimization

### Recommended Settings:

1. **Caching:**
   - Static assets: Cache Everything (1 month)
   - HTML: Bypass Cache
   - API endpoints: Bypass Cache

2. **Compression:**
   - Enable Brotli compression
   - Enable Gzip compression

3. **Minification:**
   - Auto Minify JavaScript
   - Auto Minify CSS
   - Auto Minify HTML

4. **Image Optimization:**
   - Enable Polish (if on paid plan)
   - Enable WebP conversion

---

## 📝 Current Status

- **Cloudflare Account:** ⚠️ Needs to be created/configured
- **DNS Records:** ⚠️ Pending configuration
- **SSL/TLS:** ⚠️ Pending (will be automatic after DNS)
- **Azure Integration:** ✅ Ready

---

**Next Steps:**
1. Create/access Cloudflare account
2. Add domain to Cloudflare
3. Update nameservers at registrar
4. Configure DNS records
5. Set up SSL/TLS and security settings
6. Add custom domain to Azure Static Web App