Skip to content

README.md

Latest commit

 

History

History
246 lines (180 loc) · 6.12 KB

README.md

File metadata and controls

246 lines (180 loc) · 6.12 KB

Configuration Guide

This directory contains preset configuration files for different deployment scenarios. Choose the preset that matches your use case.

Quick Start

# For local development
cp config/local.env.example .env

# For team dashboards
cp config/team.env.example .env

# For production deployments
cp config/production.env.example .env

Then edit .env to customize values for your environment.

Preset Comparison

Feature Local Team Production
API Key Auth Disabled Required Required
Rate Limiting Disabled 100 req/min 30 req/min
Secret Key Dev placeholder Custom required Strong required
Best For Personal dev/testing Internal teams Public access

When to Use Each Preset

Local (local.env.example)

Use when:

  • You're the only user
  • Running on your local machine
  • Testing or developing
  • Learning how the tool works

Features:

  • No authentication required (faster iteration)
  • No rate limiting (run as many scans as needed)
  • Placeholder secret key (don't worry about security locally)

Start the dashboard:

cp config/local.env.example .env
python tools/dashboard/app.py
# Open http://localhost:5000

Team (team.env.example)

Use when:

  • Multiple people need access
  • Running on an internal server
  • Sharing results with colleagues
  • CI/CD pipelines need access

Features:

  • API key authentication (share key with team)
  • Moderate rate limiting (prevents accidental abuse)
  • Requires secure secret key

Setup:

cp config/team.env.example .env

# Generate and set your API key
python -c "import secrets; print(secrets.token_urlsafe(24))"
# Add the output to DASHBOARD_API_KEY in .env

# Generate and set your secret key
python -c "import secrets; print(secrets.token_hex(32))"
# Add the output to FLASK_SECRET_KEY in .env

python tools/dashboard/app.py

Using with API key:

# Include key in requests
curl -H "X-API-Key: your-api-key" http://your-server:5000/api/reviews

# Or as query parameter
curl "http://your-server:5000/api/reviews?api_key=your-api-key"

Production (production.env.example)

Use when:

  • Dashboard is publicly accessible
  • High security requirements
  • External users/clients have access
  • Running in cloud infrastructure

Features:

  • Strong API key required
  • Strict rate limiting (30 req/min per IP)
  • Requires cryptographically secure secret key
  • Designed to run behind reverse proxy with HTTPS

Setup:

cp config/production.env.example .env

# Generate strong credentials
python -c "import secrets; print('API Key:', secrets.token_urlsafe(32))"
python -c "import secrets; print('Secret:', secrets.token_hex(32))"
# Add both to .env

# Run with gunicorn (not the development server)
pip install gunicorn
gunicorn -w 4 -b 127.0.0.1:5000 tools.dashboard.app:app

Nginx reverse proxy example:

server {
    listen 443 ssl;
    server_name reviews.yourcompany.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Feature Reference

API Key Authentication

When DASHBOARD_API_KEY is set, all requests must include the key:

Method How to Include
Header X-API-Key: your-key
Query param ?api_key=your-key

Why enable it:

  • Prevents unauthorized access
  • Allows tracking who's using the API
  • Required for any shared or public deployment

Why disable it (local only):

  • Faster development iteration
  • No need to manage keys for personal use

Rate Limiting

Controls how many requests per IP address are allowed within a time window.

Setting Description
RATE_LIMIT_REQUESTS Max requests per window (0 = disabled)
RATE_LIMIT_WINDOW Window size in seconds

Examples:

  • 100 requests / 60 seconds = 100 requests per minute
  • 30 requests / 60 seconds = 30 requests per minute (stricter)
  • 0 requests = disabled (no limit)

Why enable it:

  • Prevents abuse and DoS attempts
  • Ensures fair resource sharing
  • Protects server from overload

CSRF Protection

Always enabled automatically. Protects form submissions from cross-site request forgery attacks.

No configuration needed - works out of the box when FLASK_SECRET_KEY is set.

Secret Key

FLASK_SECRET_KEY is used for:

  • Session security
  • CSRF token generation
  • Any cryptographic operations

Generate a secure key:

python -c "import secrets; print(secrets.token_hex(32))"

Requirements by preset:

  • Local: Placeholder is fine
  • Team: Must be unique, keep secret from public
  • Production: Must be cryptographically random, minimum 32 characters

Environment Variables Reference

Variable Required Default Description
DASHBOARD_API_KEY No None API key for authentication (empty = disabled)
RATE_LIMIT_REQUESTS No 100 Max requests per window (0 = disabled)
RATE_LIMIT_WINDOW No 60 Rate limit window in seconds
FLASK_SECRET_KEY Yes Auto-generated Secret key for sessions and CSRF

Troubleshooting

"Invalid or missing API key" error

  • Check that your DASHBOARD_API_KEY matches what you're sending
  • Ensure the header is X-API-Key (case-sensitive)
  • Try the query parameter method: ?api_key=your-key

"Rate limit exceeded" error

  • Wait for the rate limit window to reset
  • Increase RATE_LIMIT_REQUESTS if legitimate
  • Check if multiple users share the same IP

CSRF token errors

  • Ensure FLASK_SECRET_KEY is set
  • Clear browser cookies and try again
  • Check that forms include the CSRF token

Dashboard won't start

  • Verify .env file exists in project root
  • Check for syntax errors in .env (no spaces around =)
  • Ensure all required dependencies are installed