Self-hosting Paperless-ngx on a VPS: the consume folder, OCR, and the honest RAM storyPaperless-ngx selbst hosten auf einem VPS: der Consume-Ordner, OCR und die ehrliche RAM-Geschichte

SQLite or Postgres, and which compose file to start fromSQLite oder Postgres, und mit welcher Compose-Datei du anfängst

The project publishes ready-made Docker Compose files for both database backends, plus a matching .env, and the honest first step is downloading whichever variant you want rather than hand-rolling one from scratch. Either way you get the same shape: webserver (the paperless-ngx image, running the UI, the API and the consumer together), broker (Redis, queuing consumption and OCR jobs), and, in the Postgres variant, db.Das Projekt veröffentlicht fertige Docker-Compose-Dateien für beide Datenbank-Backends, dazu eine passende .env, und der ehrliche erste Schritt ist, die Variante herunterzuladen, die du willst, statt selbst eine zusammenzubasteln. So oder so bekommst du die gleiche Form: webserver (das paperless-ngx-Image, das UI, API und den Consumer zusammen betreibt), broker (Redis, das die Consumption- und OCR-Jobs in eine Warteschlange stellt) und, in der Postgres-Variante, db.

SQLite is the default if you leave the database settings alone, and for one person's archive it is genuinely fine — Redis is there regardless of which database you pick, because it is the task queue, not the document store. Move to Postgres once more than one person uploads and searches at the same time, or the archive grows large enough that you want a database you can pg_dump on its own schedule instead of backing up as a single file that has to be quiescent to trust.SQLite ist die Standardeinstellung, wenn du die Datenbankeinstellungen unangetastet lässt, und für das Archiv einer einzelnen Person ist das wirklich in Ordnung — Redis ist unabhängig von der gewählten Datenbank dabei, weil es die Aufgaben-Warteschlange ist, nicht der Dokumentenspeicher. Wechsle zu Postgres, sobald mehr als eine Person gleichzeitig hochlädt und sucht, oder das Archiv so groß wird, dass du eine Datenbank willst, die du mit pg_dump nach eigenem Zeitplan sichern kannst, statt sie als einzelne Datei zu sichern, die dafür still stehen muss, damit man ihr trauen kann.

A trimmed sqlite-backed compose file looks like this:Eine gekürzte, SQLite-gestützte Compose-Datei sieht so aus:

services:
  broker:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.14.7  # paperless-ngx only tags exact releases (plus latest/dev) — check the GitHub releases page for the current one, not a bare major.minor
    restart: unless-stopped
    depends_on:
      - broker
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_URL=https://docs.example.com
      - PAPERLESS_SECRET_KEY=${PAPERLESS_SECRET_KEY}
      - PAPERLESS_TIME_ZONE=Europe/Berlin
      - PAPERLESS_OCR_LANGUAGE=deu+eng
      - PAPERLESS_OCR_LANGUAGES=deu eng
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - /srv/paperless/consume:/usr/src/paperless/consume
      - export:/usr/src/paperless/export

volumes:
  redisdata:
  data:
  media:
  export:

Adding Postgres means a db service plus four more variables on webserver — PAPERLESS_DBHOST=db, PAPERLESS_DBNAME, PAPERLESS_DBUSER, PAPERLESS_DBPASS — and depends_on: [broker, db]. The official Postgres compose file already has this shape; use it rather than guessing at the service name.Postgres hinzuzufügen bedeutet einen db-Service plus vier weitere Variablen bei webserver — PAPERLESS_DBHOST=db, PAPERLESS_DBNAME, PAPERLESS_DBUSER, PAPERLESS_DBPASS — sowie depends_on: [broker, db]. Die offizielle Postgres-Compose-Datei hat diese Form bereits; nutze sie, statt den Servicenamen zu erraten.

How documents get inWie Dokumente hineinkommen

Three doors, and you will probably end up using at least two of them.Drei Türen, und du wirst wahrscheinlich mindestens zwei davon nutzen.

• The consume folder. Any file dropped into it is picked up, OCR'd, and imported automatically, then removed. Bind-mount it to a real host path (as above), not a named volume, so anything on the box can drop files in directly. PAPERLESS_CONSUMER_RECURSIVE=true watches subdirectories too, and PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true turns those subdirectory names into tags automatically.Der Consume-Ordner. Jede Datei, die dort hineingelegt wird, wird aufgenommen, per OCR verarbeitet, automatisch importiert und danach entfernt. Bind-mounte ihn auf einen echten Host-Pfad (wie oben), nicht auf ein benanntes Volume, damit alles auf der Maschine Dateien direkt hineinlegen kann. PAPERLESS_CONSUMER_RECURSIVE=true überwacht auch Unterverzeichnisse, und PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true macht aus diesen Unterverzeichnisnamen automatisch Tags.
• Upload through the web UI. Drag a PDF or a photo of a receipt onto the dashboard — same consumption pipeline, no folder involved.Hochladen über die Weboberfläche. Ein PDF oder das Foto einer Quittung auf das Dashboard ziehen — dieselbe Consumption-Pipeline, kein Ordner beteiligt.
• Mail fetching. Under Settings → Mail you add a mail account (IMAP host, port, credentials, SSL or STARTTLS) and one or more rules: which folder to watch, a filter on sender or subject, and what to do with a match — consume the attachments, the whole message as a PDF, or both. A scheduled task checks the account on an interval, so mail-sourced documents lag a few minutes behind a folder drop; that is normal, not a stuck consumer.Mail-Abruf. Unter Einstellungen → Mail fügst du ein Mail-Konto hinzu (IMAP-Host, Port, Zugangsdaten, SSL oder STARTTLS) sowie eine oder mehrere Regeln: welcher Ordner beobachtet wird, ein Filter auf Absender oder Betreff, und was bei einem Treffer passiert — die Anhänge konsumieren, die ganze Nachricht als PDF, oder beides. Eine geplante Aufgabe prüft das Konto in einem bestimmten Intervall, sodass Dokumente aus der Mail einige Minuten hinter einem Ordner-Drop zurückliegen; das ist normal und kein hängender Consumer.

For a scanner that only knows how to push files to a network folder over SFTP, skip a second container and point it at the host's own SSH server instead, chrooted to the paperless project directory rather than the consume folder itself:Für einen Scanner, der nur weiß, wie man Dateien über SFTP auf einen Netzwerkordner schiebt, verzichtest du auf einen zweiten Container und richtest ihn stattdessen auf den SSH-Server des Hosts selbst aus, gechrootet auf das paperless-Projektverzeichnis statt auf den Consume-Ordner selbst:

Match User scanner
    ChrootDirectory /srv/paperless
    ForceCommand internal-sftp
    AllowTcpForwarding no

ChrootDirectory has a hard requirement: the directory it names, and every parent above it, must be owned by root and writable by no one else, or sshd refuses the login with "Bad owner or modes for ChrootDirectory". That rules out chrooting straight to consume — a folder the scanner needs to write into can never satisfy "not writable by anyone but root". Chroot to /srv/paperless instead (root-owned, mode 755), and make consume a subdirectory inside it that the scanner can write to — owned by the scanner user or a shared group, mode 775 — bind-mounted into the container at the same absolute path used above (/srv/paperless/consume). Give that user a key-only login and no shell, and it drops files into consume/ inside its chroot, which is the exact host path the webserver container already watches. Nothing paperless-specific about it — it is the same chrooted-SFTP pattern you would use for any drop folder, and the chroot root itself must stay root-owned and untouched.ChrootDirectory hat eine harte Anforderung: Das benannte Verzeichnis und jedes übergeordnete Verzeichnis darüber müssen root gehören und für sonst niemanden beschreibbar sein, sonst verweigert sshd den Login mit „Bad owner or modes for ChrootDirectory“. Das schließt aus, direkt auf consume zu chrooten — ein Ordner, in den der Scanner schreiben muss, kann niemals „für niemanden außer root beschreibbar“ erfüllen. Chroote stattdessen auf /srv/paperless (root-Besitz, Modus 755), und mach consume zu einem Unterverzeichnis darin, in das der Scanner tatsächlich schreiben kann — im Besitz des Scanner-Nutzers oder einer gemeinsamen Gruppe, Modus 775 — hineingebunden in den Container unter demselben absoluten Pfad, der oben verwendet wird (/srv/paperless/consume). Gib diesem Nutzer einen reinen Key-Login ohne Shell, und er legt Dateien in consume/ innerhalb seines Chroots ab, was genau der Host-Pfad ist, den der webserver-Container bereits überwacht. Nichts davon ist paperless-spezifisch — es ist dasselbe gechrootete SFTP-Muster, das du für jeden Drop-Ordner verwenden würdest, und die Chroot-Wurzel selbst muss root-eigen und unangetastet bleiben.

PAPERLESS_URL, PAPERLESS_SECRET_KEY, and the first superuserPAPERLESS_URL, PAPERLESS_SECRET_KEY und der erste Superuser

PAPERLESS_SECRET_KEY is not cosmetic. Leave it unset and the image falls back to a built-in default, which is fine for a five-minute test and not something you want protecting a document archive with your tax returns in it. Generate one and put it in .env, not inline in the compose file:PAPERLESS_SECRET_KEY ist nicht kosmetisch. Lässt du ihn ungesetzt, fällt das Image auf einen eingebauten Standardwert zurück, was für einen Fünf-Minuten-Test in Ordnung ist und nicht das, womit du ein Dokumentenarchiv mit deinen Steuererklärungen darin schützen willst. Erzeuge einen und trag ihn in .env ein, nicht inline in die Compose-Datei:

printf 'PAPERLESS_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
chmod 600 .env

PAPERLESS_URL matters as soon as Caddy sits in front of the app: it tells Django which origin to trust for CSRF, and without it a correctly proxied instance can still reject your own login form. Set it to the full https:// hostname you will actually use.PAPERLESS_URL wird relevant, sobald Caddy vor der App sitzt: Es sagt Django, welchem Origin es für CSRF vertrauen soll, und ohne sie kann eine korrekt geproxte Instanz trotzdem dein eigenes Login-Formular ablehnen. Setze sie auf den vollen https://-Hostnamen, den du tatsächlich benutzen wirst.

Bring the stack up, then create the first account with the documented command rather than a raw manage.py invocation:Fahr den Stack hoch, und leg dann den ersten Account mit dem dokumentierten Befehl an statt mit einem rohen manage.py-Aufruf:

docker compose up -d
docker compose run --rm webserver createsuperuser

It prompts for a username, e-mail and password interactively — nothing to leak into shell history.Es fragt interaktiv nach Benutzername, E-Mail und Passwort — nichts davon landet in der Shell-History.

OCR languages, and the honest CPU storyOCR-Sprachen, und die ehrliche CPU-Geschichte

PAPERLESS_OCR_LANGUAGE sets which Tesseract language pack OCR actually uses, combining more than one with a +, as in deu+eng above for a mixed German/English archive. PAPERLESS_OCR_LANGUAGES is the separate setting that tells the image which additional language packs to install at startup, space-separated — set both, or the language you asked for simply is not there to use.PAPERLESS_OCR_LANGUAGE legt fest, welches Tesseract-Sprachpaket die OCR tatsächlich benutzt, mehrere kombiniert mit einem +, wie oben deu+eng für ein gemischt deutsch-englisches Archiv. PAPERLESS_OCR_LANGUAGES ist die separate Einstellung, die dem Image sagt, welche zusätzlichen Sprachpakete beim Start installiert werden sollen, getrennt durch Leerzeichen — setz beide, sonst ist die Sprache, die du wolltest, schlicht nicht vorhanden.

Changing the setting later only affects documents consumed from that point on; it does not retroactively re-OCR anything already archived. For that, select the affected documents in the UI and use the Redo OCR bulk action.Die Einstellung später zu ändern wirkt sich nur auf Dokumente aus, die ab diesem Zeitpunkt konsumiert werden; sie verarbeitet nichts bereits Archiviertes rückwirkend neu per OCR. Dafür wählst du die betroffenen Dokumente in der Oberfläche aus und nutzt die Sammelaktion Redo OCR.

OCR is CPU-bound, full stop. Tesseract does real image-processing work per page, and on 2 vCPU that is slower than on a workstation — a multi-page scan can take a couple of minutes rather than a few seconds. For a personal archive that is a non-event: scan a receipt, walk away, it is searchable by the time you next open the dashboard. It only becomes a real problem if you dump years of backlog in at once expecting a quick turnaround; run a large backlog overnight instead.OCR ist CPU-gebunden, Punkt. Tesseract leistet pro Seite echte Bildverarbeitung, und auf 2 vCPU geht das langsamer als auf einer Workstation — ein mehrseitiger Scan kann ein paar Minuten dauern statt ein paar Sekunden. Für ein privates Archiv ist das kein Ereignis: Quittung scannen, weggehen, sie ist durchsuchbar, spätestens wenn du das Dashboard das nächste Mal öffnest. Es wird erst zu einem echten Problem, wenn du jahrelangen Rückstand auf einmal reinkippst und schnelle Ergebnisse erwartest; lass einen großen Rückstau stattdessen über Nacht laufen.

Sizing: RAM is fine, OCR bursts are the thing that spikesDimensionierung: RAM ist unproblematisch, OCR-Schübe sind das, was ausschlägt

2 GiB is comfortable for a personal archive: Redis, the webserver, SQLite (or a light Postgres), and the consumer sitting mostly idle between documents. The spike is not the steady state, it is an OCR job on a large, image-heavy scan — a fifty-page scan from a flatbed at high DPI asks for real memory while Tesseract and the PDF post-processing both hold pages in memory at once. One such job at a time on 2 GiB is fine; several running concurrently because a backlog got dropped in all at once is where you actually feel it.2 GiB sind komfortabel für ein privates Archiv: Redis, der Webserver, SQLite (oder ein leichtes Postgres) und der Consumer, der zwischen den Dokumenten meist untätig herumsteht. Der Ausschlag ist nicht der Dauerzustand, sondern ein OCR-Job auf einem großen, bildlastigen Scan — ein fünfzigseitiger Scan von einem Flachbett bei hoher DPI verlangt echten Speicher, während Tesseract und die PDF-Nachbearbeitung gleichzeitig Seiten im Speicher halten. Ein solcher Job auf einmal bei 2 GiB ist unproblematisch; mehrere gleichzeitig, weil ein Rückstau auf einmal reingeworfen wurde, ist der Punkt, an dem du es tatsächlich spürst.

Disk is the quieter constraint: media holds the archived PDFs and thumbnails and only grows, data holds the SQLite file (if used) plus the search index and classifier model. Move to Standard once several people are scanning into the same instance every working day — more concurrent OCR jobs and a heavier index both want the extra vCPU and RAM more than one person's archive ever will.Speicherplatz ist der leisere Engpass: media hält die archivierten PDFs und Thumbnails und wächst nur, data hält die SQLite-Datei (falls verwendet) plus den Suchindex und das Klassifikator-Modell. Wechsle zu Standard, sobald mehrere Leute jeden Arbeitstag in dieselbe Instanz scannen — mehr gleichzeitige OCR-Jobs und ein schwererer Index wollen beide eher die zusätzliche vCPU und das zusätzliche RAM, als das Archiv einer einzelnen Person es je tun wird.

HTTPS with Caddy, and read this before you buyHTTPS mit Caddy, und das hier lies, bevor du kaufst

docs.example.com {
    reverse_proxy 127.0.0.1:8000
}

That is the whole file, and it is enough because paperless-ngx's webserver speaks plain HTTP internally — Caddy is the only thing that needs to see the port from outside, which is why it is bound to 127.0.0.1 above.Das ist die ganze Datei, und sie reicht, weil der Webserver von paperless-ngx intern nur einfaches HTTP spricht — Caddy ist das Einzige, das den Port von außen sehen muss, weshalb er oben an 127.0.0.1 gebunden ist.

The catch has nothing to do with paperless-ngx and everything to do with the network the VPS sits on. Under NAT IPv4, your box has a shared address and a small number of forwarded ports, and whether 80 and 443 are among them depends on the plan — never assume they are. Caddy's automatic HTTPS needs one of those two reachable to complete the certificate challenge; without it, the config above never gets a certificate no matter how correct the Caddyfile is. Check what your plan forwards before pointing DNS at the box — point your domain at your service, then NAT IPv4 vs a dedicated IP and NAT IPv4, ports and forwarding if you are not sure what your plan hands you. A dedicated IPv4, where 80 and 443 are simply yours, is arranged by e-mail, not as a self-service toggle.Der Haken hat nichts mit paperless-ngx zu tun und alles mit dem Netzwerk, in dem der VPS steckt. Unter NAT-IPv4 hat deine Maschine eine geteilte Adresse und eine kleine Zahl weitergeleiteter Ports, und ob 80 und 443 darunter sind, hängt vom Tarif ab — geh nie davon aus. Caddys automatisches HTTPS braucht einen dieser beiden erreichbar, um die Zertifikats-Challenge abzuschließen; ohne das bekommt die Konfiguration oben nie ein Zertifikat, egal wie korrekt die Caddyfile ist. Prüf, was dein Tarif weiterleitet, bevor du DNS auf die Maschine zeigen lässt — deine Domain auf deinen Dienst zeigen lassen, dann NAT-IPv4 vs. dedizierte IP und NAT-IPv4, Ports und Weiterleitung, falls du nicht sicher bist, was dein Tarif hergibt. Eine dedizierte IPv4, bei der 80 und 443 einfach dir gehören, wird per E-Mail vereinbart, nicht als Self-Service-Schalter.

Backups: the exporter, plus the volumes underneath itBackups: der Exporter, plus die Volumes darunter

Paperless-ngx ships its own export command, and it is the one to actually use, because it writes out the originals, the generated thumbnails and a JSON manifest of every document's metadata and tags together — not just a raw copy of whatever happens to be on disk:Paperless-ngx bringt einen eigenen Export-Befehl mit, und den solltest du tatsächlich nutzen, weil er die Originale, die generierten Thumbnails und ein JSON-Manifest der Metadaten und Tags jedes Dokuments zusammen schreibt — nicht nur eine rohe Kopie von dem, was zufällig auf der Platte liegt:

docker compose exec webserver document_exporter ../export

That path resolves to the export volume mounted above; copy its contents off the machine entirely afterwards — a copy that never leaves the same disk is not a backup. The exporter is also the intended path back in: document_importer reads the same manifest into a fresh instance.Dieser Pfad löst sich zum oben eingebundenen export-Volume auf; kopiere seinen Inhalt danach vollständig von der Maschine herunter — eine Kopie, die dieselbe Platte nie verlässt, ist kein Backup. Der Exporter ist auch der vorgesehene Weg zurück hinein: document_importer liest dasselbe Manifest in eine frische Instanz ein.

Belt-and-braces beyond the exporter output: keep the raw media and data volumes backed up too. The exporter can rebuild your archive from scratch, but a straight copy of those volumes restores faster and does not depend on the last export having finished cleanly. back up your VPS covers what off-box backup looks like on our machines.Gürtel und Hosenträger über die Exporter-Ausgabe hinaus: Sichere auch die rohen media- und data-Volumes. Der Exporter kann dein Archiv von Grund auf wiederherstellen, aber eine direkte Kopie dieser Volumes stellt schneller wieder her und hängt nicht davon ab, dass der letzte Export sauber durchgelaufen ist. Backup deines VPS beschreibt, wie Backup abseits der Maschine auf unseren Maschinen aussieht.

UpdatesUpdates

docker compose pull
docker compose up -d

Bump the pinned tag in the compose file deliberately rather than tracking latest, and run an exporter backup immediately before you do — the container runs the necessary database migrations automatically on the first start after an upgrade, and once that has happened there is no supported way back to the older version's schema. A backup from ten minutes before the migration is what makes that an inconvenience instead of a lost archive.Erhöhe den fixierten Tag in der Compose-Datei bewusst, statt latest zu verfolgen, und mach unmittelbar davor ein Exporter-Backup — der Container führt die nötigen Datenbank-Migrationen automatisch beim ersten Start nach einem Upgrade aus, und danach gibt es keinen unterstützten Weg zurück zum Schema der älteren Version. Ein Backup von zehn Minuten vor der Migration macht daraus eine Unannehmlichkeit statt eines verlorenen Archivs.

On overnight.hostBei overnight.host

Full disclosure: this is what we sell. A 2 GiB Basic is comfortable for a personal document archive; move to Standard once several people are scanning into it daily and OCR queues start stacking up.Zur vollen Transparenz: Das ist, was wir verkaufen. Ein 2-GiB-Basic ist komfortabel für ein privates Dokumentenarchiv; wechsle zu Standard, sobald mehrere Leute täglich hineinscannen und sich OCR-Warteschlangen zu stapeln beginnen.

Linux KVM VPS — EUR 4.99 to EUR 59.99 a month, on our own single-tenant bare metal in Dallas, TX and Charlotte, NC. Full hardware virtualisation (KVM), your own kernel, full root. Six tiers, vps-starter to vps-ultra. Starter is 1 vCPU, 1 GiB RAM, 25 GB disk.Linux-KVM-VPS — 4,99 bis 59,99 EUR im Monat, auf unserer eigenen Single-Tenant-Bare-Metal-Hardware in Dallas, TX und Charlotte, NC. Vollständige Hardware-Virtualisierung (KVM), eigener Kernel, volles Root. Sechs Tarife, vps-starter bis vps-ultra. Starter hat 1 vCPU, 1 GiB RAM, 25 GB Speicher.

You order in the shop, pay by card (Stripe) or SEPA bank transfer, and your login details are e-mailed to you once the service is set up. Support is e-mail, run by one person, with no guaranteed response time. All prices are final totals under the German small-business rule (§19 UStG); no VAT is added or shown.Du bestellst im Shop, zahlst per Karte (Stripe) oder SEPA-Überweisung, und deine Zugangsdaten werden dir per E-Mail zugeschickt, sobald der Dienst eingerichtet ist. Support läuft per E-Mail, von einer einzelnen Person betrieben, ohne garantierte Reaktionszeit. Alle Preise sind Endpreise. Gemäß § 19 UStG wird keine Umsatzsteuer ausgewiesen.

Order vps-basic → · Linux KVM VPS overviewvps-basic bestellen → · Übersicht Linux-KVM-VPS

Written by the person who runs overnight.host: a small, honest hosting company on dedicated bare metal — Linux VPS, game servers, web hosting. Live status at up.overnight.host.Geschrieben von der Person, die overnight.host betreibt: ein kleines, ehrliches Hosting-Unternehmen auf dedizierter Bare-Metal-Hardware — Linux-VPS, Gameserver, Webhosting. Live-Status unter up.overnight.host.