Configuration Reference¶

This document provides a comprehensive reference for all configuration options available in Readur, including environment variables, configuration files, and runtime settings.

Environment Variables¶

Core Configuration¶

Authentication & Security¶

OIDC/SSO Configuration¶

Storage Configuration¶

Local Storage¶

S3 Storage¶

Watch Directory Configuration¶

OCR Configuration¶

Database Configuration¶

Performance & Resources¶

Notification Configuration¶

Monitoring & Metrics¶

Network Configuration¶

Feature Flags¶

Configuration Files¶

Main Configuration (readur.yml)¶

# readur.yml - Main configuration file
server:
  address: 0.0.0.0
  port: 8080
  workers: 4

database:
  url: postgresql://readur:password@localhost/readur
  max_connections: 32
  min_connections: 5

storage:
  type: s3  # or 'local'
  s3:
    bucket: readur-documents
    region: us-east-1
    prefix: documents/

ocr:
  enabled: true
  language: eng+fra+deu
  concurrent_jobs: 4
  timeout: 300

auth:
  jwt_secret: ${JWT_SECRET}
  session_timeout: 3600

oidc:
  enabled: false
  client_id: ${OIDC_CLIENT_ID}
  client_secret: ${OIDC_CLIENT_SECRET}
  issuer_url: https://auth.example.com

Docker Compose Override¶

# docker-compose.override.yml
version: '3.8'
services:
  readur:
    environment:
      - DATABASE_URL=postgresql://readur:${DB_PASSWORD}@db:5432/readur
      - JWT_SECRET=${JWT_SECRET}
      - S3_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - S3_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - LOG_LEVEL=debug
    volumes:
      - ./config/readur.yml:/app/config/readur.yml:ro

Kubernetes ConfigMap¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: readur-config
data:
  SERVER_PORT: "8080"
  DATABASE_MAX_CONNECTIONS: "50"
  OCR_LANGUAGE: "eng+spa+fra"
  CONCURRENT_OCR_JOBS: "8"
  LOG_LEVEL: "info"
  CORS_ALLOWED_ORIGINS: "https://app.example.com"

Kubernetes Secret¶

apiVersion: v1
kind: Secret
metadata:
  name: readur-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgresql://readur:password@postgres:5432/readur"
  JWT_SECRET: "your-secure-random-secret-min-32-chars"
  S3_ACCESS_KEY_ID: "AKIAIOSFODNN7EXAMPLE"
  S3_SECRET_ACCESS_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Configuration Precedence¶

Configuration values are loaded in the following order (later sources override earlier ones):

1. Default values (built into application)
2. Configuration file (readur.yml)
3. Environment variables
4. Command-line arguments
5. Database settings (for user-specific settings)

Multi-Environment Configuration¶

Development¶

# .env.development
DATABASE_URL=postgresql://readur:readur@localhost/readur_dev
SERVER_PORT=8080
LOG_LEVEL=debug
OCR_ENABLED=false
S3_ENABLED=false
CORS_ALLOWED_ORIGINS=http://localhost:3000

Staging¶

# .env.staging
DATABASE_URL=postgresql://readur:${DB_PASSWORD}@db-staging.internal/readur_staging
SERVER_PORT=8080
LOG_LEVEL=info
S3_ENABLED=true
S3_BUCKET_NAME=readur-staging
CORS_ALLOWED_ORIGINS=https://staging.readur.app

Production¶

# .env.production
DATABASE_URL=postgresql://readur:${DB_PASSWORD}@db-prod.internal/readur_prod
SERVER_PORT=8080
LOG_LEVEL=warn
S3_ENABLED=true
S3_BUCKET_NAME=readur-production
CORS_ALLOWED_ORIGINS=https://readur.app
RATE_LIMIT_ENABLED=true
PROMETHEUS_ENABLED=true

Dynamic Configuration¶

Some settings can be changed at runtime without restart:

User Settings (per-user)¶

• Theme preference
• Language preference
• Items per page
• Email notifications
• OCR default language

System Settings (admin only)¶

• OCR concurrent jobs
• Rate limits
• Feature flags
• Notification settings

Access via API:

# Get current settings
GET /api/settings

# Update settings
PUT /api/settings
{
  "ocr_concurrent_jobs": 6,
  "rate_limit_per_minute": 200
}

Configuration Validation¶

Readur validates configuration on startup:

# Test configuration
readur --config-test

# Validate specific file
readur --config-file readur.yml --validate

# Show effective configuration
readur --show-config

Common validation errors:

Invalid database URL: The database connection string format is incorrect or malformed.

Error: Invalid DATABASE_URL format
Expected: postgresql://user:pass@host:port/database

1. Missing required S3 credentials

   Error: S3_ENABLED=true but S3_ACCESS_KEY_ID not set
   

2. Path conflicts

   Error: UPLOAD_PATH and WATCH_FOLDER cannot be the same directory
   

Best Practices¶

Security¶

Never commit secrets: Always use environment variables or secret management systems to protect sensitive information.

# Use environment variables
JWT_SECRET=${JWT_SECRET}

# Or use secret management
JWT_SECRET=$(vault kv get -field=jwt_secret secret/readur)

Use strong secrets: Generate cryptographically secure secrets with sufficient entropy.

# Generate secure secrets
openssl rand -hex 32

Rotate secrets regularly: Implement a schedule for rotating sensitive credentials.

# Quarterly rotation
0 0 1 */3 * /scripts/rotate-secrets.sh

Performance¶

Tune database connections: Configure the optimal number of database connections based on your system's resources.

# Formula: connections = (worker_threads * 2) + management_connections
DATABASE_MAX_CONNECTIONS=$(($(nproc) * 2 + 5))

Optimize OCR workers: Set the appropriate number of concurrent OCR workers to balance performance and resource usage.

# Formula: ocr_workers = cpu_cores / 2
CONCURRENT_OCR_JOBS=$(($(nproc) / 2))

Configure caching: Set up appropriate cache sizes to improve response times while managing memory usage.

# Cache size based on available memory
CACHE_SIZE_MB=$(($(free -m | awk 'NR==2{print $7}') / 4))

Monitoring¶

Enable metrics in production: Turn on metrics collection to monitor system performance and health.

METRICS_ENABLED=true
PROMETHEUS_ENABLED=true

Set appropriate log levels: Configure logging verbosity based on your environment and debugging needs.

# Production
LOG_LEVEL=warn

# Debugging
LOG_LEVEL=debug

Configure alerts: Set up alerting to be notified of critical system events.

WEBHOOK_URL=https://alerts.example.com/readur

Troubleshooting Configuration¶

Debug Configuration Loading¶

# Enable verbose configuration logging
RUST_LOG=readur::config=debug readur

# Show configuration sources
readur --config-sources

Common Issues¶

1. Environment variable not loading
2. Check variable name (must match exactly)
3. Verify no spaces around =

4. Check for quotes in values

5. Configuration file ignored

6. Verify file path
7. Check YAML syntax

8. Ensure proper permissions

9. Settings not taking effect

10. Check configuration precedence
11. Verify no overrides
12. Some settings require restart

Migration from Previous Versions¶

From v1.x to v2.x¶

# Migration script
#!/bin/bash

# Update environment variables
sed -i 's/STORAGE_PATH/UPLOAD_PATH/g' .env
sed -i 's/OCR_WORKERS/CONCURRENT_OCR_JOBS/g' .env

# Add new required variables
echo "S3_ENABLED=false" >> .env
echo "ENABLE_PER_USER_WATCH=false" >> .env

From v2.x to v3.x¶

# New variables in v3.x
echo "OIDC_ENABLED=false" >> .env
echo "FEATURE_MULTI_LANGUAGE_OCR=true" >> .env