Configuration Guide¶

This guide covers all configuration options available in Readur through environment variables and runtime settings.

📖 See Also: For a complete reference of all configuration options including S3 storage and advanced settings, see the Configuration Reference.

Table of Contents¶

• Environment Variables
• Core Configuration
• File Storage & Upload
• Watch Folder Configuration
• OCR & Processing Settings
• Search & Performance
• Data Management
• Port Configuration
• Example Configurations
• Configuration Priority
• Runtime Settings vs Environment Variables
• Database Tuning

Environment Variables¶

All application settings can be configured via environment variables:

Core Configuration¶

File Storage & Upload¶

Watch Folder Configuration¶

OCR & Processing Settings¶

Note: These settings can also be configured per-user via the web interface

Search & Performance¶

Data Management¶

Port Configuration¶

Readur supports flexible port configuration:

# Method 1: Specify full server address
SERVER_ADDRESS=0.0.0.0:8000

# Method 2: Use separate host and port (recommended)
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# For development: Configure frontend port
CLIENT_PORT=5173
BACKEND_PORT=8000

Example Configurations¶

Development Configuration¶

# Basic development setup
DATABASE_URL=postgresql://readur:readur@localhost/readur
JWT_SECRET=dev-secret-key-not-for-production
SERVER_ADDRESS=0.0.0.0:8000
UPLOAD_PATH=./uploads
WATCH_FOLDER=./watch
OCR_LANGUAGE=eng
CONCURRENT_OCR_JOBS=2

Production Configuration¶

# Core settings
DATABASE_URL=postgresql://readur:secure_password@postgres:5432/readur
JWT_SECRET=your-very-long-random-secret-key-generated-with-openssl
SERVER_ADDRESS=0.0.0.0:8000

# File handling
UPLOAD_PATH=/app/uploads
ALLOWED_FILE_TYPES=pdf,png,jpg,jpeg,tiff,bmp,gif,txt,rtf,doc,docx

# Watch folder for NFS mount
WATCH_FOLDER=/mnt/nfs/documents
WATCH_INTERVAL_SECONDS=60
FILE_STABILITY_CHECK_MS=1000
MAX_FILE_AGE_HOURS=168
FORCE_POLLING_WATCH=1

# OCR optimization
OCR_LANGUAGE=eng
CONCURRENT_OCR_JOBS=8
OCR_TIMEOUT_SECONDS=600
MAX_FILE_SIZE_MB=200
AUTO_ROTATE_IMAGES=true
ENABLE_IMAGE_PREPROCESSING=true

# Performance tuning
MEMORY_LIMIT_MB=2048
CPU_PRIORITY=high
ENABLE_COMPRESSION=true
ENABLE_BACKGROUND_OCR=true

# Search optimization
SEARCH_RESULTS_PER_PAGE=50
SEARCH_SNIPPET_LENGTH=300
FUZZY_SEARCH_THRESHOLD=0.7

# Data management
RETENTION_DAYS=2555  # 7 years
ENABLE_AUTO_CLEANUP=true

Network Filesystem Configuration¶

# For NFS mounts
WATCH_FOLDER=/mnt/nfs/documents
WATCH_INTERVAL_SECONDS=60
FILE_STABILITY_CHECK_MS=1000
FORCE_POLLING_WATCH=1

# For SMB/CIFS mounts
WATCH_FOLDER=/mnt/smb/shared
WATCH_INTERVAL_SECONDS=30
FILE_STABILITY_CHECK_MS=2000

# For S3 mounts (using s3fs)
WATCH_FOLDER=/mnt/s3/bucket
WATCH_INTERVAL_SECONDS=120
FILE_STABILITY_CHECK_MS=5000
FORCE_POLLING_WATCH=1

Configuration Priority¶

Settings are applied in this order (later values override earlier ones):

1. Application defaults (built into the code)
2. Environment variables (system-wide configuration)
3. User settings (per-user database settings via web interface)

This allows for flexible deployment where system administrators can set defaults while users can customize their experience.

Runtime Settings vs Environment Variables¶

Some settings can be configured in two ways:

1. Environment Variables: Set at container startup, affects the entire application
2. User Settings: Configured per-user via the web interface, stored in database

Environment variables take precedence and provide system-wide defaults. User settings override these defaults for individual users where applicable.

Settings configurable via web interface: - OCR language preferences - Search result limits - File type restrictions - OCR processing options - Data retention policies

Database Tuning¶

For better search performance with large document collections:

-- Increase shared_buffers for better caching
ALTER SYSTEM SET shared_buffers = '256MB';

-- Optimize for full-text search
ALTER SYSTEM SET default_text_search_config = 'pg_catalog.english';

-- Restart PostgreSQL after changes

Security Configuration¶

Generating Secure Secrets¶

# Generate secure JWT secret
JWT_SECRET=$(openssl rand -base64 64)

# Generate secure database password
DB_PASSWORD=$(openssl rand -base64 32)

# Save to .env file
cat > .env << EOF
JWT_SECRET=${JWT_SECRET}
DB_PASSWORD=${DB_PASSWORD}
EOF

Quick Reference - Essential Variables¶

For a minimal production deployment, configure these essential variables:

# Security (REQUIRED)
JWT_SECRET=your-secure-random-key-here
DATABASE_URL=postgresql://user:password@host:port/database

# File Storage
UPLOAD_PATH=/app/uploads
WATCH_FOLDER=/path/to/mounted/folder

# Watch Folder (for network mounts)
WATCH_INTERVAL_SECONDS=60
FORCE_POLLING_WATCH=1

# Performance
CONCURRENT_OCR_JOBS=4
MAX_FILE_SIZE_MB=100

Next Steps¶

• Review deployment options for production setup
• Learn about folder watching for automatic document ingestion
• Optimize OCR performance for your use case