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.
What is Paperless-ngx?
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.
Why use Docker Compose for Paperless-ngx?
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:
- Consistency: Your setup works the same way on any system that supports Docker.
- Isolation: All components run in their own containers, preventing conflicts.
- Easy updates: Upgrading is as simple as pulling new images.
- Portability: Move your entire setup to a new server by copying a few files.
Prerequisites
Before diving into the installation, make sure you have:
- A Linux server (like Ubuntu or Debian).
- Docker and Docker Compose installed (which isn't difficult to do). Our guide, How to Install Docker and Docker Compose on Debian 12, should work for most modern Debian-based systems.
- At least 2GB of RAM (4GB recommended for better performance).
- Sufficient storage space for your documents.
Step-by-step installation guide
Step 1: Create your project structure
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.
Step 2: Configure environment variables
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=[email protected]
# 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.
Step 3: Create the Docker Compose configuration
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.
Step 4: Create consume and export directories
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.
Step 5: Launch Paperless-ngx
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.
Step 6: Access your Paperless-ngx instance
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!
Conclusion
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!
Frequently asked questions about Paperless-ngx
How much storage space do I need for Paperless-ngx?
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.
Can Paperless-ngx handle handwritten documents?
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.
Is it possible to migrate from other document management systems?
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.
What file formats does Paperless-ngx support?
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.
How do I set up mobile scanning?
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.
Can multiple users access the same Paperless-ngx instance?
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.