readur/docs/quickstart/self-hosting.md

Self-Hosting Quick Start

Purpose

Get Readur running on your own server in 15 minutes. This guide covers the essential steps for a basic self-hosted deployment.

Prerequisites

• Linux server (Ubuntu 20.04+ or similar)
• Docker and Docker Compose installed
• 4GB RAM minimum (8GB recommended)
• 20GB free disk space for documents
• Domain name (optional, for HTTPS access)

Step 1: Download Readur

Clone the repository and navigate to the directory:

git clone https://github.com/readur/readur.git
cd readur

Step 2: Configure Environment

Create your environment file from the template:

cp .env.example .env

Edit the .env file with essential settings:

# Core settings
APP_SECRET_KEY=your-secret-key-here  # Generate with: openssl rand -hex 32
POSTGRES_PASSWORD=secure-password-here
ADMIN_PASSWORD=your-admin-password

# Storage (choose one)
STORAGE_BACKEND=local  # or 's3' for cloud storage
LOCAL_STORAGE_PATH=/data/readur/documents

# Optional: External access
APP_HOST=0.0.0.0  # Allow external connections
APP_PORT=8000

Step 3: Start Services

Launch Readur with Docker Compose:

docker-compose up -d

Monitor the startup process:

docker-compose logs -f

Wait for the message: Application startup complete

Step 4: Access Readur

Open your browser and navigate to:

• Local access: http://localhost:8000
• Network access: http://your-server-ip:8000

Login with default credentials:

• Username: admin
• Password: (the one you set in ADMIN_PASSWORD)

Step 5: Initial Setup

Upload Your First Document

1. Click Upload in the top navigation
2. Select PDF or image files
3. Enable Process with OCR for scanned documents
4. Click Upload Files

Configure OCR Languages

1. Go to Settings → OCR Configuration
2. Select your primary languages
3. Adjust OCR workers based on server capacity

Set Up Automatic Import (Optional)

1. Navigate to Settings → Sources
2. Add a watch folder:

   Path: /data/watch
   Auto-process: Enabled
   OCR: Enabled
   

3. Any files placed in this folder will be automatically imported

Next Steps

Security Hardening

For production use, implement these security measures:

1. Enable HTTPS: See Reverse Proxy Setup
2. Change default passwords: Update all default credentials
3. Configure firewall: Restrict access to necessary ports only
4. Enable authentication: Set up OIDC/SSO

Performance Optimization

Tune for your workload:

# In .env file
OCR_WORKERS=4  # Increase for faster processing
POSTGRES_MAX_CONNECTIONS=100
UPLOAD_MAX_SIZE_MB=100

Backup Configuration

Set up automated backups:

# Create backup script
cat > backup.sh << 'EOF'
#!/bin/bash
docker-compose exec postgres pg_dump -U readur > backup-$(date +%Y%m%d).sql
tar -czf documents-$(date +%Y%m%d).tar.gz /data/readur/documents
EOF

chmod +x backup.sh

Troubleshooting

Container Won't Start

Check logs for specific errors:

docker-compose logs readur
docker-compose logs postgres

OCR Not Processing

Verify OCR service is running:

docker-compose ps
docker-compose logs ocr-worker

Can't Access from Browser

Check firewall settings:

sudo ufw allow 8000/tcp

Verify service is listening:

netstat -tlnp | grep 8000

Related Documentation

• Complete Self-Hosting Guide - Comprehensive setup and configuration
• Storage Configuration - S3, WebDAV, and local storage options
• Performance Tuning - Optimize for your hardware
• Backup Strategies - Protect your data