snippet-pastebin/docs/ENV-CONFIG.md

Environment Configuration Examples

This directory contains example environment configurations for different deployment scenarios.

Quick Reference

Copy the appropriate example to .env in the project root:

cp .env.example .env
# Edit .env with your values

Scenarios

1. Local Development (Default)

Use case: Developing frontend only with local browser storage

# No backend URL - uses IndexedDB
VITE_FLASK_BACKEND_URL=

2. Local Development with Backend

Use case: Developing with local Flask backend

# Frontend (.env)
VITE_FLASK_BACKEND_URL=http://localhost:5000

# Backend (environment or .env)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
DATABASE_PATH=/app/data/snippets.db

3. Docker Compose (Full Stack)

Use case: Running both frontend and backend with Docker

# Frontend automatically connects to backend via nginx proxy
# No .env needed - configured in docker-compose.yml

docker-compose.yml already includes:

environment:
  - VITE_FLASK_BACKEND_URL=http://localhost:5000
  - CORS_ALLOWED_ORIGINS=http://localhost:3000
  - DATABASE_PATH=/app/data/snippets.db

4. Production - Separate Domains (CapRover)

Use case: Frontend and backend on different domains

# Frontend environment variables (in CapRover)
VITE_FLASK_BACKEND_URL=https://backend.example.com

# Backend environment variables (in CapRover)
CORS_ALLOWED_ORIGINS=https://frontend.example.com
DATABASE_PATH=/app/data/snippets.db

5. Production - Multiple Frontend Domains

Use case: Multiple frontend deployments (prod, staging, dev)

# Backend environment variables
CORS_ALLOWED_ORIGINS=https://app.example.com,https://staging.example.com,https://dev.example.com
DATABASE_PATH=/app/data/snippets.db

# Frontend 1 (Production)
VITE_FLASK_BACKEND_URL=https://api.example.com

# Frontend 2 (Staging)
VITE_FLASK_BACKEND_URL=https://api.example.com

# Frontend 3 (Development)
VITE_FLASK_BACKEND_URL=https://api.example.com

6. Production - Single Domain (Proxied)

Use case: Frontend and backend on same domain, nginx proxy

# Frontend environment variables
VITE_FLASK_BACKEND_URL=/api

# Backend environment variables
CORS_ALLOWED_ORIGINS=*
# Note: CORS not needed since nginx proxies requests (same-origin)
DATABASE_PATH=/app/data/snippets.db

nginx.conf includes:

location /api {
    proxy_pass http://backend:5000;
}

Environment Variables Reference

Frontend Variables

Variable	Description	Example
VITE_FLASK_BACKEND_URL	Backend API URL. When set, forces Flask backend usage.	https://backend.example.com

Notes:

• Must start with VITE_ to be exposed to frontend
• If not set, app uses IndexedDB (local storage)
• Can be relative (/api) if using nginx proxy
• Requires rebuild for production: npm run build

Backend Variables

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

Notes:

• Use * only in development
• In production, always specify exact origins
• No trailing slashes on URLs
• Must match frontend URL exactly (including https://)

Setting Environment Variables

Local Development (.env file)

# Create .env file
cat > .env << EOF
VITE_FLASK_BACKEND_URL=http://localhost:5000
EOF

# Start dev server
npm run dev

Docker Build

# Build with environment variable
docker build --build-arg VITE_FLASK_BACKEND_URL=https://backend.example.com -t frontend .

Docker Compose

# docker-compose.yml
services:
  frontend:
    environment:
      - VITE_FLASK_BACKEND_URL=https://backend.example.com

CapRover

1. Go to CapRover dashboard
2. Select your app
3. Click "App Configs" tab
4. Add environment variables in "Environment Variables" section
5. Redeploy app

Kubernetes

# deployment.yaml
env:
  - name: VITE_FLASK_BACKEND_URL
    value: "https://backend.example.com"
  - name: CORS_ALLOWED_ORIGINS
    value: "https://frontend.example.com"

Testing Configuration

Test Frontend Backend Connection

# Check if environment variable is set
echo $VITE_FLASK_BACKEND_URL

# Check in browser console
console.log(import.meta.env.VITE_FLASK_BACKEND_URL)

Test Backend CORS

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

# Full test suite
./test-cors.sh https://backend.example.com https://frontend.example.com

Common Mistakes

❌ Wrong: Missing VITE_ Prefix

FLASK_BACKEND_URL=http://localhost:5000  # Won't work!

✅ Correct: VITE_ Prefix Required

VITE_FLASK_BACKEND_URL=http://localhost:5000

---

❌ Wrong: Trailing Slash in CORS

CORS_ALLOWED_ORIGINS=https://frontend.example.com/  # Won't work!

✅ Correct: No Trailing Slash

CORS_ALLOWED_ORIGINS=https://frontend.example.com

---

❌ Wrong: HTTP/HTTPS Mismatch

# Frontend
VITE_FLASK_BACKEND_URL=https://backend.example.com

# Backend
CORS_ALLOWED_ORIGINS=http://frontend.example.com  # Wrong protocol!

✅ Correct: Matching Protocols

# Frontend
VITE_FLASK_BACKEND_URL=https://backend.example.com

# Backend
CORS_ALLOWED_ORIGINS=https://frontend.example.com

---

❌ Wrong: Using * in Production

CORS_ALLOWED_ORIGINS=*  # Security risk in production!

✅ Correct: Specific Origins

CORS_ALLOWED_ORIGINS=https://frontend.example.com

Troubleshooting

Environment variable not working

1. Frontend not rebuilding:

   • Vite requires rebuild for env vars: npm run build
   • Dev server: Restart npm run dev

2. Variable not prefixed correctly:

   • Must start with VITE_ for frontend
   • Backend vars don't need prefix

3. Docker not picking up changes:

   • Rebuild: docker-compose up -d --build
   • Check: docker-compose config

CORS errors persist

1. Backend not restarted:

   • Restart after env changes
   • Check logs: docker-compose logs backend

2. URL mismatch:

   • Frontend URL must match CORS_ALLOWED_ORIGINS exactly
   • Check browser console for actual origin

3. Cloudflare issues:

   • Verify proxy status (orange cloud)
   • Check SSL/TLS mode: "Full (strict)"

Security Best Practices

Development

• ✅ Use * for CORS_ALLOWED_ORIGINS
• ✅ Use http:// for local URLs
• ✅ Keep .env out of version control

Staging

• ✅ Use specific origins for CORS
• ✅ Use https:// for all URLs
• ✅ Test with production-like configuration

Production

• ✅ Always use specific origins
• ✅ Always use https://
• ✅ Store secrets in secure environment
• ✅ Never commit .env files
• ✅ Rotate credentials regularly
• ✅ Monitor access logs

Additional Resources

• Backend Configuration Guide
• CORS Configuration & Testing
• Deployment Guide
• Deployment Checklist