How to Set Up Paperless-ngx Using Docker Compose
Stop digging through paper stacks and build your own searchable digital archive. This guide makes it easy to set up Paperless-ngx with Docker Compose in under an hour.
Publish date: 7/8/2025
Stop digging through paper stacks and build your own searchable digital archive. This guide makes it easy to set up Paperless-ngx with Docker Compose in under an hour.
Publish date: 7/8/2025
Let's be honest: managing paper is a pain. Whether it's a mountain of receipts for tax season or a filing cabinet overflowing with contracts and letters, finding what you need is a chore. What if you could turn that chaos into your own private, searchable database?
That's exactly what Paperless-ngx, a powerful open-source tool, is designed to do. Paired with the simplicity of Docker Compose, you can set up a personal document server that automatically scans, indexes, and organizes your files, getting you up and running in less than an hour.
Paperless-ngx is a community-driven fork of the original Paperless project, designed to scan, index, and archive all your physical documents. Think of it as your personal Google Drive, but specifically engineered for scanned documents with powerful OCR (Optical Character Recognition) capabilities. It automatically recognizes text in your scanned documents, making them fully searchable, even handwritten notes in many cases.
The beauty of Paperless-ngx lies in its simplicity. You scan a document, drop it in a folder, and the system automatically processes it, extracts the text, tags it based on your rules, and files it away. Need to find that warranty from three years ago? Just search for it.
Docker Compose simplifies the deployment process by bundling all the necessary components—the web server, database, and Redis cache—into a single, manageable configuration. Instead of manually installing and configuring each component, you define everything in a YAML file and let Docker handle the heavy lifting.
This approach offers several advantages:
Before diving into the installation, make sure you have:
First, let's create a dedicated directory for Paperless-ngx. This keeps everything organized and makes backups easier.
sudo mkdir -p /opt/paperless-ngx
cd /opt/paperless-ngx
I prefer using /opt for application data, but you can choose any location that suits your setup.
Paperless-ngx uses environment variables for configuration. Create a .env file to store these settings:
sudo nano .env
Add the following configuration, adjusting the values to fit your needs:
# Security
PAPERLESS_SECRET_KEY=generate_a_very_long_random_string_here
PAPERLESS_ALLOWED_HOSTS=localhost,your-server-ip,your-domain.com
# Timezone and locale
PAPERLESS_TIME_ZONE=America/New_York
PAPERLESS_OCR_LANGUAGE=eng
# Admin account
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=choose_a_strong_password
PAPERLESS_ADMIN_MAIL=your-email@example.com
# Optional: Enable automatic login (development only)
# PAPERLESS_AUTO_LOGIN_USERNAME=admin
# Performance tuning
PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=2
Important security note: Generate a truly random secret key. You can use the openssl command:
openssl rand -hex 32
When setting PAPERLESS_ALLOWED_HOSTS, you may need to find your server's IP address.
Now for the heart of our setup. Create a docker-compose.yml file:
sudo nano docker-compose.yml
Here's a production-ready configuration using PostgreSQL and Redis:
services:
broker:
image: docker.io/library/redis:8-alpine
restart: unless-stopped
volumes:
- redisdata:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 30s
timeout: 10s
retries: 3
db:
image: docker.io/library/postgres:17-alpine
restart: unless-stopped
volumes:
- pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: paperless
POSTGRES_USER: paperless
POSTGRES_PASSWORD: paperless_db_password
healthcheck:
test: ["CMD-SHELL", "pg_isready -U paperless"]
interval: 30s
timeout: 10s
retries: 3
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:latest
restart: unless-stopped
depends_on:
db:
condition: service_healthy
broker:
condition: service_healthy
ports:
- "8010:8000"
volumes:
- data:/usr/src/paperless/data
- media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export
- ./consume:/usr/src/paperless/consume
env_file: .env
environment:
PAPERLESS_REDIS: redis://broker:6379
PAPERLESS_DBHOST: db
PAPERLESS_DBUSER: paperless
PAPERLESS_DBPASS: paperless_db_password
volumes:
data:
media:
pgdata:
redisdata:
This configuration uses health checks to ensure services start in the correct order, preventing common startup issues.
Paperless-ngx needs directories for document intake and export.
mkdir -p consume export
sudo chown -R 1000:1000 consume export
The consume directory is where you'll drop documents for processing, while export is used for backups.
Time to bring everything online:
sudo docker compose up -d
Monitor the startup process to ensure everything initializes correctly:
sudo docker compose logs -f
Wait for the message indicating the web server has started. This typically takes a minute or two on the first run.
Success! Open your web browser and navigate to http://your-server-ip:8010.
Log in using the admin credentials you specified in the .env file, and you're ready to start uploading documents!
Setting up Paperless-ngx with Docker Compose transforms document management from a chore into an automated, searchable system. The initial setup takes less than an hour, but the time saved searching for documents pays dividends for years. Why not give it a try?
That said, if you're looking to host Paperless-ngx with reliability and performance in mind, xTom offers a range of infrastructure solutions, including dedicated servers, colocation services, and more. For smaller deployments or testing, our sister brand, V.PS, provides affordable and scalable NVMe KVM VPS hosting, perfect for Paperless-ngx.
Thanks for reading!
Storage requirements depend on your document volume and quality. As a rough estimate, 1,000 scanned documents with OCR data typically use 2-5GB. Plan for growth and remember that Paperless-ngx stores both the original files and the archived PDF versions.
Yes, but with limitations. Modern OCR engines can recognize neat handwriting, but accuracy varies significantly. For best results with handwritten notes, make sure you use a high-quality scan and that the writing is as clear as possible.
Paperless-ngx has a built-in importer that handles raw files, and the community has developed scripts for migrating from systems like Evernote or other databases. The easiest path is often exporting your documents as PDFs and dropping them into the consume folder.
Paperless-ngx processes PDFs, images (JPEG, PNG, TIFF), and plain text files. It can also handle Microsoft Office documents if you install additional dependencies. The system converts all compatible files into PDF/A format for long-term archival.
Several mobile scanning apps work well with Paperless-ngx. Popular choices like Genius Scan or Microsoft Lens can be configured to upload scanned documents directly to your consume folder via FTP, WebDAV, or other cloud integrations.
Yes, Paperless-ngx is fully multi-user capable. From the admin settings, you can create additional users and assign them specific permissions for viewing, editing, or administering documents, making it suitable for teams and families.