CodeSource
/
Readur
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Readur/docs/self-hosting/index.md

9.8 KiB
Raw Blame History

Self-Hosting Guide

Overview

This comprehensive guide covers everything you need to successfully self-host Readur in your own infrastructure. Whether you're deploying for personal use, your organization, or offering it as a service, this guide provides complete instructions for setup, configuration, and maintenance.

Self-Hosting Options

Docker Deployment (Recommended)

The simplest and most reliable deployment method:

  • Single-server setup: All components on one machine (standard deployment)
  • Docker Compose: Manage containers easily
  • Note: Readur is a single-instance application and does not support clustering or multiple server instances

Quick Start with Docker →

Bare Metal Installation

Direct installation on Linux servers:

  • System packages: Install from distribution repositories
  • From source: Build and install manually
  • SystemD services: Managed by system init

Bare Metal Installation →

Cloud Platform Deployment

Deploy on managed cloud services:

  • AWS: EC2, RDS, S3, and ECS
  • Google Cloud: Compute Engine, Cloud SQL, GCS
  • Azure: Virtual Machines, Database, Blob Storage
  • DigitalOcean: Droplets, Managed Database, Spaces

Cloud Deployment Guide →

System Requirements

Minimum Requirements

For personal use or small teams (1-10 users):

  • CPU: 2 cores (x86_64 or ARM64)
  • RAM: 4GB
  • Storage: 20GB for system + document storage
  • OS: Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+)
  • Docker: Version 20.10+ (if using containers)

Recommended Production Setup

For organizations (10-100 users):

  • CPU: 4-8 cores
  • RAM: 16GB
  • Storage: 100GB SSD for system, 1TB+ for documents
  • Database: PostgreSQL 14+ with 50GB storage
  • Cache: Redis 6+ with 2GB RAM
  • Network: 100Mbps+ connection

Enterprise Scale

For large deployments (100+ users):

  • Server: Single high-performance server with ample resources
  • CPU: 8-16 cores for concurrent processing
  • RAM: 32GB+ for large document processing
  • Database: PostgreSQL with performance tuning
  • Storage: S3-compatible object storage for scalability
  • Note: Vertical scaling only - add more resources to the single server

Installation Methods

Method 1: Docker Compose (Simplest)

Perfect for single-server deployments:

# Download and configure
git clone https://github.com/readur/readur.git
cd readur
cp .env.example .env
nano .env  # Configure settings

# Start services
docker-compose up -d

# Verify installation
docker-compose ps
curl http://localhost:8000/health

Detailed Docker Guide →

Method 2: Kubernetes (Container Orchestration)

For production deployments with container orchestration:

# readur-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: readur
spec:
  replicas: 1  # MUST be 1 - Readur doesn't support multiple instances
  selector:
    matchLabels:
      app: readur
  template:
    metadata:
      labels:
        app: readur
    spec:
      containers:
      - name: readur
        image: readur/readur:latest
        ports:
        - containerPort: 8000

Kubernetes Deployment →

Method 3: Ansible Automation

Automated deployment across multiple servers:

# playbook.yml
- hosts: readur_servers
  roles:
    - postgresql
    - redis
    - readur
  vars:
    readur_version: "2.5.4"
    postgres_version: "14"

Ansible Playbook →

Configuration

Essential Configuration

These settings must be configured before first run:

# Security
APP_SECRET_KEY=<generate-with-openssl-rand-hex-32>
ADMIN_PASSWORD=<strong-password>

# Database
DATABASE_URL=postgresql://user:pass@localhost/readur
POSTGRES_PASSWORD=<secure-password>

# Storage
STORAGE_BACKEND=s3  # or 'local'
S3_BUCKET=readur-documents
S3_ACCESS_KEY_ID=<your-key>
S3_SECRET_ACCESS_KEY=<your-secret>

Complete Configuration Reference →

Storage Configuration

Choose and configure your storage backend:

Local Storage

STORAGE_BACKEND=local
LOCAL_STORAGE_PATH=/data/readur/documents

S3-Compatible Storage

STORAGE_BACKEND=s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=my-readur-bucket
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Storage Setup Guide →

Authentication Setup

Configure authentication methods:

Local Authentication

AUTH_METHOD=local
ENABLE_REGISTRATION=false
REQUIRE_EMAIL_VERIFICATION=true

OIDC/SSO Integration

AUTH_METHOD=oidc
OIDC_ISSUER=https://auth.company.com
OIDC_CLIENT_ID=readur
OIDC_CLIENT_SECRET=<secret>

Authentication Guide →

Network Configuration

Reverse Proxy Setup

Configure NGINX for HTTPS:

server {
    listen 443 ssl http2;
    server_name readur.company.com;
    
    ssl_certificate /etc/ssl/certs/readur.crt;
    ssl_certificate_key /etc/ssl/private/readur.key;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Reverse Proxy Guide →

Firewall Configuration

Essential firewall rules:

# Allow HTTPS
sudo ufw allow 443/tcp

# Allow SSH (restrict to your IP)
sudo ufw allow from YOUR_IP to any port 22

# Enable firewall
sudo ufw enable

Backup and Recovery

Automated Backups

Set up daily backups with retention:

#!/bin/bash
# backup.sh

# Backup database
pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql

# Backup documents (if local storage)
tar -czf documents-$(date +%Y%m%d).tar.gz /data/readur/documents

# Upload to S3
aws s3 cp backup-*.sql s3://backups/readur/
aws s3 cp documents-*.tar.gz s3://backups/readur/

# Clean old backups (keep 30 days)
find . -name "backup-*.sql" -mtime +30 -delete

Backup Strategy Guide →

Disaster Recovery

Restore from backup:

# Restore database
PGPASSWORD="${DB_PASSWORD}" psql -h localhost -U readur -d readur < backup-20240315.sql

# Restore documents
tar -xzf documents-20240315.tar.gz -C /

# Verify integrity by checking document count
docker-compose exec readur psql -U readur -d readur -c "SELECT COUNT(*) FROM documents;"

Security Hardening

Security Checklist

  • Change all default passwords
  • Enable HTTPS with valid certificates
  • Configure firewall rules
  • Disable unnecessary services
  • Enable audit logging
  • Set up intrusion detection
  • Regular security updates
  • Implement rate limiting

Security Best Practices →

SSL/TLS Configuration

Obtain and configure SSL certificates:

# Using Let's Encrypt
sudo certbot certonly --webroot -w /var/www/html -d readur.company.com

# Auto-renewal
sudo certbot renew --dry-run

Monitoring and Maintenance

Health Monitoring

Set up monitoring endpoints:

# Health check
curl http://localhost:8000/health

# Metrics
curl http://localhost:8000/metrics

# Status page
curl http://localhost:8000/status

Monitoring Setup →

Performance Tuning

Optimize for your workload:

# OCR processing
OCR_WORKERS=4
OCR_MAX_PARALLEL=8
OCR_QUEUE_SIZE=100

# Database connections
POSTGRES_MAX_CONNECTIONS=200
DATABASE_POOL_SIZE=20

# Caching
REDIS_MAX_MEMORY=4gb
CACHE_TTL=3600

Performance Guide →

Updates and Upgrades

Keep your installation current:

# Backup first
./backup.sh

# Pull latest version
docker-compose pull

# Run migrations
docker-compose exec readur alembic upgrade head

# Restart services
docker-compose down && docker-compose up -d

Update Procedures →

Troubleshooting

Common Issues

Service Won't Start

# Check logs
docker-compose logs readur
journalctl -u readur

# Verify permissions
ls -la /data/readur/

OCR Not Processing

# Check worker status
docker-compose logs ocr-worker

# Monitor queue
redis-cli llen ocr_queue

Database Connection Failed

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Check firewall
telnet postgres_host 5432

Complete Troubleshooting Guide →

Migration from Other Systems

Migrating from Paperless-ngx

# Export from Paperless
python manage.py document_exporter ../export

# Import to Readur
python import_paperless.py ../export --preserve-metadata

Migrating from Mayan EDMS

# Use migration tool
python migrate_mayan.py \
  --source-db postgresql://mayan_db \
  --target-db postgresql://readur_db

Migration Guide →

Support and Resources

Getting Help

Useful Commands

# View logs
docker-compose logs -f

# Access shell
docker-compose exec readur bash

# Database console
docker-compose exec postgres psql -U readur

# Redis CLI
docker-compose exec redis redis-cli

# Run management command
# For Rust CLI tools:
docker-compose exec readur /app/migrate_to_s3 --help
# Or during development:
docker-compose exec readur cargo run --bin migrate_to_s3 -- --help

Next Steps

  1. Complete installation
  2. Configure storage backend
  3. Set up authentication
  4. Enable HTTPS
  5. Configure backups
  6. Set up monitoring