Paperless-ngx Docker Compose Guide: OCR, Tags and Auto-Import

Somewhere in your home or office there is a drawer full of paper. Utility invoices, the lease, the car insurance policy, warranty slips that fade a little more every summer, and that letter from the tax office you swore you would never need again. Finding one specific page takes twenty minutes and some luck, and if the drawer ever gets wet, it is all gone. Paperless-ngx turns that drawer into a searchable archive: you scan a page or forward an email, it reads the text with OCR, figures out who sent it and what it is, tags it and files it away. Three years later you type “fridge warranty” and the PDF is on your screen in under a second.

In this guide we deploy Paperless-ngx with Docker Compose on a fresh VPS, teach it to read both Romanian and English, make it import documents automatically from a folder and from a mailbox, and build matching rules so invoices and contracts file themselves. Everything runs on your own server, with no subscription and no third party reading your bills.

What Paperless-ngx actually is

Paperless-ngx is a free, open source document management system. The project lives at github.com/paperless-ngx/paperless-ngx under the GPL-3.0 license, with official documentation at docs.paperless-ngx.com . It is the community-maintained successor of the original Paperless and Paperless-ng projects, and today it is the most active open source project in this space.

You hand it a document (a PDF, a phone photo of a page, a scanned image, and with an optional add-on even Word, Excel or email files) and it does four things:

1. Reads it with OCR. OCR, optical character recognition, is the process of turning the pixels of a scanned page into real text that a computer can search. Paperless-ngx uses the Tesseract engine through a tool called OCRmyPDF.
2. Keeps two copies. The original file stays untouched, and next to it Paperless creates an “archive version”: a PDF/A file with an invisible text layer, so you can select and copy text even from a crooked phone photo.
3. Classifies it. It assigns a correspondent, a document type, tags and a storage path, either through rules you write or through a small machine learning model that learns from your corrections.
4. Indexes it for full-text search, so you search inside every document, not just in file names.

A few words we will use throughout the guide:

• Correspondent: who the document comes from or goes to, such as Enel, Digi, your landlord or your accountant.
• Document type: what kind of document it is: invoice, contract, receipt, payslip.
• Tag: a free label. A document can have many tags: “to pay”, “car”, “2026”, “tax”.
• Storage path: the folder structure Paperless uses for the files on disk.
• Container: an application packaged with everything it needs, isolated from the rest of the system. Docker runs containers, and Docker Compose starts several containers together from a single file.
• Volume: storage that Docker keeps outside the container, so your data survives updates and restarts.
• Port: a numbered door on the server where a program listens: 22 for SSH, 80 for HTTP, 443 for HTTPS.
• Reverse proxy: a web server that sits in front of your apps, handles HTTPS certificates and forwards each request to the right app.

How the pieces fit together

Paperless-ngx is not a single program but a small stack. The main container runs the web interface, the document consumer and the OCR workers. PostgreSQL stores the metadata (titles, tags, users, rules), and Redis acts as a task queue, so heavy OCR work happens in the background while the interface stays responsive. In front of it we put Caddy for automatic HTTPS, and the UFW firewall makes sure only SSH, HTTP and HTTPS are reachable from the internet.

What you need

• A VPS with Debian 13 or Ubuntu 24.04, at least 2 vCPU and 2 GB of RAM (4 GB if you add the optional Office and email converters or scan a lot at once).
• Disk space: a scanned page usually takes about 100-300 KB, and Paperless keeps both the original and the archive copy, so a few thousand documents fit comfortably in 20-40 GB.
• A sudo user with SSH access (not root).
• A domain or subdomain, for example docs.example.ro, with an A record pointing to the VPS IP address.
• Optionally, a dedicated mailbox for invoices with IMAP access.
• A scanner, a multifunction printer with scan-to-email, or simply your phone camera.

A note on virtualization: Docker runs without surprises on a KVM VPS. On an unprivileged LXC container, Docker needs the “nesting” feature enabled, and some things (adding a swap file, loading firewall kernel modules) may be restricted. If docker run hello-world fails on an LXC plan, ask our support to check nesting, or pick a KVM plan.

How much RAM does Paperless-ngx use?

Most of the time Paperless is quiet. The heavy moment is OCR: while a multi-page scan is processed, the main container can briefly use more than a gigabyte. That is why we limit it to one worker on a small VPS. The figures below are approximate values from a 2 vCPU VPS; yours will vary with document size and settings.

The whole procedure at a glance

We will go through ten numbered steps. The first six install and secure the stack, the next three automate the filing, and the last one protects your archive.

Step 1: Prepare the server and the firewall

Log in over SSH with your sudo user and bring the system up to date. We also install the few tools we need later: ufw (the firewall), curl, CA certificates and openssl (to generate passwords).

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y ufw curl ca-certificates openssl

On Ubuntu 24.04, ufw is already installed but inactive; on Debian 13 it is not installed by default, so the line above takes care of it on both. Now open only the three ports we need. Allow SSH before enabling the firewall, otherwise you lock yourself out (if you moved SSH to another port, use that number instead of 22).

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

ufw enable asks for confirmation; type y. The status should show Status: active and the three rules. Port 80 is needed because Caddy uses it to obtain the HTTPS certificate. On an unprivileged LXC container, ufw enable can fail because the container cannot load firewall kernel modules; in that case ask our support how traffic filtering works on your plan.

Check whether the upgrade needs a reboot. Ubuntu creates the file /var/run/reboot-required when it does; Debian does not create this file by default, so on Debian simply reboot if the upgrade installed a new linux-image package.

[ -f /var/run/reboot-required ] && echo "Reboot needed" || echo "No reboot flag"
sudo reboot

Step 2: Install Docker and Docker Compose

We install Docker from Docker’s official repository, which gives us the current engine and the Compose v2 plugin (the docker compose command, with a space). The commands below work on both Debian and Ubuntu, because they read the distribution name from /etc/os-release.

sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker "$USER"

The last line adds your user to the docker group so you do not have to type sudo before every Docker command. Log out and back in for the group change to take effect, then test:

docker run --rm hello-world
docker compose version

You should see a “Hello from Docker!” message and something like Docker Compose version v2.x.x. Keep in mind that membership in the docker group is equivalent to root access, so only add trusted users to it.

Step 3: Create the project folder and the secrets

We keep everything in /opt/paperless. Inside, consume is the inbox folder Paperless watches, and export is where backups will land.

sudo mkdir -p /opt/paperless
sudo chown "$USER":"$USER" /opt/paperless
cd /opt/paperless
mkdir -p consume export
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
PAPERLESS_SECRET_KEY=$(openssl rand -hex 48)
EOF
chmod 600 .env
id -u; id -g

The .env file now holds a random database password and a random secret key that Paperless uses to sign sessions. Docker Compose reads .env automatically and substitutes the values into the compose file, so the secrets never appear in the YAML. The last command prints your user ID and group ID, usually 1000 and 1000. Note them: Paperless will run with the same IDs, so the files in consume and export stay yours.

Step 4: Write the paperless-ngx docker compose file

Create /opt/paperless/compose.yaml with nano compose.yaml and paste the following. Replace docs.example.ro with your real subdomain and, if id -u printed something other than 1000, adjust USERMAP_UID and USERMAP_GID.

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:17
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.18
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_URL: https://docs.example.ro
      PAPERLESS_TIME_ZONE: Europe/Bucharest
      PAPERLESS_OCR_LANGUAGES: ron
      PAPERLESS_OCR_LANGUAGE: ron+eng
      PAPERLESS_TASK_WORKERS: "1"
      PAPERLESS_THREADS_PER_WORKER: "2"
      PAPERLESS_CONSUMER_RECURSIVE: "true"
      PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS: "true"
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"

volumes:
  data:
  media:
  pgdata:
  redisdata:

What the important lines do:

• Image tags. We pin Redis to major version 7 and PostgreSQL to 17. Pinning PostgreSQL matters a lot: moving to a new major version (17 to 18) requires a dump and restore, and newer PostgreSQL images also changed where they store data, so never jump majors by accident. For Paperless-ngx we pinned the 2.18 release line that was current while we wrote this; check the releases page and use the current version. Using :latest is simpler but means a routine docker compose pull can bring a major upgrade you did not plan for.
• 127.0.0.1:8000:8000 publishes the web interface only on the server’s loopback address. This is crucial: Docker writes its own firewall rules that bypass UFW, so a plain 8000:8000 would expose Paperless to the whole internet over unencrypted HTTP, whatever UFW says. Caddy will reach it locally.
• PAPERLESS_URL must match the exact address you will use in the browser, otherwise logins fail with CSRF errors.
• PAPERLESS_OCR_LANGUAGES: ron installs the Romanian Tesseract pack when the container starts (the image ships with English, German, French, Italian and Spanish). PAPERLESS_OCR_LANGUAGE: ron+eng tells OCR to expect both languages, so diacritics in Romanian invoices and English contracts are recognized correctly.
• Workers and threads: one worker with two threads keeps OCR from eating all the RAM on a 2 GB VPS. On a 4 vCPU / 8 GB machine you can raise workers to 2.
• Recursive consumer with subfolders as tags: a file dropped in consume/invoices/ automatically gets the tag invoices.

Step 5: Start Paperless-ngx and create the admin account

Pull the images and start the stack in the background:

cd /opt/paperless
docker compose pull
docker compose up -d
docker compose ps

docker compose ps should list three services, all running (the webserver may show health: starting for a minute). The first start takes one to three minutes because Paperless installs the Romanian language pack and creates the database tables. Follow the logs and press Ctrl+C when you are done:

docker compose logs -f webserver

When you see a line saying the consumer is using inotify to watch /usr/src/paperless/consume, the app is ready. Now create the administrator account. The command starts a temporary container, asks for a username, an optional email and a password twice, and ends with Superuser created successfully.

docker compose run --rm webserver createsuperuser

A quick local check that the web server answers (expect a line like HTTP/1.1 302 Found, a redirect to the login page):

curl -sI http://127.0.0.1:8000 | head -n 1

Step 6: Put Paperless-ngx behind HTTPS with Caddy

Caddy is a web server that obtains and renews Let’s Encrypt certificates on its own. It is available in the official repositories of both Debian 13 and Ubuntu 24.04 (on Ubuntu it lives in the “universe” component, enabled by default). Make sure your DNS A record already points to the VPS, then:

sudo apt install -y caddy
sudo tee /etc/caddy/Caddyfile > /dev/null <<'EOF'
docs.example.ro {
    encode gzip
    reverse_proxy 127.0.0.1:8000
}
EOF
sudo systemctl reload caddy
sudo journalctl -u caddy -n 30 --no-pager

Replace docs.example.ro with your subdomain. Within a few seconds the journal should mention that the certificate was obtained successfully. Open https://docs.example.ro in your browser, log in with the admin account from step 5 and you will see the empty Paperless dashboard. Drag a PDF onto the page: it uploads, a progress notice appears, and a few seconds later the document shows up with its text recognized.

Step 7: Auto-import documents from a folder

Uploading through the browser is fine for one file. For everything else we use the consume folder: whatever lands in /opt/paperless/consume is imported, OCR-ed and then removed from the folder. Thanks to the settings in step 4, subfolders become tags.

From your laptop (Linux, macOS, or Windows with WSL), copy files with rsync over SSH:

rsync -av --remove-source-files ~/to-paperless/ user@docs.example.ro:/opt/paperless/consume/

We prefer rsync over plain scp because it writes to a temporary file and renames it only at the end, so Paperless never picks up a half-copied PDF. The --remove-source-files flag deletes each file from your local to-paperless folder after a successful transfer, so the next run does not send duplicates; use a dedicated outbox folder for this, not your only copy of your scans. If you create ~/to-paperless/invoices/ and ~/to-paperless/contracts/ locally, the documents arrive with the tags invoices and contracts.

Watch the import live on the server:

cd /opt/paperless
docker compose logs -f webserver

You will see a line about consuming the file and, after a few seconds per page, a message that consumption finished. If you send the same file twice, Paperless refuses it as a duplicate, which is exactly what you want.

Got a network scanner? Many multifunction printers offer “scan to email”, which is the easiest route: point it at the mailbox from the next step. Small businesses can also drop the PDFs of their e-invoices here in bulk at the end of the month.

Step 8: Auto-import documents from email

This is where Paperless becomes truly hands-off. Create a dedicated address, for example invoices@yourcompany.ro, and either give it to your suppliers or set up forwarding rules in your main mailbox. Paperless connects to it over IMAP (port 993, outbound from the VPS, which UFW allows by default) and imports the attachments.

In the web interface, open Mail in the sidebar and click Add Account:

• IMAP server: for example mail.yourcompany.ro
• IMAP port: 993, IMAP security: SSL
• Username / Password: the mailbox credentials. For large providers that use two-factor login, generate an app password instead of using your normal one.

Press Test to confirm the connection, then save. Next, click Add Rule and set:

• Account and Folder: your new account, folder INBOX.
• Filters (optional): filter by sender, subject, body or attachment file name, for example only messages from facturare@enel.ro.
• Maximum age: by default 30 days. Older messages are ignored, so raise it if you want to import an existing backlog.
• Consumption scope: “Only process attachments” is the usual choice.
• Action: mark as read, move to a folder (e.g. Processed), flag or delete. Moving to a folder keeps your inbox tidy and gives you an audit trail.
• Assign: tags, document type and correspondent. You can set the correspondent from the sender address or name, or pick a fixed one per rule.

Paperless checks mail every 10 minutes by default. Rules are evaluated in order, and you can have several per account: one for each important supplier, plus a catch-all at the end.

Step 9: Tags, correspondents and matching rules

This is the step that makes invoices and contracts file themselves. Every correspondent, document type, tag and storage path has a matching algorithm and a match field. When a document is imported, Paperless runs every rule against the OCR text and assigns whatever matches.

The matching algorithms

• None: never assigned automatically.
• Any word: matches if at least one of the words appears. digi rcs rds matches any of the three.
• All words: every word must appear somewhere in the document.
• Exact match: the exact phrase must appear.
• Regular expression: a pattern, for when you need precision.
• Fuzzy word: like exact match, but tolerant of small OCR errors.
• Auto: a machine learning classifier that learns from documents you already sorted by hand. It needs a handful of examples per item and retrains automatically every hour. New items default to Auto.

Tick Case insensitive for almost every rule. If your documents contain Romanian diacritics, OCR with ron will reproduce them, so add both spellings (with and without diacritics) to word-based rules.

A starter set of rules

Start explicit, then let Auto take over. A good pattern: create correspondents with explicit rules for your ten most common senders, leave the rest on Auto, and correct mistakes as you review. Every correction makes the classifier better.

Also create a tag called Inbox and tick Inbox tag in its settings. Paperless adds it to every new document, so you get a review queue: once a week, open the Inbox view, check the assignments, and remove the tag.

Workflows for everything else

For logic that is not “text contains X”, use Workflows (in the sidebar). A workflow has a trigger (Consumption Started, Document Added, Document Updated or Scheduled), optional filters (file name, source such as mail fetch or consume folder, existing tags) and actions (assign or remove tags, owner, permissions, custom fields, send an email or call a webhook). Example: every document that arrives through the invoices mail rule gets the owner “accounting” and the tag to pay; another workflow emails you when a document tagged contract is added.

Storage paths: a tidy folder tree on disk

By default files are stored with numeric names. Under Storage Paths, create one with a path template such as {{ correspondent }}/{{ created_year }}/{{ title }} and set it to match all documents (or by type). Now the files on disk are organized as Enel/2026/Invoice October.pdf, readable even without Paperless.

Step 10: Back up everything (and update safely)

Your archive is only as good as its backup. Paperless includes a document exporter that writes every original, every archive PDF and a manifest.json with all metadata (tags, correspondents, users, rules) into the export folder. Run it once by hand:

cd /opt/paperless
docker compose exec -T webserver document_exporter ../export
ls export | head

Running it again only updates what changed. Add --delete if you also want files of documents you deleted in Paperless removed from the export. Schedule it nightly with crontab -e:

0 3 * * * cd /opt/paperless && docker compose exec -T webserver document_exporter ../export > /dev/null 2>&1

A backup on the same disk is not a backup, so copy export to another machine, ideally encrypted, for example with rsync to a second server or with an encrypting tool such as restic. The export is also your exit door: the files are plain PDFs and JSON, and document_importer restores them into a fresh install.

To update, read the release notes, change the Paperless-ngx tag in compose.yaml, then:

cd /opt/paperless
docker compose pull
docker compose up -d
docker image prune -f

Run the exporter right before every update, so you have a fresh copy if something goes wrong.

Optional: Office documents and whole emails with Tika

Out of the box, Paperless handles PDFs and images. To import Word, Excel, LibreOffice files, or whole emails as .eml (the “Process message as .eml” scope in mail rules), add two helper containers: Gotenberg converts documents to PDF and Apache Tika extracts their text. Add these services to compose.yaml (at the same indentation as db):

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

Then add gotenberg and tika under the webserver’s depends_on, and these lines to its environment:

      PAPERLESS_TIKA_ENABLED: "1"
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

Apply with docker compose up -d. As the chart above shows, this adds roughly 500 MB of RAM, so plan for 4 GB. The Tika image uses :latest because it is a stateless converter; pin a specific version if you want fully reproducible deployments.

Troubleshooting and common mistakes

“CSRF verification failed” or 403 when logging in. PAPERLESS_URL does not match the address in your browser exactly (http vs https, www, a typo). Fix it in compose.yaml and run docker compose up -d.

Files sit in the consume folder and nothing happens. Check the logs first. The usual cause is permissions: the files must be readable by the user from USERMAP_UID. If the folder is a network mount (NFS, SMB), inotify events do not arrive; add PAPERLESS_CONSUMER_POLLING: "30" to make Paperless check every 30 seconds.

OCR text is garbage or diacritics are wrong. Confirm PAPERLESS_OCR_LANGUAGE: ron+eng and look in the startup logs for the Romanian pack installation. For documents imported before the fix, select them in the document list and use the bulk action to redo OCR.

The container restarts or the VPS freezes during a big import. That is the OCR spike. Keep PAPERLESS_TASK_WORKERS at 1, lower threads to 1, or add a swap file on KVM. On an unprivileged LXC container you usually cannot add swap, so choose a plan with more RAM instead.

Docker fails to start on an LXC plan. Nesting is not enabled for the container. Ask support, or use a KVM VPS.

Emails are not imported. Use the Test button on the mail account, check the folder name (some servers use INBOX.Processed style names), and remember the 30-day maximum age filter. Password protected PDF attachments cannot be OCR-ed and will fail.

Certificate errors in Caddy. The A record does not point to the VPS yet, or port 80 is blocked. Check sudo ufw status and sudo journalctl -u caddy.

Security notes

• Never publish 8000 without 127.0.0.1. Docker bypasses UFW, so the loopback binding is what actually keeps Paperless private.
• Strong admin password and two-factor authentication. Recent 2.x releases support TOTP two-factor login in your profile settings; turn it on for every account.
• Separate accounts. Give family members or employees normal users with the permissions they need instead of sharing the superuser. Paperless supports per-document owners and permissions.
• Protect the secrets. .env holds the database password and secret key, keep it at chmod 600 and out of any Git repository.
• Files are not encrypted at rest. Anyone with root on the server can read the documents. Keep SSH key-only, keep the system updated, and encrypt your offsite backups.
• No public FTP or SMB for scanners. If a scanner must upload files, send them through scan-to-email or an SSH-based transfer, never an open file share on the internet.
• Data locality. Invoices and contracts contain personal data. Hosting them on a VPS in our Romanian data center keeps them in the EU, under your control, which simplifies GDPR conversations.

So, is Paperless-ngx worth it?

If you have more than a shoebox of documents, absolutely. After one afternoon of setup you get an archive that reads Romanian and English, pulls invoices out of your mailbox, files them by supplier and type, and finds any page in a second. The ongoing cost is a small VPS and five minutes a week to review the Inbox tag.

You can run the paperless-ngx docker compose stack from this guide on a VPS with us in a few minutes, with your documents stored in Romania. If you would rather not deal with Docker, backups and updates yourself, our server administration team can install, secure and maintain Paperless-ngx for you.

FAQ

Can I use Paperless-ngx from my phone?

Yes. The web interface is responsive and works in any mobile browser, and you can upload photos of documents directly from the phone. There are also community mobile apps that talk to the Paperless API.

Does Paperless-ngx modify my original files?

No. The original is stored untouched; OCR results go into a separate archive PDF and into the search index. You can always download either version.

How much disk space will I need?

Roughly 100-300 KB per scanned page for the original, plus a similar amount for the archive copy. A household with a few thousand documents typically stays under 20 GB; a small business with years of invoices should plan 40 GB or more and monitor growth.

Can I move away from Paperless-ngx later?

Yes. The document exporter writes plain PDFs and a JSON manifest with all metadata, and with a storage path template the files on disk are already organized in readable folders. Nothing is locked into a proprietary format.