snippet-pastebin/docs/DEPLOYMENT.md

CapRover / Cloudflare Deployment Guide

This guide explains how to deploy CodeSnippet with separate frontend and backend domains using CapRover and Cloudflare.

Architecture

┌─────────────────────────────────────────────┐
│          Cloudflare DNS & Proxy             │
│  https://frontend.example.com               │
│  https://backend.example.com                │
└─────────────┬───────────────────────────────┘
              │
              │ HTTPS (Cloudflare SSL)
              │
┌─────────────▼───────────────────────────────┐
│             CapRover Server                 │
│                                             │
│  ┌──────────────┐      ┌─────────────────┐ │
│  │   Frontend   │      │    Backend      │ │
│  │   (Nginx)    │      │    (Flask)      │ │
│  │   Port 3000  │      │   Port 5000     │ │
│  └──────────────┘      └─────────────────┘ │
└─────────────────────────────────────────────┘

Prerequisites

1. CapRover server installed and configured
2. Domain name configured in Cloudflare
3. DNS records pointing to your CapRover server
4. CapRover CLI installed: npm install -g caprover

Step 1: Configure DNS in Cloudflare

Add these DNS records in Cloudflare:

Type	Name	Content	Proxy Status
A	frontend	YOUR_CAPROVER_IP	Proxied
A	backend	YOUR_CAPROVER_IP	Proxied

Important: Enable "Proxied" (orange cloud) to use Cloudflare's CDN and SSL.

Step 2: Deploy Backend to CapRover

Create Backend App

1. Login to CapRover dashboard
2. Go to "Apps" → "One-Click Apps/Databases"
3. Create a new app named codesnippet-backend
4. Enable "Has Persistent Data" and set persistent directory to /app/data

Configure Backend Environment Variables

In the backend app settings, add these environment variables:

CORS_ALLOWED_ORIGINS=https://frontend.example.com
DATABASE_PATH=/app/data/snippets.db

Deploy Backend Code

From the backend directory:

cd backend
caprover deploy -a codesnippet-backend

Enable HTTPS for Backend

1. In CapRover dashboard → Apps → codesnippet-backend
2. Go to "HTTP Settings"
3. Enable "HTTPS"
4. Connect domain: backend.example.com
5. Enable "Force HTTPS by redirecting all HTTP traffic to HTTPS"
6. Wait for SSL certificate to be issued

Step 3: Deploy Frontend to CapRover

Create Frontend App

1. In CapRover dashboard, create new app: codesnippet-frontend
2. No persistent data needed for frontend

Configure Frontend Environment Variables

In the frontend app settings, add:

VITE_FLASK_BACKEND_URL=https://backend.example.com

Deploy Frontend Code

From the project root:

caprover deploy -a codesnippet-frontend

Enable HTTPS for Frontend

1. In CapRover dashboard → Apps → codesnippet-frontend
2. Go to "HTTP Settings"
3. Enable "HTTPS"
4. Connect domain: frontend.example.com
5. Enable "Force HTTPS by redirecting all HTTP traffic to HTTPS"
6. Wait for SSL certificate to be issued

Step 4: Configure Cloudflare Settings

SSL/TLS Settings

1. Go to Cloudflare dashboard → SSL/TLS
2. Set encryption mode to "Full (strict)"
3. Enable "Always Use HTTPS"
4. Enable "Automatic HTTPS Rewrites"

Security Settings

1. Go to Security → WAF
2. Consider enabling Bot Fight Mode for backend
3. Set up rate limiting rules if needed

Speed Settings

1. Enable "Auto Minify" for JavaScript, CSS, HTML
2. Enable "Brotli" compression
3. Set Browser Cache TTL appropriately

Step 5: Verify Deployment

Test Backend

curl https://backend.example.com/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Test CORS

curl -H "Origin: https://frontend.example.com" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS \
     https://backend.example.com/api/snippets

Should return CORS headers:

Access-Control-Allow-Origin: https://frontend.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

Test Frontend

Visit https://frontend.example.com and verify:

• Frontend loads correctly
• Backend indicator shows "Backend" status
• Can create, edit, and delete snippets
• No CORS errors in browser console

Environment Variables Reference

Backend Environment Variables

Variable	Description	Example
CORS_ALLOWED_ORIGINS	Comma-separated list of allowed frontend URLs	https://frontend.example.com
DATABASE_PATH	Path to SQLite database file	/app/data/snippets.db

Note: Use * for CORS_ALLOWED_ORIGINS only in development. In production, always specify exact origins.

Frontend Environment Variables

Variable	Description	Example
VITE_FLASK_BACKEND_URL	Backend API URL	https://backend.example.com

Alternative: Single Domain Setup

If you prefer a single domain (e.g., https://app.example.com), you can deploy frontend with nginx proxying to backend:

Deploy Both Services

1. Deploy backend as before (internal only, no custom domain)
2. Frontend proxies /api requests to backend via nginx

Frontend Configuration

# Frontend environment variables
VITE_FLASK_BACKEND_URL=/api

Nginx Configuration

The included nginx.conf already handles this:

location /api {
    proxy_pass http://backend:5000;
    # ... proxy headers
}

Benefits

• Simplified DNS (single domain)
• No CORS issues (same-origin requests)
• Easier SSL management

Drawbacks

• Frontend and backend tightly coupled
• Can't independently scale services
• Single point of failure

Troubleshooting

CORS Errors

Problem: Browser console shows CORS errors

Solutions:

1. Verify CORS_ALLOWED_ORIGINS in backend matches frontend URL exactly
2. Ensure both domains use HTTPS (not mixed HTTP/HTTPS)
3. Check Cloudflare proxy status is enabled for both domains
4. Clear browser cache and hard refresh

Backend Connection Failed

Problem: Frontend shows "Connection failed" error

Solutions:

1. Verify backend is running: curl https://backend.example.com/health
2. Check CapRover logs for backend app
3. Verify VITE_FLASK_BACKEND_URL in frontend matches backend URL
4. Test from command line: curl -v https://backend.example.com/api/snippets

SSL Certificate Issues

Problem: SSL certificate not issued or invalid

Solutions:

1. Wait 5-10 minutes for Let's Encrypt to issue certificate
2. Verify DNS records are correct and propagated
3. Check CapRover can reach Let's Encrypt (port 80 open)
4. Try disabling and re-enabling HTTPS in CapRover

Data Persistence Issues

Problem: Backend loses data after restart

Solutions:

1. Verify "Has Persistent Data" is enabled in CapRover
2. Check persistent directory path is /app/data
3. Verify DATABASE_PATH environment variable is correct
4. Check CapRover volume is properly mounted

Multiple Origins

Problem: Need to allow multiple frontend domains

Solution: Set comma-separated origins:

CORS_ALLOWED_ORIGINS=https://frontend.example.com,https://app.example.com,https://staging.example.com

Security Best Practices

Production Checklist

• HTTPS enabled for both frontend and backend
• CORS_ALLOWED_ORIGINS set to specific domains (not *)
• Cloudflare proxy enabled (orange cloud)
• Rate limiting configured in Cloudflare
• Backend database backed up regularly
• Environment variables stored securely (not in code)
• Debug mode disabled in Flask (debug=False)
• Cloudflare WAF rules configured
• HTTPS-only cookies enabled
• Security headers configured in nginx

Recommended Cloudflare Rules

1. Rate Limiting: Limit API requests to 100 per minute per IP
2. Bot Protection: Challenge or block known bad bots
3. Geographic Restrictions: Block countries you don't serve (optional)
4. DDoS Protection: Enable automatic DDoS mitigation

Monitoring

CapRover Monitoring

1. Enable app metrics in CapRover dashboard
2. Monitor CPU and memory usage
3. Set up alerts for app crashes
4. Review logs regularly for errors

Cloudflare Analytics

1. Monitor traffic patterns
2. Check for unusual spikes or attacks
3. Review security events
4. Analyze performance metrics

Backup Strategy

Automated Backups

Set up a cron job in CapRover to backup database:

# In backend app settings, add a schedule:
0 2 * * * tar -czf /app/data/backup-$(date +%Y%m%d).tar.gz /app/data/snippets.db

Manual Backup

1. SSH into CapRover server
2. Copy database file:

   docker cp captain--codesnippet-backend:/app/data/snippets.db ./backup.db
   

Restore from Backup

1. Copy backup to container:

   docker cp ./backup.db captain--codesnippet-backend:/app/data/snippets.db
   

2. Restart backend app in CapRover

Scaling Considerations

Vertical Scaling

Increase resources in CapRover:

1. Go to app settings → "Resources"
2. Increase CPU and memory limits
3. Restart app

Horizontal Scaling

For high traffic:

1. Deploy multiple backend instances in CapRover
2. Use CapRover's load balancing
3. Consider shared database (PostgreSQL instead of SQLite)
4. Use Redis for session management

Cost Optimization

Cloudflare

• Free plan includes SSL, CDN, and basic DDoS protection
• Pro plan ($20/mo) adds WAF and additional performance features

CapRover

• Single VPS can run both frontend and backend
• Recommended: 2 CPU / 4GB RAM minimum
• Estimated cost: $10-20/month (DigitalOcean, Linode, Vultr)

Support

For issues specific to:

• CapRover: https://caprover.com/docs/
• Cloudflare: https://support.cloudflare.com/
• CodeSnippet: Check the main README.md and BACKEND-CONFIG.md