snippet-pastebin/backend/README.md

CodeSnippet Backend

Flask-based REST API for managing code snippets with SQLite database.

Quick Start

Option 1: Docker (Recommended)

# From project root
docker-compose up -d

The backend will be available at http://localhost:5000

Option 2: Local Python

cd backend
pip install -r requirements.txt
python app.py

Server runs on http://localhost:5000 by default.

Configuration

Set the DB_PATH environment variable to change the database location:

export DB_PATH=/path/to/snippets.db
python app.py

Default: /data/snippets.db

API Endpoints

Health Check

• GET /health - Returns server health status

Snippets

• GET /api/snippets - Get all snippets
• GET /api/snippets/:id - Get a specific snippet
• POST /api/snippets - Create a new snippet
• PUT /api/snippets/:id - Update a snippet
• DELETE /api/snippets/:id - Delete a snippet

Request/Response Format

Snippet Object

{
  "id": "unique-id",
  "title": "Snippet Title",
  "code": "const example = 'code';",
  "language": "javascript",
  "description": "Optional description",
  "tags": ["array", "of", "tags"],
  "category": "general",
  "componentName": "ComponentName",
  "previewParams": [],
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Frontend Integration

Automatic Configuration (Recommended)

The frontend can be automatically configured to use the Flask backend via environment variable:

For Docker Compose (full stack):

docker-compose up -d

The frontend will automatically connect to the backend at http://backend:5000.

For local development:

# .env file in project root
VITE_FLASK_BACKEND_URL=http://localhost:5000

When VITE_FLASK_BACKEND_URL is set:

• Frontend automatically uses Flask backend
• Manual backend selection in Settings is disabled
• Perfect for production deployments

Manual Configuration

In the CodeSnippet app:

1. Navigate to Settings page
2. Select "Flask Backend (Remote Server)"
3. Enter backend URL (e.g., http://localhost:5000)
4. Click "Test" to verify connection
5. Click "Save Storage Settings"
6. Optionally migrate existing IndexedDB data to Flask

See BACKEND-CONFIG.md for detailed configuration guide.

Docker Details

Building the Image

docker build -t codesnippet-backend ./backend

Running the Container

# With volume for persistent data
docker run -p 5000:5000 -v $(pwd)/data:/app/data codesnippet-backend

# With custom database path and CORS
docker run -p 5000:5000 \
  -e DATABASE_PATH=/app/data/custom.db \
  -e CORS_ALLOWED_ORIGINS=https://frontend.example.com \
  -v $(pwd)/data:/app/data \
  codesnippet-backend

Using Docker Compose

# Start
docker-compose up -d

# Stop
docker-compose down

# View logs
docker-compose logs -f backend

# Rebuild after changes
docker-compose up -d --build

Development

The backend uses:

• Flask 3.0 - Web framework
• Flask-CORS - Cross-origin resource sharing
• SQLite3 - Database (built into Python)

Database Schema

CREATE TABLE snippets (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    code TEXT NOT NULL,
    language TEXT NOT NULL,
    description TEXT,
    tags TEXT,
    category TEXT,
    componentName TEXT,
    previewParams TEXT,
    createdAt TEXT NOT NULL,
    updatedAt TEXT NOT NULL
)

Environment Variables

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

Production Configuration

For production deployments, always set specific CORS origins:

# Single origin
export CORS_ALLOWED_ORIGINS=https://frontend.example.com

# Multiple origins
export CORS_ALLOWED_ORIGINS=https://frontend.example.com,https://app.example.com

Important: Using * for CORS in production is a security risk. Only use in development.

Troubleshooting

Connection Refused

• Ensure the Flask server is running
• Check firewall settings
• Verify the port (5000) is not in use

CORS Errors

• The backend allows all origins by default in development (CORS_ALLOWED_ORIGINS=*)
• For production, set specific origins: CORS_ALLOWED_ORIGINS=https://frontend.example.com
• See CORS-GUIDE.md for detailed CORS configuration and testing
• Verify frontend URL matches exactly (including https:// and no trailing slash)

Database Locked

• Ensure only one instance of the backend is running
• Check file permissions on the database file

Production Deployment

For deploying to production with separate frontend and backend domains:

1. See DEPLOYMENT.md - Complete CapRover/Cloudflare deployment guide
2. See CORS-GUIDE.md - CORS configuration and testing
3. See DEPLOYMENT-CHECKLIST.md - Quick deployment checklist

Quick Production Setup

# Build and deploy backend to CapRover
cd backend
caprover deploy -a codesnippet-backend

# Set environment variables in CapRover dashboard:
# - CORS_ALLOWED_ORIGINS=https://frontend.example.com
# - DATABASE_PATH=/app/data/snippets.db

# Enable persistent storage at /app/data
# Enable HTTPS and connect custom domain