Die Konfigurationsdatei (.env) von Paperless-ngx im Detail

Die zentrale Konfigurationsdatei von Paperless-ngx

Ein Großteil der Systemkonfiguration von Paperless-ngx wird über eine sogenannte .env-Datei gesteuert. Diese Datei enthält zentrale Parameter für den Betrieb der Containerumgebung und legt fest, wie einzelne Komponenten des Systems zusammenarbeiten.

Die Konfigurationsdatei befindet sich typischerweise im Projektverzeichnis der Docker-Installation, beispielsweise:

/opt/paperless/.env

Beim Start der Container liest Docker Compose diese Datei automatisch ein und stellt die enthaltenen Variablen den einzelnen Diensten zur Verfügung.

Aufbau der Konfigurationsdatei

Die Datei besteht aus einfachen Schlüssel-Wert-Paaren. Jede Zeile definiert eine Konfigurationsvariable, die das Verhalten von Paperless-ngx oder der Containerumgebung beeinflusst.

PAPERLESS_URL=http://192.168.30.80:8000
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_TASK_WORKERS=1

Kommentare werden mit dem Zeichen # eingeleitet und dienen der Dokumentation der Konfiguration.

Gerade bei langfristig betriebenen Systemen empfiehlt es sich, die Datei übersichtlich zu strukturieren und in thematische Abschnitte zu gliedern.

Typische Konfigurationsbereiche

In der hier dokumentierten Installation wird die Datei in mehrere klar abgegrenzte Abschnitte unterteilt. Dadurch bleibt die Konfiguration auch bei späteren Anpassungen gut nachvollziehbar.

Systembasis

Dieser Abschnitt enthält grundlegende Einstellungen wie Zeitzone oder Benutzerzuordnung innerhalb der Containerumgebung.

TZ=Europe/Berlin
USERMAP_UID=1000
USERMAP_GID=1000
HTTP_PORT=8000

Diese Parameter stellen sicher, dass Containerprozesse mit den richtigen Systemrechten arbeiten und Zeitstempel korrekt gesetzt werden.

Server- und Netzwerkparameter

Hier wird festgelegt, unter welcher Adresse die Weboberfläche erreichbar ist und welche Hosts vom System akzeptiert werden.

PAPERLESS_URL=http://192.168.30.80:8000
PAPERLESS_ALLOWED_HOSTS=192.168.30.80,localhost,127.0.0.1
PAPERLESS_CSRF_TRUSTED_ORIGINS=http://192.168.30.80:8000

Diese Einstellungen sind insbesondere relevant, wenn Paperless-ngx innerhalb eines lokalen Netzwerks betrieben wird.

OCR- und Dokumentverarbeitung

Paperless-ngx nutzt eine OCR-Engine zur Texterkennung gescannter Dokumente. Die entsprechenden Parameter werden ebenfalls über die .env-Datei gesteuert.

PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_OCR_MODE=skip
PAPERLESS_CONVERT_TO_PDFA=true

Damit wird beispielsweise festgelegt, welche Sprachen für die Texterkennung verwendet werden und ob bereits durchsuchbare Dokumente erneut verarbeitet werden sollen.

Datenbankkonfiguration

Für kleinere Installationen wird häufig eine SQLite-Datenbank eingesetzt. Diese speichert sämtliche Metadaten des Archivs.

PAPERLESS_DBENGINE=sqlite
PAPERLESS_DBNAME=/usr/src/paperless/data/paperless.db

Die Datenbank enthält Informationen wie Dokumenttitel, Tags, Korrespondenten und andere organisatorische Merkmale.

Import- und Consumer-Einstellungen

Der sogenannte Consumer überwacht das Importverzeichnis und verarbeitet neu abgelegte Dokumente automatisch.

PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true
PAPERLESS_CONSUMER_POLLING=10

Diese Parameter steuern unter anderem, wie häufig das Importverzeichnis überprüft wird und ob Unterordner automatisch als Tags interpretiert werden.

Dubletten-Erkennung

Paperless-ngx kann identische Dokumente anhand ihres Inhalts erkennen. Dadurch lassen sich doppelte Importe vermeiden.

PAPERLESS_CONSUMER_ENABLE_DUPLICATE_CHECK=true
PAPERLESS_CONSUMER_DELETE_DUPLICATES=false

Gefundene Dubletten können separat gespeichert werden, sodass der Benutzer sie später überprüfen kann.

Dateinamenstruktur

Eine besonders wichtige Einstellung betrifft die Struktur der archivierten Dateien. Paperless-ngx erlaubt es, sprechende Dateinamen automatisch zu erzeugen.

PAPERLESS_FILENAME_FORMAT={{ created|date:'Y/MM' }}/{{ correspondent.name }}/{{ created|date:'Y-MM-dd' }} - {{ title }}

Damit entstehen nachvollziehbare Archivpfade, die auch außerhalb des Systems verständlich bleiben.

Vorteile einer strukturierten Konfiguration

Eine sauber dokumentierte .env-Datei bietet mehrere Vorteile:

• klare Übersicht über alle Systemparameter
• einfachere Fehlersuche
• leichtere Migration auf andere Systeme
• bessere Wartbarkeit der Installation

Gerade bei langfristig betriebenen Archivsystemen ist eine nachvollziehbare Konfiguration ein wichtiger Bestandteil der Systemdokumentation.

Nächster Schritt der Reihe

Nachdem Installation, Datenstruktur und Konfiguration erläutert wurden, beschäftigt sich der nächste Beitrag mit dem automatischen Dokumentenimport. Dabei wird erklärt, wie Paperless-ngx neue Dokumente erkennt, verarbeitet und in das Archiv übernimmt.

Aufbau der Artikelreihe

• • Teil 0 – Übersichtsseite der Artikelreihe
  • Teil 1 – Einführung in das Paperless-ngx Dokumentenarchiv
  • Teil 2 – Installation von Paperless-ngx auf Debian mit Docker
  • Teil 3 – Ordnerstruktur und Datenorganisation
  • Teil 4 – Die Konfigurationsdatei (.env)
  • Teil 5 – Automatischer Dokumentenimport
  • Teil 6 – Dateinamen und Archivstruktur
  • Teil 7 – Backup und Datensicherung eines Paperless-ngx Archivs

>