Paperless-NGX On-Demand: Zero-Idle Cloud Architecture with Task-Draining Watchdog (~$2/month on AWS)

[plthomasva]

Hello Paperless-NGX community!

I wanted to share a project I just created and open-sourced that brings an automated, zero-cost-idle architecture to Paperless-NGX on AWS:

🔗 GitHub Repository: https://github.com/plthomasva/paperless-ngx-on-demand
📖 Live Documentation: https://plthomasva.github.io/paperless-ngx-on-demand/

Why build this?

Many personal and home users want the reliability and offsite durability of cloud hosting, but paying for a 24/7 VPS or cloud server for occasional document indexing is overkill.

Existing "serverless" approaches often struggle with Paperless-NGX because it relies on persistent background Celery workers, Redis, Tesseract OCR, and Whoosh full-text search indexing that cannot run cleanly on ephemeral containers without severe cold starts or broken indexing state.

Architecture Highlights:

• CloudFront + KeyValueStore Router: Global edge distribution routes web traffic. When compute is cold, users receive an instant dark-mode splash page (~50ms) while the instance boots.
• Fast Graviton Instance (t4g.medium): Boots in ~45–60 seconds (hardware start + Paperless container/worker initialization). On boot, mount-s3 mounts the S3 media library, starts Docker Compose, verifies Paperless health on port 8000, and updates KVS to route traffic directly to the instance.
• Task-Draining Watchdog: The instance only shuts down when:
  1. No web requests for 15 minutes (/tmp/access.log).
  2. Redis Celery queue is empty (LLEN celery == 0).
  3. No active jobs in /api/tasks/.
  4. No OCR (tesseract, ocrmypdf) processes running.
  5. S3 consume inbox is drained.
• Online Database Durability: Uses SQLite's online .backup API to flush WAL journals and upload consistent database snapshots to S3 before halting.
• Monthly Cost: ~$1.90 – $2.04/month total for typical home archivist volume.

External Setup Requirements:

• AWS Account
• Domain name & DNS (e.g. Cloudflare or Route 53)
• Free AWS ACM SSL Certificate in us-east-1

Feedback, suggestions, and architectural reviews from the community are warmly welcome!