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:**
```env
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:**
```env
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:**
```env
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:**
```env
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:**
```env
NODE_ENV=production
VITE_API_URL=/api
```

## Advanced Configuration

### CORS Configuration

For production deployments, configure CORS appropriately:

```python
# 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:

```env
# 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:

```env
# 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:

```env
# 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:

```env
# 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`:

```yaml
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:
```yaml
ports:
  - "8080:80"  # Change frontend to port 8080
```

### Volume Configuration

Persistent data storage:

```yaml
volumes:
  db_data:  # MySQL data
```

For development, you can add more volumes:
```yaml
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:

```yaml
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:

```nginx
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:

```bash
# Development
.env.development

# Staging
.env.staging

# Production
.env.production
```

Load the appropriate file:
```bash
docker compose --env-file .env.production up -d
```

### Security Headers

Add security headers in production:

```env
# 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:

```env
# 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:

```cnf
# 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:

```env
# 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:

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

## Monitoring Configuration

### Health Check Configuration

Configure health check parameters:

```env
# 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:

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

## Troubleshooting Configuration Issues

### Validation

Validate your configuration:

```bash
# 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