← Blog Guides & tutorials • 12 min read Self-host Paperless-ngx: your own document archive
Follow this on your own server. Start your 14-day trial
A drawer full of paper and a folder of scattered PDFs named scan_0042.pdf have the same problem: the moment you need one specific document, you can’t find it. Paperless-ngx fixes that by turning every scan, invoice, contract and letter into a searchable, OCR’d, tagged archive you own. It does the job that paid document-management SaaS does, running the text recognition on your own hardware so the contents of your tax returns and medical records never touch a third party’s servers. By the end of this guide you’ll have Paperless-ngx running on your own server, reachable over HTTPS at your own domain, backed by Postgres and Redis, OCR’ing everything you drop into a watch folder, with a backup that actually restores.
Two things decide whether a Paperless install is good or a liability. The first is the OCR language: Paperless reads the text off your documents once, at the moment it files them, so the language has to be set correctly before you consume anything, not after. The second is backing up the original documents, not just the database. Paperless keeps your structured data, tags and search index in Postgres, but the actual scanned files live on disk in a separate directory. A database dump without those files is a catalogue of documents you no longer have. This setup gets both right from the start.
What you’ll need
- A server. Paperless itself is light at rest, but OCR is CPU-heavy in bursts: a 2 vCPU / 2 GB VPS is a comfortable floor, and 1 GB works if you’re patient and consume documents in small batches. Any Ubuntu 24.04 box works.
- A domain name (or subdomain) with access to its DNS.
- Docker and the Docker Compose plugin on the server (Step 2).
- SSH access and a terminal.
Step 1: Create the server and point a domain at it
Create an Ubuntu 24.04 server with at least 2 GB of RAM, and note its public IP.
In your DNS, add an A record for a subdomain, for example paperless.yourdomain.com, pointing at that IP:
Type: A
Name: paperless
Value: <your server's IP>
TTL: 300
Confirm it resolves before continuing, since TLS depends on it:
dig paperless.yourdomain.com +short
That should print your server’s IP.
Step 2: Install Docker
SSH in and install Docker Engine with the Compose plugin:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Log out and back in for the group change to take effect, then check both pieces are present:
docker --version
docker compose version
You should see a Docker version and a Compose version printed, with no “command not found” errors.
Step 3: Lay out the project and its secrets
Create a directory for the stack and an .env file for everything that shouldn’t live in the compose file:
mkdir -p ~/paperless && cd ~/paperless
Paperless signs session cookies and other tokens with a secret key. Treat it the way you’d treat an encryption key: generate a long random one, and keep it, because a restore onto a fresh box needs the same key. Generate it:
openssl rand -base64 48
Create .env with that key, your domain, a database password, your timezone, the OCR language, and the first admin account:
# .env
PAPERLESS_SECRET_KEY=<paste the key you just generated>
PAPERLESS_URL=https://paperless.yourdomain.com
PAPERLESS_DBPASS=<a long random password>
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_TIME_ZONE=America/New_York
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=<a strong password>
DOMAIN=paperless.yourdomain.com
Set its permissions so only your user can read it:
chmod 600 .env
A word on PAPERLESS_OCR_LANGUAGE. The value eng installs and uses the English OCR model. If your documents are in another language, or more than one, set it to the matching Tesseract code, and list several joined with +, for example PAPERLESS_OCR_LANGUAGE=eng+fra+deu for English, French and German. The languages you name here are downloaded into the image on first boot. Get this right before you consume documents: Paperless OCRs each file once as it files it, so a document consumed under the wrong language stays wrong until you re-process it by hand.
Step 4: Write the Docker Compose file
Paperless-ngx is three cooperating services. The webserver is Paperless itself, which also runs the background task worker that does the OCR. Redis is the task broker those workers pull jobs from. Postgres is the database. Paperless can run on SQLite, but Postgres is what it recommends for anything you intend to keep, and it’s the difference between a snappy archive and one that locks up during a bulk import.
Create docker-compose.yml:
services:
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:2.13
restart: unless-stopped
depends_on:
db:
condition: service_healthy
broker:
condition: service_healthy
environment:
- PAPERLESS_REDIS=redis://broker:6379
- PAPERLESS_DBHOST=db
- PAPERLESS_DBPASS=${PAPERLESS_DBPASS}
- PAPERLESS_SECRET_KEY=${PAPERLESS_SECRET_KEY}
- PAPERLESS_URL=${PAPERLESS_URL}
- PAPERLESS_OCR_LANGUAGE=${PAPERLESS_OCR_LANGUAGE}
- PAPERLESS_TIME_ZONE=${PAPERLESS_TIME_ZONE}
- PAPERLESS_ADMIN_USER=${PAPERLESS_ADMIN_USER}
- PAPERLESS_ADMIN_PASSWORD=${PAPERLESS_ADMIN_PASSWORD}
volumes:
- data:/usr/src/paperless/data
- media:/usr/src/paperless/media
- ./consume:/usr/src/paperless/consume
- export:/usr/src/paperless/export
networks:
- paperless-net
broker:
image: redis:7-alpine
restart: unless-stopped
volumes:
- redis:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
interval: 5s
timeout: 5s
retries: 10
networks:
- paperless-net
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
- POSTGRES_DB=paperless
- POSTGRES_USER=paperless
- POSTGRES_PASSWORD=${PAPERLESS_DBPASS}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U paperless"]
interval: 5s
timeout: 5s
retries: 10
networks:
- paperless-net
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
environment:
- DOMAIN=${DOMAIN}
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
- caddy_config:/config
depends_on:
- webserver
networks:
- paperless-net
networks:
paperless-net:
volumes:
data:
media:
export:
redis:
pgdata:
caddy_data:
caddy_config:
A few choices worth explaining:
- The Paperless image is pinned to
2.13rather thanlatest. A document archive that silently upgrades itself on a restart, running database migrations you didn’t read the notes for, is not a good trade. You upgrade on your own schedule, covered in Step 7. - The webserver publishes no ports to the host. Only Caddy faces the internet; Paperless, Redis and Postgres are reachable only on the internal Docker network.
PAPERLESS_DBHOST=dbandPAPERLESS_REDIS=redis://broker:6379point Paperless at the other two services by their compose names. Default to those and Paperless would fall back to SQLite and an in-process broker.
The volumes are the part to understand, because they’re what you’re actually protecting:
mediais the original documents — every PDF, scan and image Paperless has filed, plus the archived OCR’d versions. This is the irreplaceable one. Lose it and you’ve lost your archive even if the database is perfectly intact, because the database only holds the metadata that points at these files.dataholds Paperless’s own state: the full-text search index, the classification model and other working files. It’s rebuildable from the documents and database, but worth keeping anyway.consumeis the watch folder — the inbox you drop scans into (bind-mounted to./consumeso it’s easy to reach from the host). Paperless watches it, OCRs and files whatever appears, then removes the original from the folder.exportis where Paperless writes its self-contained backup export in Step 6. Optional, but the clean way to get a restorable copy out.
Step 5: Write the Caddyfile and start everything
Paperless’s webserver listens on port 8000. Caddy handles the Let’s Encrypt certificate automatically, as long as DNS already points at the server and ports 80 and 443 are reachable. Create Caddyfile in the same directory:
{$DOMAIN} {
reverse_proxy webserver:8000
}
Start the stack:
docker compose up -d
First boot takes a minute or two: Paperless runs its database migrations and downloads the OCR language data you asked for. Watch it come up and confirm Caddy got a certificate:
docker compose logs -f caddy
docker compose logs -f webserver
You should see a line about a certificate obtained for your domain, and the webserver log settling into a ready state with no migration errors. Then open https://paperless.yourdomain.com and log in with the PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD from your .env. That admin account was created automatically on first boot, so there’s no separate setup screen to click through.
Step 6: Back up the documents and the database together
This is the step people get wrong, and they find out when a restore is a catalogue pointing at files that no longer exist. Paperless ships its own tool for exactly this: document_exporter writes a single, self-contained directory holding every document together with all its metadata, tags, correspondents and document types, in a format Paperless can import back cleanly onto a fresh install. Make that your primary backup:
docker compose exec webserver document_exporter ../export
That writes into the export volume. Pull it off the server as a tarball and keep it elsewhere:
docker run --rm -v paperless_export:/data -v $(pwd):/backup alpine \
tar czf /backup/paperless-export-$(date +%F).tar.gz -C /data .
The export is restorable on its own, but it’s worth also keeping a raw copy of the media volume and a Postgres dump, both from the same point in time, as a second line of defence:
# the original documents
docker run --rm -v paperless_media:/data -v $(pwd):/backup alpine \
tar czf /backup/paperless-media-$(date +%F).tar.gz -C /data .
# the database
docker compose exec -T db pg_dump -U paperless paperless > "paperless-db-$(date +%F).sql"
Put all of this in a cron job and copy the results to object storage or another machine. A backup that lives only on the server it protects doesn’t survive the failure that destroys the server.
One thing travels separately: your PAPERLESS_SECRET_KEY. A restore needs the same key the export was made under, so back up the .env file to somewhere access-controlled, apart from the archive itself. Restoring onto a fresh box is the mirror image: bring the stack up once so the volumes and database exist, then run document_exporter’s counterpart, document_importer ../export, against the extracted export. The documents and metadata come back together, which is the whole point of using the exporter over a bare file-plus-dump restore.
Step 7: Upgrade Paperless-ngx without surprises
Check the tag you’re running, read the release notes between it and the one you’re moving to (Paperless occasionally changes defaults or runs one-way data migrations), then bump the tag in docker-compose.yml:
image: ghcr.io/paperless-ngx/paperless-ngx:2.14
Take a Step 6 export first, always, then pull and restart:
docker compose pull webserver
docker compose up -d
Paperless runs any needed database migrations on boot, and rebuilds its full-text search index automatically when the index format changes between versions, so there’s nothing to trigger by hand for that. You should see the webserver log show a clean startup with no failed migration, and your documents should all still be searchable when you log back in. If a migration does fail, the export from Step 6 is the way back. Never point a latest tag at an archive you care about and let a restart decide when to migrate it.
Consuming documents: the daily workflow
With the stack running, the actual day-to-day is simple: get files into the consume folder and Paperless does the rest. Drop a PDF or image into ~/paperless/consume on the server, and within a few seconds Paperless OCRs it, pulls out a date and a title, applies any matching tags, correspondents and document types you’ve set up, files it into the archive, and deletes it from the watch folder. You can also upload straight from the web UI, point a network scanner at the folder over a share, or set up a dedicated mailbox so emailed attachments get consumed automatically. The web interface is where you then search the full text of everything, not just the filenames — which is the entire reason to run this instead of a folder of PDFs.
The shortcut: do it with Railyard
Everything above — Paperless-ngx backed by Postgres and Redis, with a generated secret key, the original documents on a persistent volume, OCR configured, and HTTPS already wired up — is also a one-click template:
https://app.railyard.run/deploy?template=paperless-ngx
That gives you the same architecture this guide builds by hand: the Paperless webserver, a dedicated Postgres and a Redis broker, with the media volume holding your actual documents so they survive restarts and redeploys, TLS handled for you at your own domain, and scheduled backups configured so the thing this guide spends the most care on — keeping the documents, not just the database — is already right. Because it’s a multi-service stack rather than a single container, pick it from the templates catalogue and confirm its services rather than deploying straight from the link.
If you want to understand what runs on your server first, what happens on your server when you connect walks through it, and databases and backups explains how scheduled backups work across every template. For how the one-click link format itself works, see deploy button.
Troubleshooting
Caddy never gets a certificate, or the browser shows a certificate warning. This is almost always DNS, not Caddy. Run dig paperless.yourdomain.com +short from your own machine and confirm it returns the server’s IP, not an old one and not nothing. Let’s Encrypt also needs port 80 reachable for its initial validation, so check your cloud provider’s firewall allows inbound 80 and 443, not just 443.
Documents land in the consume folder but nothing happens to them. The task worker isn’t picking them up, which almost always means Redis isn’t reachable. Check docker compose logs broker is healthy and that PAPERLESS_REDIS=redis://broker:6379 matches the broker service name. Also confirm you’re dropping files into the host’s ./consume directory, the one bind-mounted into the container, not a different folder.
OCR produces garbage, empty text, or the wrong language. PAPERLESS_OCR_LANGUAGE doesn’t match the documents, or the language data wasn’t installed. Confirm the code is a valid Tesseract one (eng, fra, deu, joined with + for several), restart so the image downloads it, and re-process the affected documents from the UI — changing the setting doesn’t retroactively re-OCR what was already filed under the old one.
Logins fail or assets 404 after switching to HTTPS. Paperless needs to know its own public address. Confirm PAPERLESS_URL is set to the full https:// URL and matches the domain Caddy serves. Without it, Paperless builds redirect and asset URLs from the wrong host.
Postgres keeps restarting, or Paperless can’t connect to the database. Check docker compose logs db first. The usual cause is a PAPERLESS_DBPASS changed in .env after the Postgres volume was first initialized; Postgres only reads that variable on the very first boot with an empty data directory, so the volume still has the old password. Set it back, or remove the pgdata volume to initialize fresh — which erases the database, so only before you have real documents.
Restored a backup and documents are missing or show as broken. The database came back but the media volume didn’t, or the two came from different points in time. Use the document_exporter / document_importer pair from Step 6, which keeps documents and metadata together, rather than restoring a bare dump without the files it references.
FAQ
Do I need Postgres and Redis, or can Paperless run on its own? Paperless can fall back to SQLite and an in-process broker, which is fine to try it out, but Postgres and Redis are what it recommends for an archive you actually rely on, and they’re what keep bulk imports and full-text search from stalling. Starting with them, as this guide does, avoids a migration later.
What about Office documents — Word, Excel, ODT? The three-service core here handles PDFs and images, which is the bulk of what most people archive. For Office formats, add the optional gotenberg and tika services: Tika extracts the text and Gotenberg converts the file to a PDF for the archive. They’re a clean add-on to this compose file rather than part of the core, so leave them out until you actually need them.
How much does this cost to run? The server, roughly $10–18/month for a 2 GB VPS. Paperless-ngx itself is free, open-source software with no per-document or per-user fee — you’re paying for the box the OCR runs on, not for what it processes.
What happens if I lose the secret key? Existing sessions and signed tokens become invalid, and a restore made under a different key won’t line up cleanly, which is why Step 6 backs up .env separately. Your documents themselves live in the media volume and aren’t encrypted with that key, but keeping the key with your backup is what makes a clean document_importer restore possible.
Can I let several people use it? Yes. Paperless has its own users, groups and per-document permissions, managed from the admin area under the account you set in .env. Everyone reaches the same instance over HTTPS; there’s no per-seat cost because you own the server it runs on.
Either path gets you the same thing in the end: your own document archive, your own files searchable by their contents, and no monthly bill that grows with the size of the drawer you’re finally emptying.
Why people pick Railyard for this
- Your own cloud account. Deploy to DigitalOcean, Hetzner, Vultr, AWS, OVHcloud, or any Linux server over SSH, billed directly by your provider with no markup.
- One flat price per team. Launch is $22 a month with 2 servers and 1 seat. Scale is $45 with 5 servers and 5 seats, Team is $79 with 10 servers and 15 seats, and Agency is $149 with 20 servers and unlimited seats. Unlimited apps on every plan, no charge per app, per deploy or per gigabyte, and a 14-day trial to start.
- One-click templates. Deploy open-source apps, like databases, analytics and dev tools, to your own server in one click.
- Managed databases. Postgres, MySQL and Redis with scheduled, restore-verified backups and point-in-time recovery.
- Push-to-deploy. Deploy from GitHub, GitLab or the CLI, with automatic HTTPS and zero-downtime releases.