feat: add Sentry, Cloudflare R2, and CloudFlare CDN integrations

Production quick wins for improved observability and scalability: Sentry Error Tracking: - Add sentry-sdk[fastapi] dependency - Initialize Sentry in main.py with FastAPI/SQLAlchemy integrations - Add Celery integration for background task error tracking - Feature-flagged via SENTRY_DSN (disabled when empty) Cloudflare R2 Storage: - Add boto3 dependency for S3-compatible API - Create storage_service.py with StorageBackend abstraction - LocalStorageBackend for development (default) - R2StorageBackend for production cloud storage - Feature-flagged via STORAGE_BACKEND setting CloudFlare CDN/Proxy: - Create middleware/cloudflare.py for CF header handling - Extract real client IP from CF-Connecting-IP - Support CF-IPCountry for geo features - Feature-flagged via CLOUDFLARE_ENABLED setting Documentation: - Add docs/deployment/cloudflare.md setup guide - Update infrastructure.md with dev vs prod requirements - Add enterprise upgrade checklist for scaling beyond 1000 users - Update installation.md with new environment variables All features are optional and disabled by default for development. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 19:44:59 +01:00
parent 12b79c1ff0
commit ff5b395cdd
13 changed files with 1062 additions and 47 deletions
--- a/docs/deployment/cloudflare.md
+++ b/docs/deployment/cloudflare.md
@@ -0,0 +1,299 @@
+# CloudFlare Setup Guide
+
+This guide covers setting up CloudFlare for Wizamart, including CDN, proxy, WAF, and R2 storage.
+
+## Overview
+
+CloudFlare provides:
+
+| Feature | Benefit |
+|---------|---------|
+| **CDN** | Global edge caching for static assets |
+| **Proxy** | Hide origin IP, DDoS protection |
+| **WAF** | Web Application Firewall (basic rules free) |
+| **R2** | S3-compatible object storage (~$5/mo) |
+| **SSL** | Free SSL certificates |
+
+---
+
+## Quick Start
+
+### 1. Add Your Domain to CloudFlare
+
+1. Create a CloudFlare account at [cloudflare.com](https://cloudflare.com)
+2. Add your domain and follow the setup wizard
+3. Update your domain's nameservers to CloudFlare's
+
+### 2. Configure DNS Records
+
+Create these DNS records (with proxy enabled - orange cloud):
+
+| Type | Name | Content | Proxy |
+|------|------|---------|-------|
+| A | @ | Your server IP | ✅ Proxied |
+| A | www | Your server IP | ✅ Proxied |
+| A | api | Your server IP | ✅ Proxied |
+| CNAME | media | your-bucket.r2.dev | ✅ Proxied |
+
+### 3. Enable CloudFlare in Wizamart
+
+```env
+# .env
+CLOUDFLARE_ENABLED=true
+```
+
+This enables the CloudFlare middleware to:
+- Extract real client IPs from `CF-Connecting-IP`
+- Read client country from `CF-IPCountry`
+- Track requests via `CF-Ray` header
+
+---
+
+## SSL/TLS Configuration
+
+### Recommended: Full (Strict) Mode
+
+1. Go to **SSL/TLS** > **Overview**
+2. Select **Full (strict)**
+3. This requires a valid SSL certificate on your origin server
+
+### Origin Certificates
+
+For the origin server, you can use:
+
+1. **Let's Encrypt** (recommended for VPS):
+   ```bash
+   sudo certbot --nginx -d yourdomain.com
+   ```
+
+2. **CloudFlare Origin Certificate** (15-year free cert):
+   - Go to **SSL/TLS** > **Origin Server**
+   - Create Certificate
+   - Install on your server
+
+---
+
+## Caching Configuration
+
+### Page Rules for Static Assets
+
+Create page rules for optimal caching:
+
+**Rule 1: Static Assets**
+- URL: `*yourdomain.com/static/*`
+- Setting: Cache Level → Cache Everything
+- Setting: Edge Cache TTL → 1 month
+
+**Rule 2: Uploads**
+- URL: `*yourdomain.com/uploads/*`
+- Setting: Cache Level → Cache Everything
+- Setting: Edge Cache TTL → 1 week
+
+**Rule 3: API (No Cache)**
+- URL: `*yourdomain.com/api/*`
+- Setting: Cache Level → Bypass
+
+### Cache Rules (New Interface)
+
+Or use the newer Cache Rules:
+
+```
+Expression: (http.request.uri.path starts with "/static/")
+Action: Cache eligible → Override → 30 days
+```
+
+---
+
+## Cloudflare R2 Storage
+
+### Create R2 Bucket
+
+1. Go to **R2** in CloudFlare dashboard
+2. Click **Create bucket**
+3. Name: `wizamart-media`
+4. Location: Choose region closest to your users
+
+### Create API Token
+
+1. Go to **R2** > **Manage R2 API Tokens**
+2. Create new token with:
+   - Permission: Object Read & Write
+   - Bucket: Select your bucket
+3. Save the **Access Key ID** and **Secret Access Key**
+
+### Configure Wizamart
+
+```env
+# .env
+STORAGE_BACKEND=r2
+R2_ACCOUNT_ID=your_account_id
+R2_ACCESS_KEY_ID=your_access_key
+R2_SECRET_ACCESS_KEY=your_secret_key
+R2_BUCKET_NAME=wizamart-media
+```
+
+### Enable Public Access (Optional)
+
+For direct public access to uploaded files:
+
+1. Go to **R2** > Your bucket > **Settings**
+2. Enable **Public Access**
+3. Note the public URL: `https://your-bucket.account-id.r2.dev`
+
+Or use a custom domain:
+
+1. Go to **R2** > Your bucket > **Settings** > **Custom Domains**
+2. Add `media.yourdomain.com`
+3. Update `.env`:
+   ```env
+   R2_PUBLIC_URL=https://media.yourdomain.com
+   ```
+
+---
+
+## Security Settings
+
+### WAF Rules (Free Tier)
+
+Enable these managed rules:
+
+1. **CloudFlare Managed Ruleset** - Basic protection
+2. **OWASP Core Ruleset** - SQL injection, XSS protection
+
+### Rate Limiting
+
+Create rate limiting rules for the API:
+
+- URL: `/api/*`
+- Rate: 100 requests per minute
+- Action: Challenge or Block
+
+### Bot Fight Mode
+
+1. Go to **Security** > **Bots**
+2. Enable **Bot Fight Mode**
+
+---
+
+## Nginx Configuration for CloudFlare
+
+When using CloudFlare proxy, update Nginx to trust CloudFlare IPs:
+
+```nginx
+# /etc/nginx/conf.d/cloudflare.conf
+
+# CloudFlare IP ranges
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 131.0.72.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+
+# IPv6
+set_real_ip_from 2400:cb00::/32;
+set_real_ip_from 2606:4700::/32;
+set_real_ip_from 2803:f800::/32;
+set_real_ip_from 2405:b500::/32;
+set_real_ip_from 2405:8100::/32;
+set_real_ip_from 2a06:98c0::/29;
+set_real_ip_from 2c0f:f248::/32;
+
+real_ip_header CF-Connecting-IP;
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLOUDFLARE_ENABLED` | Enable CF header processing | `false` |
+| `STORAGE_BACKEND` | Storage backend (`local` or `r2`) | `local` |
+| `R2_ACCOUNT_ID` | CloudFlare account ID | - |
+| `R2_ACCESS_KEY_ID` | R2 API access key | - |
+| `R2_SECRET_ACCESS_KEY` | R2 API secret key | - |
+| `R2_BUCKET_NAME` | R2 bucket name | `wizamart-media` |
+| `R2_PUBLIC_URL` | Custom public URL for R2 | - |
+
+---
+
+## Verification
+
+### Check CloudFlare is Working
+
+1. **Check headers** in browser DevTools:
+   - `CF-Ray` header should be present
+   - `CF-Cache-Status` shows caching status
+
+2. **Test from command line**:
+   ```bash
+   curl -I https://yourdomain.com/static/css/main.css
+   # Should see CF-Ray and CF-Cache-Status headers
+   ```
+
+### Check R2 is Working
+
+1. **Upload a test file** via the admin media library
+2. **Check the URL** - should point to R2 or your custom domain
+3. **Verify in CloudFlare dashboard** - file should appear in bucket
+
+### Check Real IP Logging
+
+With `CLOUDFLARE_ENABLED=true`:
+
+```bash
+# Check application logs
+journalctl -u wizamart | grep "real_ip"
+```
+
+---
+
+## Troubleshooting
+
+### 521 Error (Web Server Down)
+
+- Ensure your origin server is running
+- Check firewall allows CloudFlare IPs
+- Verify SSL certificate is valid
+
+### 522 Error (Connection Timed Out)
+
+- Check origin server is responding
+- Verify port 443 is open
+- Check server isn't overloaded
+
+### 525 Error (SSL Handshake Failed)
+
+- Ensure origin has valid SSL certificate
+- Try CloudFlare Origin Certificate
+- Check SSL mode is correct (Full vs Full Strict)
+
+### R2 Access Denied
+
+- Verify API token has correct permissions
+- Check bucket name is correct
+- Ensure bucket policy allows the operation
+
+---
+
+## Cost Estimate
+
+| Service | Free Tier | Paid Usage |
+|---------|-----------|------------|
+| CDN | Unlimited | Free |
+| WAF | Basic rules | $20/mo for advanced |
+| R2 Storage | 10 GB/mo | $0.015/GB |
+| R2 Requests | 10M Class A, 10M Class B | $0.36/M, $0.0036/M |
+| SSL | Free | Free |
+
+**Typical monthly cost for small-medium site: ~$5-15**
--- a/docs/deployment/infrastructure.md
+++ b/docs/deployment/infrastructure.md
@@ -73,31 +73,52 @@ This guide documents the complete infrastructure for the Wizamart platform, from

 ### What We Have Now

-| Component | Technology | Status |
-|-----------|------------|--------|
-| Web Framework | FastAPI + Uvicorn | ✅ Production Ready |
-| Database | PostgreSQL 15 | ✅ Production Ready |
-| ORM | SQLAlchemy 2.0 | ✅ Production Ready |
-| Migrations | Alembic | ✅ Production Ready |
-| Templates | Jinja2 + Tailwind CSS | ✅ Production Ready |
-| Authentication | JWT (PyJWT) | ✅ Production Ready |
-| Email | SMTP/SendGrid/Mailgun/SES | ✅ Production Ready |
-| Payments | Stripe | ✅ Production Ready |
-| Task Queue | Celery 5.3 + Redis | ✅ Production Ready |
-| Task Scheduler | Celery Beat | ✅ Production Ready |
-| Task Monitoring | Flower | ✅ Production Ready |
-| Caching | Redis 7 | ✅ Production Ready |
-| File Storage | Local filesystem | ⏳ Needs S3 for prod |
+| Component | Technology | Dev Required | Prod Required | Status |
+|-----------|------------|--------------|---------------|--------|
+| Web Framework | FastAPI + Uvicorn | ✅ | ✅ | ✅ Production Ready |
+| Database | PostgreSQL 15 | ✅ | ✅ | ✅ Production Ready |
+| ORM | SQLAlchemy 2.0 | ✅ | ✅ | ✅ Production Ready |
+| Migrations | Alembic | ✅ | ✅ | ✅ Production Ready |
+| Templates | Jinja2 + Tailwind CSS | ✅ | ✅ | ✅ Production Ready |
+| Authentication | JWT (PyJWT) | ✅ | ✅ | ✅ Production Ready |
+| Email | SMTP/SendGrid/Mailgun/SES | ❌ | ✅ | ✅ Production Ready |
+| Payments | Stripe | ❌ | ✅ | ✅ Production Ready |
+| Task Queue | Celery 5.3 + Redis | ❌ | ✅ | ✅ Production Ready |
+| Task Scheduler | Celery Beat | ❌ | ✅ | ✅ Production Ready |
+| Task Monitoring | Flower | ❌ | ⚪ Optional | ✅ Production Ready |
+| Caching | Redis 7 | ❌ | ✅ | ✅ Production Ready |
+| File Storage | Local / Cloudflare R2 | Local | R2 | ✅ Production Ready |
+| Error Tracking | Sentry | ❌ | ⚪ Recommended | ✅ Production Ready |
+| CDN / WAF | CloudFlare | ❌ | ⚪ Recommended | ✅ Production Ready |

-### What We Need to Add
+**Legend:** ✅ Required | ⚪ Optional/Recommended | ❌ Not needed

-| Component | Priority | Reason |
-|-----------|----------|--------|
-| S3/MinIO | High | Scalable file storage |
-| Sentry | High | Error tracking |
-| CloudFlare | Medium | CDN + DDoS protection |
-| Load Balancer | Medium | Horizontal scaling |
-| Prometheus/Grafana | Low | Metrics and dashboards |
+### Development vs Production
+
+**Development** requires only:
+- PostgreSQL (via Docker: `make docker-up`)
+- Python 3.11+ with dependencies
+
+**Production** adds:
+- Redis (for Celery task queue)
+- Celery workers (for background tasks)
+- Reverse proxy (Nginx)
+- SSL certificates
+
+**Optional but recommended for Production:**
+- Sentry (error tracking) - Set `SENTRY_DSN` to enable
+- Cloudflare R2 (cloud storage) - Set `STORAGE_BACKEND=r2` to enable
+- CloudFlare CDN (caching/DDoS) - Set `CLOUDFLARE_ENABLED=true` to enable
+
+### What We Need for Enterprise (Future Growth)
+
+| Component | Priority | When Needed | Estimated Users |
+|-----------|----------|-------------|-----------------|
+| Load Balancer | Medium | Horizontal scaling | 1,000+ concurrent |
+| Database Replica | Medium | Read-heavy workloads | 1,000+ concurrent |
+| Redis Sentinel | Low | Cache redundancy | 5,000+ concurrent |
+| Prometheus/Grafana | Low | Advanced metrics | Any (nice to have) |
+| Kubernetes | Low | Multi-region/HA | 10,000+ concurrent |

 ---

@@ -838,7 +859,7 @@ python -c "from app.core.database import engine; print(engine.connect())"

 ## Migration Path

-### Phase 1: Current (Development) ✅ COMPLETE
+### Phase 1: Development ✅ COMPLETE
 - ✅ PostgreSQL 15 (Docker)
 - ✅ FastAPI + Uvicorn
 - ✅ Local file storage
@@ -850,35 +871,93 @@ python -c "from app.core.database import engine; print(engine.connect())"
 - ✅ Celery 5.3 (background jobs)
 - ✅ Celery Beat (scheduled tasks)
 - ✅ Flower (task monitoring)
- ⏳ S3/MinIO (file storage)
- ⏳ Sentry (error tracking)
+- ✅ Cloudflare R2 (cloud file storage)
+- ✅ Sentry (error tracking)
+- ✅ CloudFlare CDN (caching + DDoS protection)

-### Phase 3: Scale
- Horizontal app scaling (multiple Uvicorn instances)
- Load balancer (Nginx/HAProxy)
- PostgreSQL read replicas
- Redis Sentinel/cluster
- CDN for static assets (CloudFlare)
- Dedicated Celery workers per queue
+### Phase 3: Scale (1,000+ Users)
+- ⏳ Load balancer (Nginx/HAProxy/ALB)
+- ⏳ Horizontal app scaling (2-4 Uvicorn instances)
+- ⏳ PostgreSQL read replica
+- ⏳ Dedicated Celery workers per queue

-### Phase 4: High Availability
- Multi-region deployment
- Database failover
- Container orchestration (Kubernetes)
- Full monitoring stack (Prometheus/Grafana/Loki)
+### Phase 4: Enterprise (5,000+ Users)
+- ⏳ Redis Sentinel/cluster
+- ⏳ Database connection pooling (PgBouncer)
+- ⏳ Full monitoring stack (Prometheus/Grafana)
+- ⏳ Log aggregation (Loki/ELK)
+
+### Phase 5: High Availability (10,000+ Users)
+- ⏳ Multi-region deployment
+- ⏳ Database failover (streaming replication)
+- ⏳ Container orchestration (Kubernetes)
+- ⏳ Global CDN with edge caching
+
+---
+
+## Enterprise Upgrade Checklist
+
+When you're ready to scale beyond 1,000 concurrent users:
+
+### Infrastructure
+
+- [ ] **Load Balancer** - Add Nginx/HAProxy in front of API servers
+  - Enables horizontal scaling
+  - Health checks and automatic failover
+  - SSL termination at edge
+
+- [ ] **Multiple API Servers** - Run 2-4 Uvicorn instances
+  - Scale horizontally instead of vertically
+  - Blue-green deployments possible
+
+- [ ] **Database Read Replica** - Add PostgreSQL replica
+  - Offload read queries from primary
+  - Backup without impacting production
+
+- [ ] **Connection Pooling** - Add PgBouncer
+  - Reduce database connection overhead
+  - Handle connection spikes
+
+### Monitoring & Observability
+
+- [ ] **Prometheus + Grafana** - Metrics dashboards
+  - Request latency, error rates, saturation
+  - Database connection pool metrics
+  - Celery queue lengths
+
+- [ ] **Log Aggregation** - Loki or ELK stack
+  - Centralized logs from all services
+  - Search and alerting
+
+- [ ] **Alerting** - PagerDuty/OpsGenie integration
+  - On-call rotation
+  - Escalation policies
+
+### Security
+
+- [ ] **WAF Rules** - CloudFlare or AWS WAF
+  - SQL injection protection
+  - Rate limiting at edge
+  - Bot protection
+
+- [ ] **Secrets Management** - HashiCorp Vault
+  - Rotate credentials automatically
+  - Audit access to secrets

 ---

 ## Next Steps

-1. **Configure S3/MinIO** - For production file storage (high priority)
-2. **Set up Sentry** - Error tracking (high priority)
-3. **Add CloudFlare** - CDN + DDoS protection (medium priority)
-4. **Configure load balancer** - When scaling horizontally
-5. **Choose production deployment** - VPS or Docker based on team preference
+**You're production-ready now!** Optional improvements:
+
+1. **Enable Sentry** - Add `SENTRY_DSN` for error tracking (free tier)
+2. **Enable R2** - Set `STORAGE_BACKEND=r2` for cloud storage (~$5/mo)
+3. **Enable CloudFlare** - Proxy domain for CDN + DDoS protection (free tier)
+4. **Add load balancer** - When you need horizontal scaling

 See also:
 - [Production Deployment Guide](production.md)
+- [CloudFlare Setup Guide](cloudflare.md)
 - [Docker Deployment](docker.md)
 - [Environment Configuration](environment.md)
 - [Background Tasks Architecture](../architecture/background-tasks.md)
--- a/docs/deployment/production.md
+++ b/docs/deployment/production.md
@@ -393,11 +393,70 @@ free -h

 ### Set Up Sentry (Error Tracking)

+Sentry provides real-time error tracking and performance monitoring.
+
+1. **Create a Sentry account** at [sentry.io](https://sentry.io) (free tier available)
+2. **Create a new project** (Python/FastAPI)
+3. **Add to `.env`**:
+   ```env
+   SENTRY_DSN=https://your-key@sentry.io/project-id
+   SENTRY_ENVIRONMENT=production
+   SENTRY_TRACES_SAMPLE_RATE=0.1
+   ```
+4. **Restart services**:
+   ```bash
+   sudo systemctl restart wizamart wizamart-celery
+   ```
+
+Sentry will now capture:
+- Unhandled exceptions
+- API errors with request context
+- Celery task failures
+- Performance traces (10% sample rate)
+
+---
+
+## Cloudflare R2 Storage
+
+For production, use Cloudflare R2 instead of local storage for scalability and CDN integration.
+
+### Setup
+
+1. **Create R2 bucket** in CloudFlare dashboard
+2. **Create API token** with Object Read/Write permissions
+3. **Add to `.env`**:
+   ```env
+   STORAGE_BACKEND=r2
+   R2_ACCOUNT_ID=your_account_id
+   R2_ACCESS_KEY_ID=your_access_key
+   R2_SECRET_ACCESS_KEY=your_secret_key
+   R2_BUCKET_NAME=wizamart-media
+   R2_PUBLIC_URL=https://media.yourdomain.com
+   ```
+
+See [CloudFlare Setup Guide](cloudflare.md) for detailed instructions.
+
+---
+
+## CloudFlare CDN & Proxy
+
+For production, proxy your domain through CloudFlare for:
+- Global CDN caching
+- DDoS protection
+- Free SSL certificates
+- WAF (Web Application Firewall)
+
+### Enable CloudFlare Headers
+
 Add to `.env`:
 ```env
-SENTRY_DSN=https://your-sentry-dsn
+CLOUDFLARE_ENABLED=true
 ```

+This enables proper handling of `CF-Connecting-IP` for real client IPs.
+
+See [CloudFlare Setup Guide](cloudflare.md) for complete configuration.
+
 ---

 ## Troubleshooting
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -236,6 +236,31 @@ pytest -m integration
 | `FLOWER_URL` | Flower dashboard URL | `http://localhost:5555` | ❌ |
 | `FLOWER_PASSWORD` | Flower authentication password | `changeme` | ❌ |

+### Sentry Error Tracking
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `SENTRY_DSN` | Sentry DSN (leave empty to disable) | - | ❌ |
+| `SENTRY_ENVIRONMENT` | Environment name | `development` | ❌ |
+| `SENTRY_TRACES_SAMPLE_RATE` | Performance tracing rate (0.0-1.0) | `0.1` | ❌ |
+
+### Cloudflare R2 Storage
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `STORAGE_BACKEND` | Storage backend (`local` or `r2`) | `local` | ❌ |
+| `R2_ACCOUNT_ID` | Cloudflare account ID | - | ❌ (if r2) |
+| `R2_ACCESS_KEY_ID` | R2 access key | - | ❌ (if r2) |
+| `R2_SECRET_ACCESS_KEY` | R2 secret key | - | ❌ (if r2) |
+| `R2_BUCKET_NAME` | R2 bucket name | `wizamart-media` | ❌ |
+| `R2_PUBLIC_URL` | Custom public URL for R2 | - | ❌ |
+
+### CloudFlare CDN
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `CLOUDFLARE_ENABLED` | Enable CloudFlare header handling | `false` | ❌ |
+
 ### Stripe Billing

 | Variable | Description | Default | Required |
--- a/docs/index.md
+++ b/docs/index.md
@@ -435,9 +435,12 @@ We welcome contributions! Please see our [Contributing Guide](development/contri
 - ✅ Marketplace integration
 - ✅ Team management

+**Production Ready**:
+- ✅ Error tracking (Sentry integration)
+- ✅ Cloud storage (Cloudflare R2)
+- ✅ CDN & WAF (CloudFlare)
+
 **In Development**:
- 🚧 Payment integration (Stripe-ready)
- 🚧 Email notifications
 - 🚧 Advanced analytics

 ---