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¶

Security and Access Control¶

These settings are read at startup. Invalid values (for example a malformed CIDR, an out-of-range JWT_TTL_HOURS, an invalid CORS origin, or a Boolean other than true/false/1/0/yes/no/on/off) stop the server with an error.

Related API behavior:

• POST /api/auth/logout revokes all sessions of the current user.
• POST /api/auth/password lets a signed-in user change their own password.
• /api/ocr/health requires authentication; POST /api/ocr/perform has been removed.
• Source API responses do not include stored WebDAV passwords or S3 secret keys. The source config instead carries has_password / has_secret_access_key flags; omit the field or send an empty value on update to keep the stored secret. The settings response likewise has has_webdav_password instead of webdav_password.
• Document cleanup endpoints (DELETE /api/documents/cleanup/low/confidence, DELETE /api/documents/cleanup/failed/ocr and the cleanup preview) act on the caller's own documents, including for admins. An admin can pass ?all_users=true to act on all users' documents.
• OIDC login completes at /auth/callback#code=...; the frontend exchanges the one-time code at POST /api/auth/oidc/exchange. The token is not placed in the URL query.

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¶

Database Connection Priority¶

The database connection can be configured in two ways:

1. Using DATABASE_URL (takes priority if set):

   DATABASE_URL=postgresql://username:password@host:port/database
   

2. Using individual PostgreSQL variables (used if DATABASE_URL is not set):

   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   POSTGRES_DB=readur
   POSTGRES_USER=readur
   POSTGRES_PASSWORD=your_password
   

This flexibility allows for easy deployment across different platforms: - Docker/Kubernetes: Often provide individual variables - Heroku/Railway: Typically provide DATABASE_URL - Local Development: Use either method based on preference

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: "<output of: openssl rand -hex 32>"
  S3_ACCESS_KEY_ID: "AKIAIOSFODNN7EXAMPLE"
  S3_SECRET_ACCESS_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Helm Chart Values¶

The Helm chart (charts/readur) manages the initial ADMIN_PASSWORD in a Secret named <release>-auth. When no value is given, it is generated randomly on install and kept on upgrade. The Secret has helm.sh/resource-policy: keep, so it also remains after helm uninstall. JWT_SECRET is optional: set auth.jwtSecret (or include it in auth.existingSecret) to manage it yourself; otherwise Readur keeps a generated key in its database. A JWT_SECRET already stored in the Secret by an earlier chart version is kept.

GitOps / helm template: keeping generated values across upgrades relies on Helm's lookup function, which only works when Helm talks to the cluster (helm install / helm upgrade). Renderers that do not, such as helm template and Argo CD, cannot see the existing Secret and would generate new random values on every render, signing out all users and changing the admin password. With these tools, set auth.existingSecret to a Secret you manage (for example with Sealed Secrets or External Secrets), or set both auth.jwtSecret and auth.adminPassword explicitly.

# Read the initial admin password
kubectl get secret <release>-auth -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d

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