stupa-pdf-api/docs/CONFIGURATION.md

Configuration Guide

This guide covers all configuration options for the STUPA PDF API system.

Environment Variables

The application is configured using environment variables. These can be set in a .env file in the project root or passed directly to Docker.

Database Configuration

Variable	Description	Default	Required
MYSQL_HOST	MySQL server hostname	db	Yes
MYSQL_PORT	MySQL server port	3306	Yes
MYSQL_DB	Database name	stupa	Yes
MYSQL_USER	Database user	stupa	Yes
MYSQL_PASSWORD	Database password	None	Yes
MYSQL_ROOT_PASSWORD	MySQL root password	None	Yes

Example:

MYSQL_HOST=db
MYSQL_PORT=3306
MYSQL_DB=stupa
MYSQL_USER=stupa
MYSQL_PASSWORD=secure_password_here
MYSQL_ROOT_PASSWORD=secure_root_password_here

Authentication

Variable	Description	Default	Required
MASTER_KEY	Master key for admin access	None	Yes

Security Notes:

• Generate a strong, random master key
• Never commit the master key to version control
• Rotate the master key periodically
• Use different keys for each environment

Example:

MASTER_KEY=your_very_secure_master_key_here

Rate Limiting

Variable	Description	Default	Required
RATE_IP_PER_MIN	Requests per minute per IP	60	No
RATE_KEY_PER_MIN	Requests per minute per key	30	No

Notes:

• Rate limiting is disabled for localhost and Docker internal IPs
• Adjust based on your expected traffic
• Set to 0 to disable rate limiting (not recommended for production)

Example:

RATE_IP_PER_MIN=60
RATE_KEY_PER_MIN=30

Application Settings

Variable	Description	Default	Required
TZ	Timezone for the application	Europe/Berlin	No
QSM_TEMPLATE	Path to QSM PDF template	/app/assets/qsm.pdf	No
VSM_TEMPLATE	Path to VSM PDF template	/app/assets/vsm.pdf	No

Example:

TZ=Europe/Berlin
QSM_TEMPLATE=/app/assets/qsm.pdf
VSM_TEMPLATE=/app/assets/vsm.pdf

Frontend Configuration

Variable	Description	Default	Required
NODE_ENV	Node environment	production	No
VITE_API_URL	API URL for frontend	/api	No

Example:

NODE_ENV=production
VITE_API_URL=/api

Advanced Configuration

CORS Configuration

For production deployments, configure CORS appropriately:

# In service_api.py (for reference)
CORS_ORIGINS = os.getenv("CORS_ORIGINS", "").split(",")
# Or hardcode in production
CORS_ORIGINS = ["https://your-domain.com"]

Database Connection Pool

Configure connection pooling for better performance:

# Optional database pool settings
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
DB_POOL_TIMEOUT=30
DB_POOL_RECYCLE=3600

File Upload Limits

Control file upload constraints:

# Maximum upload size in bytes (100MB)
MAX_UPLOAD_SIZE=104857600
# Maximum attachments per application
MAX_ATTACHMENTS_PER_APP=30
# Maximum size per attachment (50MB)
MAX_ATTACHMENT_SIZE=52428800

Logging Configuration

Configure logging levels and outputs:

# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO
# Log format: json, text
LOG_FORMAT=json
# Log file path (optional)
LOG_FILE=/var/log/stupa-api.log
# Enable access logs
ENABLE_ACCESS_LOGS=true

Session Configuration

Control session behavior:

# Session timeout in seconds (1 hour)
SESSION_TIMEOUT=3600
# Session cookie settings
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_HTTPONLY=true
SESSION_COOKIE_SAMESITE=strict

Docker Compose Configuration

Port Mapping

Default port configuration in docker-compose.yml:

services:
  frontend:
    ports:
      - "3000:80"  # Frontend on port 3000
  api:
    ports:
      - "8000:8000"  # API on port 8000
  db:
    ports:
      - "3306:3306"  # MySQL on port 3306
  adminer:
    ports:
      - "8080:8080"  # Adminer on port 8080

To change ports, modify the left side of the mapping:

ports:
  - "8080:80"  # Change frontend to port 8080

Volume Configuration

Persistent data storage:

volumes:
  db_data:  # MySQL data

For development, you can add more volumes:

volumes:
  - ./backend/src:/app/src  # Hot reload for backend
  - ./frontend/src:/usr/share/nginx/html  # Hot reload for frontend

Network Configuration

Services communicate on an internal Docker network. To customize:

networks:
  stupa_network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

Production Configuration

SSL/TLS Configuration

For HTTPS in production, use a reverse proxy:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

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

    location / {
        proxy_pass http://localhost:3000;
    }

    location /api/ {
        proxy_pass http://localhost:8000/;
    }
}

Environment-Specific Files

Create environment-specific configuration:

# Development
.env.development

# Staging
.env.staging

# Production
.env.production

Load the appropriate file:

docker compose --env-file .env.production up -d

Security Headers

Add security headers in production:

# Enable security headers
SECURE_HEADERS=true
# HSTS settings
HSTS_ENABLED=true
HSTS_MAX_AGE=31536000
HSTS_INCLUDE_SUBDOMAINS=true
# CSP settings
CSP_ENABLED=true
CSP_POLICY="default-src 'self'"

Backup Configuration

Configure automated backups:

# Enable backups
BACKUP_ENABLED=true
# Backup schedule (cron format)
BACKUP_SCHEDULE="0 2 * * *"
# Backup retention days
BACKUP_RETENTION_DAYS=30
# Backup destination
BACKUP_PATH=/backups
# S3 backup (optional)
BACKUP_S3_BUCKET=stupa-backups
BACKUP_S3_REGION=eu-central-1

Performance Tuning

MySQL Configuration

Optimize MySQL for your workload:

# my.cnf
[mysqld]
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M
innodb_flush_method = O_DIRECT
max_connections = 200

API Worker Configuration

Configure Uvicorn workers:

# Number of worker processes
WEB_CONCURRENCY=4
# Worker class
WORKER_CLASS=uvicorn.workers.UvicornWorker
# Worker timeout
WORKER_TIMEOUT=300

Frontend Build Optimization

For production builds:

# Enable production optimizations
VITE_BUILD_COMPRESS=true
VITE_BUILD_SOURCEMAP=false
VITE_BUILD_MINIFY=true

Monitoring Configuration

Health Check Configuration

Configure health check parameters:

# Health check interval in seconds
HEALTH_CHECK_INTERVAL=30
# Health check timeout
HEALTH_CHECK_TIMEOUT=5
# Health check retries
HEALTH_CHECK_RETRIES=3

Metrics Configuration

Enable metrics collection:

# Enable Prometheus metrics
ENABLE_METRICS=true
METRICS_PORT=9090
# Enable application metrics
COLLECT_APP_METRICS=true

Troubleshooting Configuration Issues

Validation

Validate your configuration:

# Check Docker Compose configuration
docker compose config

# Test environment variables
docker compose run --rm api env

# Verify database connection
docker compose exec api python -c "from service_api import get_db; db = next(get_db()); print('DB OK')"

Common Issues

1. Database Connection Failed

   • Check MYSQL_HOST is correct
   • Ensure database service is healthy
   • Verify credentials match

2. Rate Limiting Too Restrictive

   • Increase RATE_IP_PER_MIN
   • Check if IP is excluded

3. File Upload Fails

   • Check MAX_UPLOAD_SIZE
   • Verify disk space
   • Check nginx client_max_body_size

4. CORS Errors

   • Configure CORS_ORIGINS
   • Check frontend VITE_API_URL

Configuration Best Practices

1. Use Strong Passwords

   • Minimum 20 characters
   • Use password generator
   • Different for each environment

2. Separate Environments

   • Never use production credentials in development
   • Use different master keys
   • Isolate databases

3. Version Control

   • Commit .env.example
   • Never commit .env
   • Document all variables

4. Regular Updates

   • Review configuration quarterly
   • Update dependencies
   • Rotate credentials

5. Monitoring

   • Log configuration changes
   • Alert on failures
   • Track performance metrics