Paperless-ngx Docker Setup: 6 Easy Steps to a Paperless Life

I had a filing cabinet drawer so stuffed with old insurance paperwork that it stopped closing all the way. Two years ago I scanned the whole thing, shredded the originals, and now every document I own is searchable by typing two words into a browser tab. That’s the entire pitch for this project.

This is a paperless-ngx docker setup walkthrough for anyone who’s tired of hunting through folders for a warranty card or a tax document. If you’ve got a spare mini PC, an old laptop, or a NAS already running Docker, you can have this running in under 30 minutes — no coding required, just copy, paste, and edit a couple of files.

What Paperless-ngx Actually Does

Paperless-ngx is an open-source document management system that turns scanned paper into a searchable digital archive. Drop a PDF or image into a watched folder, and it runs OCR (optical character recognition) on it, guesses the document type and date, lets you tag it, and files it away — permanently searchable by any word in the document, not just the filename.

Under the hood, a full install runs a handful of Docker containers working together: a web server for the interface, a Postgres database for metadata, Redis for background task handling, and Gotenberg plus Tika for converting and parsing office documents. Docker Compose spins all of it up with one command instead of installing each piece by hand.

The organizational layer is what makes it actually useful long-term, not just a pile of searchable PDFs. Tags let you mark documents by category (tax, warranty, medical), correspondents track who a document is from or to (a utility company, your bank, a specific doctor), and document types separate invoices from letters from receipts. Combine those three with full-text search and you can find “that HVAC warranty from three years ago” in about five seconds, instead of digging through a box.

1. Install Docker and Docker Compose

If your homelab box doesn’t have Docker yet, install it first. On most Linux distros, the official install script handles Docker and the Compose plugin together:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in so the group change applies, then confirm it worked with docker compose version. If you’re running this on a Synology or QNAP NAS, use the built-in Container Manager app instead — the compose file below works the same way once pasted in.

2. Grab the Official Compose Files

Paperless-ngx ships an install script that pulls the right docker-compose.yml and environment file for you, which saves you from hand-typing service definitions:

mkdir -p ~/paperless-ngx && cd ~/paperless-ngx
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

The script asks a few questions — which database engine to use (Postgres is the default and the one I’d recommend), where to store your files, and whether to enable OCR on install. Answer those and it drops a working docker-compose.yml and docker-compose.env into the folder.

3. Configure the Environment File

Open docker-compose.env before you start the stack. Two settings matter most for a smooth first run:

PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_TIME_ZONE=America/Chicago
PAPERLESS_SECRET_KEY=change-this-to-something-random

Set PAPERLESS_OCR_LANGUAGE to match the documents you’ll actually scan — multiple languages can be combined with a plus sign, like eng+deu. Get the time zone right now; changing it after documents are indexed causes date-sorting headaches later.

4. Start the Stack

With the environment file saved, bring everything up in the background:

docker compose up -d

First launch takes a couple of minutes while Postgres initializes and the web server compiles its static assets. Check progress with docker compose logs -f webserver, and once it settles, the interface is live on port 8000.

5. Create Your Admin Account

Run this once the containers are healthy to create your login:

docker compose exec webserver createsuperuser

Follow the prompts for a username, email, and password, then log in at http://YOUR_SERVER_IP:8000. If you’re running Nginx Proxy Manager already, this is a good candidate to put behind a real domain with HTTPS instead of leaving it on plain HTTP and a raw port.

6. Set Up the Consumption Folder and Start Scanning

The consume folder is the whole workflow: drop any PDF, JPG, or PNG into it, and paperless-ngx picks it up automatically within about 30 seconds, runs OCR, guesses tags and a title, and files it. No upload button, no manual step — just drag a file in and it’s indexed.

This is where the right scanner changes the entire experience. A flatbed scanner or a phone photo works for a document here and there, but if you’re digitizing years of paperwork in one sitting, an automatic document feeder (ADF) scanner is the difference between an afternoon project and a weekend one.

The Fujitsu/Ricoh ScanSnap iX1600 was the scanner homelab and paperless-ngx communities recommended most often for years, but it’s become hard to find at a reasonable price. The Epson WorkForce ES-580W is the pick I point people to now — it scans double-sided pages automatically, has a 4.3″ touchscreen for quick destination presets, and supports scan-to-network-folder, which pairs perfectly with the consume folder above.

If you want to test the workflow before committing to a high-end scanner, the Brother ADS-1700W is a genuinely solid budget entry point. It’s compact, wireless, and handles the same core job — feed paper in, get a searchable PDF out — at a fraction of the cost.

FAQ: Paperless-ngx Docker Setup

Do I need a powerful server to run this?
No. Paperless-ngx runs comfortably on a low-power mini PC or even a Raspberry Pi 4/5 for personal use. OCR is the most CPU-intensive step, but it runs in the background and doesn’t need to be fast for a home-scale document volume.

Can I use my phone instead of a scanner?
Yes — apps that save to a synced folder (like a phone’s cloud backup pointed at your consume folder) work fine for occasional documents. For digitizing a backlog of hundreds of pages, an ADF scanner is dramatically faster and produces cleaner, straighter scans for OCR.

Is my data actually private, unlike scanning apps that upload to the cloud?
Yes, that’s the entire point of self-hosting it. Everything — documents, OCR text, tags — stays on your own hardware. Nothing leaves your network unless you deliberately expose it through a reverse proxy.

What happens if my server dies — do I lose everything?
Only if you skip backups, which you shouldn’t. The two folders that matter are your media directory (the actual document files) and your Postgres database volume (all the tags, correspondents, and metadata). Back up both together, on a schedule, to a second location — a NAS, an external drive, or cloud storage. A document management system you can’t restore isn’t much better than the drawer it replaced.

The Takeaway

A paperless-ngx docker setup takes less time to build than it takes to sort through one drawer of old paperwork by hand, and once it’s running, it just keeps working in the background. Start with the docker-compose install script, get your first admin login working, and don’t worry about a scanner until step six — the consume folder works fine with your phone while you decide if you want to go all-in.

Give it a weekend with your worst filing drawer. You’ll wonder why you waited this long to digitize it.

Running paperless-ngx already? Tell me what tagging setup you landed on — I’m still tweaking mine two years in.