How to self-host Paperless-ngx

Scan your paper post and letters, then find any of it again by searching the words inside. Cresdock runs it on a server you own, from a catalogue, with no Docker and no reverse proxy to configure.

What Cresdock does for you with Paperless-ngx

• Its configuration is written before the container ever starts — including the web address it lives at, so Paperless-ngx generates correct links from the first page load instead of half-working behind a prefix.

• Reached through your panel login. There is no second password to invent for Paperless-ngx and no port to open on your firewall.

• Paperless-ngx needs a PostgreSQL database. Cresdock runs one privately for your account, on your own network, with the connection details handed to Paperless-ngx automatically — you never see a connection string.

• It also needs a background worker service. That is started and managed alongside it, privately, and removed with it.

• Paperless-ngx takes in whatever is left in the folder it watches, whoever put it there — a syncing app, a file manager, or a scan you upload yourself. There's no app to pair it with.

Why run Paperless-ngx yourself

Small tools are where a subscription is hardest to justify: a few pounds a month, times a dozen tools, for software that would run happily on a server you already pay for.

What kind of server Paperless-ngx needs

More than most. Paperless-ngx brings a database and a background worker with it, so budget roughly 1 GB of memory for the three together, and more if you expect it to be busy. Cresdock starts and manages both for you, but they run on your machine and count against your account like anything else.

Cresdock itself is undemanding — it runs on a small rented server, an old desktop or a mini PC, on Ubuntu or Debian. Everything it installs shares that machine, so the honest question is not "will this app run" but "how much am I going to put on here in total".

Where to run Paperless-ngx

Paperless-ngx runs wherever Cresdock runs, and the choice is about the machine, not the app:

• At home, on hardware you already own. A mini PC, an old desktop or a NAS that can run Debian. Cresdock works behind a home router with no port forwarding and no domain, so Paperless-ngx is reachable on your own network first and from outside only if you choose.
• On a rented server. A small VPS is enough for most apps and is the usual answer when Paperless-ngx should be reachable from anywhere. The setup guide covers the specs and the one-command install.
• Through a provider that runs Cresdock. Hosting companies deploy Cresdock workspaces for their customers, so Paperless-ngx can come with a server you rent rather than one you set up — ask your provider, or see how providers offer it.

Installing Paperless-ngx

1. Put Cresdock on a server

   One line on any Ubuntu or Debian machine — a rented VPS, a spare PC, a home server. It sets itself up.

2. Pick Paperless-ngx from the catalogue

   Click Install. The panel pulls the image, writes the configuration, gets a certificate and starts it.

3. Open it from your dashboard

   Its address and any login details are on its card. Start, stop, update, roll back or remove it from the same place, any time.

What's left for you to do

Cresdock does not pretend to do the parts that are genuinely yours to decide. After it's running:

• Sign in with the username and password on this card

• Put a PDF or a photo of a letter in this app's Consume folder. It is read and filed within a minute

• Reading the text out of a scan is slow the first time; give a big batch a few minutes

What this replaces

Doing it by hand means writing something like this, then keeping it working:

services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.18
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - DB_HOST=db
      - DB_PASSWORD=<choose one>
      - REDIS_URL=redis://cache:6379
    volumes:
      - ./paperless/config:/config
    depends_on:
      - db
      - cache

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=<the same one>
      - POSTGRES_DB=paperless
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7-alpine
    restart: unless-stopped

And that is the easy half. Still to do:

• Install a reverse proxy and write a server block for it

• Get a TLS certificate and set up automatic renewal

• Create the folders above with the right ownership, or it will not start

• Create the database and role, and keep that password in step with the app's

• Repeat all of it for the next app, and again on every server rebuild

On Cresdock, Paperless-ngx is one click and none of the above exists.

Looking for what Paperless-ngx itself can do? That lives in its own documentation — this page is only about running it.

Pairs well with: Shell  ·  Solidtime  ·  Plex

Before you start: where to rent a server  ·  what it needs to run  ·  Cresdock vs Cloudron