docs: add detailed configuration and deployment guides

- Add `configuration.md` with environment variable documentation
- Add `deployment.md` with production deployment instructions and tips
- Include detailed security, performance, storage, and scaling checklists
- Document rate limit configurations and logging best practices
- Provide S3/MinIO configuration examples and FAQs for common scenarios

Author: Pdzly

README.md

@@ -1,184 +1,72 @@
-# DevBin – The Bin for all your Pasting needs
+# DevBin
 
-A lightweight and modern pastebin service built with FastAPI (Python) for the backend and Svelte for the frontend. Share
-code snippets, text, and more with ease.
+A lightweight pastebin service built with FastAPI and Svelte.
 
-## Features
-
-- **Simple and Clean Interface** – Intuitive UI for quick paste creation and sharing
-- **Syntax Highlighting** – Support for multiple programming languages
-- **Paste Expiration** – Automatic cleanup of expired pastes
-- **Rate Limiting** – Built-in protection with configurable limits and bypass tokens
-- **Caching Layer** – LRU cache for improved performance
-- **Legacy Paste Support** – Backward compatibility with older paste formats
-- **Health Monitoring** – Built-in health check endpoint and storage monitoring
-- **Docker Ready** – Easy deployment with Docker Compose
-- **Configurable Storage** – Customizable file storage and size limits
-- **Trusted Hosts** – IP-based access control
-
-## Tech Stack
-
-- **Backend**: FastAPI, SQLAlchemy, PostgreSQL, Alembic (migrations)
-- **Frontend**: Svelte
-- **Deployment**: Docker, Docker Compose
-- **Caching**: LRU Memory Cache with configurable TTL
-
-## Requirements
-
-- Docker Engine
-- Docker Compose (or `docker-compose` for older versions)
-
-## Installation
-
-> **Note**: Depending on your Docker version, you may need to use `docker-compose` instead of `docker compose`
-
-### Quick Start
-
-DevBin can be deployed in two ways:
-
-#### Option 1: Development Setup
-
-1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd DevBin
-   ```
-
-2. **Configure environment variables**
-   ```bash
-   cp .env.example .env
-   ```
-   Edit `.env` and update the values according to your needs. Key configurations include:
-    - Database credentials
-    - API port and host
-    - Rate limiting settings
-    - CORS domains
-    - Storage paths and limits
-    - Trusted hosts
-
-3. **Start the services**
-   ```bash
-   docker compose up -d
-   ```
-
-4. **Run database migrations**
-   ```bash
-   docker compose run --rm app uv run alembic upgrade head
-   ```
-
-5. **Access the application**
-    - Frontend: http://localhost:3000
-    - API Documentation (Swagger): http://localhost:8000/docs
-    - Health Check: http://localhost:8000/health
-
-#### Option 2: Production Setup
-
-For production deployment, you only need the production compose file and environment configuration:
-
-1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd DevBin
-   ```
-
-2. **Configure environment variables**
-   ```bash
-   cp .env.example .env
-   ```
-   Edit `.env` with production-ready values (strong passwords, proper domains, etc.)
-
-3. **Start the services**
-   ```bash
-   docker compose -f docker-compose.prod.yml up -d
-   ```
-
-4. **Run database migrations**
-   ```bash
-   docker compose -f docker-compose.prod.yml run --rm app uv run alembic upgrade head
-   ```
-
-### Stopping the Service
-
-Development:
+## Quick Start
 
 ```bash
-docker compose down
+git clone <repository-url>
+cd DevBin
+cp .env.example .env      # Configure as needed
+task dev:up               # Start all services
+task db:migrate           # Run migrations
 ```
 
-Production:
-
-```bash
-docker compose -f docker-compose.prod.yml down
-```
-
-## Configuration
-
-Key environment variables in `.env`:
-
-| Variable                 | Description                             | Default                   |
-|--------------------------|-----------------------------------------|---------------------------|
-| `APP_PORT`               | Backend API port                        | 8000                      |
-| `APP_MAX_CONTENT_LENGTH` | Maximum paste size                      | 10000                     |
-| `APP_WORKERS`            | Number of worker processes              | 1                         |
-| `APP_BYPASS_TOKEN`       | Token to bypass rate limits             | -                         |
-| `APP_CACHE_TTL`          | Cache time-to-live (seconds)            | 300                       |
-| `APP_MIN_STORAGE_MB`     | Minimum required storage (MB)           | 1024                      |
-| `TRUSTED_HOSTS`          | Array of trusted IP addresses/hostnames | ["127.0.0.1"]             |
-| `APP_CORS_DOMAINS`       | Allowed CORS origins                    | ["http://localhost:3000"] |
-
-See `.env.example` for a complete list of configuration options.
+**Access:**
+- Frontend: http://localhost:3000
+- API Docs: http://localhost:8000/docs
+- Health: http://localhost:8000/health
 
-## Development
+## Commands
 
-### Running in Development Mode
+Run `task --list` for all available commands.
 
-Set these variables in `.env`:
+| Command | Description |
+|---------|-------------|
+| `task dev:up` | Start all dev services |
+| `task dev:down` | Stop all dev services |
+| `task dev:logs` | Tail logs |
+| `task dev:reset` | Reset with fresh volumes |
+| `task db:migrate` | Run migrations |
+| `task db:shell` | PostgreSQL shell |
+| `task test` | Run all tests |
+| `task prod:up` | Start production |
+| `task prod:down` | Stop production |
+| `task clean` | Remove containers and volumes |
 
-```env
-APP_DEBUG=true
-APP_RELOAD=true
-APP_SQLALCHEMY_ECHO=true
-```
-
-### Tests
-
-### Backend Tests
-
-Run tests with:
-
-```bash
-cd backend
-uv run pytest
-```
+## Configuration
 
-> If you modified any of the core API endpoints, make sure to run the tests to ensure they still work as expected. Or if
-> you are committing breaking changes, please adjust them and add a note why this breaking change is necessary.
+See [`.env.example`](.env.example) for all options. Key settings:
 
-See [Testing](/backend/TESTING.md)
+| Variable | Description |
+|----------|-------------|
+| `APP_PORT` | API port (default: 8000) |
+| `APP_MAX_CONTENT_LENGTH` | Max paste size |
+| `APP_STORAGE_TYPE` | `local`, `s3`, or `minio` |
+| `APP_CACHE_TYPE` | `memory` or `redis` |
 
-### API Endpoints
+Full reference: [`docs/configuration.md`](docs/configuration.md)
 
-- `GET /health` – Health check
-- `GET /pastes/{paste_id}` – Retrieve a paste
-- `GET /pastes/legacy/{paste_id}` – Retrieve a legacy paste
-- `POST /pastes` – Create a new paste
+## API
 
-Full API documentation available at `/docs` when running.
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check |
+| `GET /metrics` | Prometheus metrics |
+| `POST /pastes` | Create paste |
+| `GET /pastes/{id}` | Get paste |
+| `DELETE /pastes/{id}` | Delete paste |
 
-## Production Deployment
+Interactive docs at `/docs` when running.
 
-See **[Option 2: Production Setup](#option-2-production-setup)** in the Quick Start section above for deployment
-instructions.
+## Documentation
 
-### Production Checklist
+- [Configuration Reference](docs/configuration.md)
+- [Production Deployment](docs/deployment.md)
+- [Testing Guide](backend/TESTING.md)
 
-Make sure to configure the following in your `.env` file:
+## Tech Stack
 
-- ✅ Set strong database credentials (`POSTGRES_USER`, `POSTGRES_PASSWORD`)
-- ✅ Configure appropriate rate limits
-- ✅ Set `APP_DEBUG=false` and `APP_RELOAD=false`
-- ✅ Configure trusted hosts properly (`TRUSTED_HOSTS`)
-- ✅ Set up proper CORS domains (`APP_CORS_DOMAINS`)
-- ✅ Use a secure bypass token (`APP_BYPASS_TOKEN`)
-- ✅ Configure minimum storage requirements (`APP_MIN_STORAGE_MB`)
-- ✅ Set appropriate worker count (`APP_WORKERS`)
+- **Backend**: FastAPI, SQLAlchemy, PostgreSQL
+- **Frontend**: Svelte
+- **Deployment**: Docker Compose

Taskfile.yml

@@ -22,6 +22,13 @@ tasks:
     cmds:
       - "{{.COMPOSE_DEV}} --profile dev_backend up -d --build"
 
+  dev:db:
+    desc: Start backend only (with database)
+    env:
+      APP_DEBUG: "true"
+    cmds:
+      - "{{.COMPOSE_DEV}} up -d"
+
   dev:frontend:
     desc: Start frontend only
     env:

backend/.env.example

@@ -89,8 +89,26 @@ APP_LOCK_TYPE=file
 APP_SAVE_USER_AGENT=false
 APP_SAVE_IP_ADDRESS=false
 
-# Optional: Rate limit bypass token for trusted apps
-# APP_BYPASS_TOKEN=your_secret_bypass_token_here
+# Rate Limiting Configuration
+# Enable/disable rate limiting globally
+APP_RATELIMIT_ENABLED=true
+# Storage backend: memory (default) or redis
+APP_RATELIMIT_BACKEND=memory
+# Default rate limit for endpoints without explicit limits
+APP_RATELIMIT_DEFAULT=60/minute
+
+# Per-endpoint rate limits (optional, these are defaults)
+# Format: <number>/<second|minute|hour|day>
+# APP_RATELIMIT_HEALTH=60/minute
+# APP_RATELIMIT_GET_PASTE=10/minute
+# APP_RATELIMIT_GET_PASTE_LEGACY=10/minute
+# APP_RATELIMIT_CREATE_PASTE=4/minute
+# APP_RATELIMIT_EDIT_PASTE=4/minute
+# APP_RATELIMIT_DELETE_PASTE=4/minute
+
+# Bypass tokens for trusted services (JSON list format)
+# Requests with matching Authorization header bypass rate limiting
+# APP_RATELIMIT_BYPASS_TOKENS=["service-token-1", "internal-api-key"]
 
 # Metrics Authentication
 # Optional: Secure the Prometheus /metrics endpoint with Bearer token authentication

backend/app/api/routes.py

@@ -12,7 +12,7 @@
 from app.config import config
 from app.containers import Container
 from app.exceptions import UnauthorizedError
-from app.ratelimit import limiter
+from app.ratelimit import create_limit_resolver, limiter
 from app.services.health_service import HealthService
 
 router = APIRouter()
@@ -51,7 +51,7 @@ def verify_metrics_token(credentials: HTTPAuthorizationCredentials | None = Depe
 
 
 @router.get("/health")
-@limiter.limit("60/minute")
+@limiter.limit(create_limit_resolver(config, "health"))
 @inject
 async def health(
     request: Request,
@@ -61,7 +61,7 @@ async def health(
 
 
 @router.get("/ready")
-@limiter.limit("60/minute")
+@limiter.limit(create_limit_resolver(config, "health"))
 @inject
 async def ready(
     request: Request,

backend/app/api/subroutes/pastes.py

@@ -1,6 +1,5 @@
 import logging
 from typing import TYPE_CHECKING
-from uuid import uuid4
 
 from dependency_injector.wiring import Provide, inject
 from fastapi import APIRouter, Depends, HTTPException
@@ -20,7 +19,7 @@
 )
 from app.config import config
 from app.containers import Container
-from app.ratelimit import get_ip_address, limiter
+from app.ratelimit import create_limit_resolver, get_exempt_key, limiter
 from app.services.paste_service import PasteService
 from app.utils.LRUMemoryCache import LRUMemoryCache
 
@@ -46,19 +45,11 @@ def set_cache(cache_instance: "RedisCache | LRUMemoryCache"):
 delete_token_key_header = APIKeyHeader(name="Authorization", scheme_name="Delete Token")
 
 
-def get_exempt_key(request: Request) -> str:
-    auth_header = request.headers.get("Authorization")
-    if not auth_header or auth_header != config.BYPASS_TOKEN:
-        return get_ip_address(request)
-
-    return str(uuid4())  # To simulate a new request if it is the BYPASS_TOKEN
-
-
 @pastes_route.get(
     "/legacy/{paste_id}",
     responses={404: {"model": ErrorResponse}, 200: {"model": LegacyPasteResponse}},
 )
-@limiter.limit("10/minute", key_func=get_exempt_key)
+@limiter.limit(create_limit_resolver(config, "get_paste_legacy"), key_func=get_exempt_key)
 @inject
 async def get_paste(
     request: Request,
@@ -105,7 +96,7 @@ async def get_paste(
     "/{paste_id}",
     responses={404: {"model": ErrorResponse}, 200: {"model": PasteResponse}},
 )
-@limiter.limit("10/minute", key_func=get_exempt_key)
+@limiter.limit(create_limit_resolver(config, "get_paste"), key_func=get_exempt_key)
 @inject
 async def get_paste(
     request: Request,
@@ -148,7 +139,7 @@ async def get_paste(
 
 
 @pastes_route.post("", response_model=CreatePasteResponse)
-@limiter.limit("4/minute", key_func=get_exempt_key)
+@limiter.limit(create_limit_resolver(config, "create_paste"), key_func=get_exempt_key)
 @inject
 async def create_paste(
     request: Request,
@@ -159,7 +150,7 @@ async def create_paste(
 
 
 @pastes_route.put("/{paste_id}")
-@limiter.limit("4/minute", key_func=get_exempt_key)
+@limiter.limit(create_limit_resolver(config, "edit_paste"), key_func=get_exempt_key)
 @inject
 async def edit_paste(
     request: Request,
@@ -183,7 +174,7 @@ async def edit_paste(
 
 
 @pastes_route.delete("/{paste_id}")
-@limiter.limit("4/minute", key_func=get_exempt_key)
+@limiter.limit(create_limit_resolver(config, "delete_paste"), key_func=get_exempt_key)
 @inject
 async def delete_paste(
     request: Request,