Paperless in Docker einrichten

Letztes Update 2026/02/14 20:41

Vorbereitung

mkdir /home/pi/paperless-ngx
mkdir /home/pi/paperless-ngx/export
touch /home/pi/paperless-ngx/.env && printf "COMPOSE_PROJECT_NAME=paperless\n">/home/pi/paperless-ngx/.env

touch /home/pi/paperless-ngx/docker-compose.env && printf "# Paperless-ngx settings\n">/home/pi/paperless-ngx/docker-compose.env

Portainer öffnen

Portainer öffnen (https://<IP>:9443/), auf den Walfisch klicken und im Menü links Stacks anklicken. Auf + Add stack klicken. Im Feld Name paperless eingeben. Den untenstehendern Code kopieren und im Web editor einfügen.

# Docker Compose file for running paperless from the docker container registry.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# All compose files of paperless configure paperless in the following way:
#
# - Paperless is (re)started on system boot, if it was running before shutdown.
# - Docker volumes for storing data are managed by Docker.
# - Folders for importing and exporting files are created in the same directory
#   as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), PostgreSQL is used as the database server.
# - Apache Tika and Gotenberg servers are started with paperless and paperless
#   is configured to use these services. These provide support for consuming
#   Office documents (Word, Excel, PowerPoint and their LibreOffice counter-
#   parts).
#
# To install and update paperless with this file, do the following:
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
#   and '.env' into a folder.
# - Run 'docker compose pull'.
# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.

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

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8100:8000"
    volumes:
      - data:/usr/src/paperless/data
#      - media:/usr/src/paperless/media
      - /home/pi/paperless-ngx:/usr/src/paperless/media
      - /home/pi/paperless-ngx/export:/usr/src/paperless/export
#      - ./export:/usr/src/paperless/export
      - /home/pi/paperless-ngx/consume:/usr/src/paperless/consume
#    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_CONSUMER_ENABLE_BARCODES: true
      PAPERLESS_TIME_ZONE: Europe/Vienna
#      PAPERLESS_SECRET_KEY: 123456!
#      PAPERLESS_ADMIN_USER: admin
#      PAPERLESS_ADMIN_PASSWORD: 123456!

      USERMAP_UID: 1000
      USERMAP_GID: 1000

      PAPERLESS_OCR_LANGUAGE: deu+eng      
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
  gotenberg:
    image: docker.io/gotenberg/gotenberg:latest
    restart: unless-stopped
    # The gotenberg chromium route is used to convert .eml files. We do not
    # want to allow external content like tracking pixels or even javascript.
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"
  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped
volumes:
  data:
  pgdata:
  redisdata:

Nach unten scrollen und Deploy stack anklicken. Im Menü Containers anklicken. Nach kurzer Zeit erscheinen die neu erstellten Container als heathy.

Aufruf im Browser

http://<IP>:8100

Im Browser die IP-Adresse und den Port von Paperless-ngx inklusive http:// eingeben.

Falls http:// nicht vorgestellt wird, kann es je nach Browser vorkommen, das der Aufruf der Seite mit einer Fehlermeldung abbricht. Nach dem Aufruf wird eine Loginabfrage angezeigt. Hier die Daten eingeben, die bei der Installation verwendet wurden.

Nach dem ersten erfolgreichen Login wird wird eine kleine Demo angezeigt, die auf Wunsch abgebrochen werden kann.

Paperless ist fertig installiert. Nun kann mit der Konfiguration der Einstellungen begonnen werden.

Sicherung der Daten

Um die Daten von Paperless-ngx zu sichern, sollten die folgenden Verzeichnisse gesichert werden:

/var/lib/docker/volumes/paperless_data
/var/lib/docker/volumes/paperless_pgdata
/var/lib/docker/volumes/paperless_redisdata
/home/pi/paperless-ngx/consume
/home/pi/paperless-ngx/documents
/home/pi/paperless-ngx/export

Auf dem Linux-Rechner wird ein Verzeichnis /mnt/sicherung angelegt.

sudo mkdir /mnt/sicherung

Einfaches Script zur Sicherung

Dieses Script kopiert die notwendigen Verzeichnisse unkomprimiert auf das gemountete QNAP-Verzeichnis in ein Datumsverzeichnis, erstellt das aktuelle /export-Verzeichnis und löscht alle Tagessicherungen der letzten 5 Tage. Somit verbleiben im Sicherungsverzeichnis die aktuelle Sicherung und die Sicherungen mit dem Datum der letzten 5 Tage.

Mit dem Begriff Export bringt man das Speichern der Dokumente in Verbindung. Die Funktion, die Paperless-NGX eingebaut hat, ist aber viel umfangreicher: Datenbankinhalte, Metadaten, Einstellungen, Nutzer-Accounts – sogar Passwörter für die einzelnen Account: all dies wird mit einem einzigen Befehl gesichert. Mehr noch: Paperless-NGX überprüft auch Änderungen zum letzten durchgeführten Export und passt die Sicherung entsprechend an. Und noch mehr: Die Sicherung kann auf ein anderes Gerät übertragen werden. Wenn dort ebenfalls Paperless-NGX installiert ist, so hat man – nach einem kurzen Import – auch in dieser anderen Installation ein 1:1-Abbild seines Archivs.

Mit anderen Worten, man muss sich keine Gedanken um irgendwelche (Docker-)Pfade, Datenbanken usw. usw. machen. Man führt den Befehl aus, wartet ein paar Sekunden und hat – je nach Einstellung – alles in einem ZIP-Archiv oder auf einem Export-Pfad liegen.

Das aktuelle Verzeichnis ist /home/pi.

touch ppl_backup.sh
sudo nano ppl_backup.sh

#!/bin/bash
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# Bash für die Datensicherung von Paperless-ngx
# Ver.: 0.1 120324 Verzeichnis nach Datum erstellen
# Ver.: 0.2 010125 export Verzeichnis update      ede
# Ver.: 0.3 180125 Löschen von Daten, die älter als 5 Tage sind      ede
# Ver.: 0.4 240126 Korrekturen für die lokale Sicherung der Daten    ede
#
# ppl_backup.sh
#
 
# Lokales Verzeichnis
mount_dir="/mnt/sicherung"
 
# Momentanes Datum und Uhrzeit
c_datetime=$(date +"%Y-%m-%d_%H-%M-%S")
bkp_ordner="paperless-${c_datetime}"
 
mkdir "${mount_dir}/${bkp_ordner}"
 
# Docker-Container herunterfahren
echo Docker Container werden heruntergefahren
docker stop $(docker ps -q)
 
echo Daten werden kopiert. Bitte warten . . . . .
echo
scp -r /home/pi/paperless-ngx/ "${mount_dir}/${bkp_ordner}"
scp -r /var/lib/docker/volumes/paperless_data "${mount_dir}/${bkp_ordner}"
scp -r /var/lib/docker/volumes/paperless_pgdata "${mount_dir}/${bkp_ordner}"
scp -r /var/lib/docker/volumes/paperless_redisdata "${mount_dir}/${bkp_ordner}"
 
# Docker-Container wieder starten
echo
echo Docker Container werden wieder hochgefahren
docker start $(docker ps -a -q)
 
chmod -R 755 "${mount_dir}/${bkp_ordner}"
 
# export Verzeichnis update
echo
echo export-Verzeichis wird neu erstellt
cd /home/pi/paperless-ngx
sudo docker compose exec -T webserver document_exporter ../export -z
 
echo
echo Alte Sicherung löschen
 
# Löschen aller Dateien die vom heutigen Tag älter als 2 Tage sind
# Es müssen daher 3 Tage Sicherung übrig sein
# -maxdepth 1: Bei der Suche die Unterverzeichnisse nicht einbeziehen, -type -d: Directory
#
# find /mnt/sicherung/@Recycle/ -type d -name 'paperless_*' -mtime +10 -exec rm -r {} \;
find /mnt/sicherung/ -maxdepth 1 -type d -name 'paperless*' -mtime +2 -exec rm -r '{}' \;
 
 
echo
echo Fertig
echo

Datei ausführbar machen und starten:

sudo chmod +x ppl_backup.sh
sudo ./ppl_backup.sh

Nach dem ersten manuellen Aufruf des Sicherungsscriptes sind im Verzeichnis /mnt/sicherung die folgenden verzeichnisse zu finden:

pi@docker100:/mnt/sicherung $ ls -lsa
total 12
4 drwxr-xr-x 3 root root 4096 Jan 24 13:59 .
4 drwxr-xr-x 3 root root 4096 Jan 24 13:59 ..
4 drwxr-xr-x 6 root root 4096 Jan 24 13:59 paperless-2026-01-24_13-59-56
pi@docker100:/mnt/sicherung $
pi@docker100:/mnt/sicherung $ cd paperless-2026-01-24_13-59-56/
pi@docker100:/mnt/sicherung/paperless-2026-01-24_13-59-56 $ ls -lsa
total 24
4 drwxr-xr-x 6 root root 4096 Jan 24 13:59 .
4 drwxr-xr-x 3 root root 4096 Jan 24 13:59 ..
4 drwx-----x 3 root root 4096 Jan 24 13:59 paperless_data
4 drwxr-xr-x 5 root root 4096 Jan 24 13:59 paperless-ngx
4 drwx-----x 3 root root 4096 Jan 24 13:59 paperless_pgdata
4 drwx-----x 3 root root 4096 Jan 24 13:59 paperless_redisdata
pi@docker100:/mnt/sicherung/paperless-2026-01-24_13-59-56 $

Das Verzeicnis enthält das aktuelle Datum der Sicherung.

Cron Job

Um die Sicherung zu automatisieren, wird ein Cron-Job eingerichtet, welcher zu einer festgelegten Zeit, regelmäßig eine Sicherung vornimmt.

sudo nano /etc/crontab

In die crontab wird die Zeile:

# Dateien von Paperless-ngx jeden Tag um 4 Uhr zu sichern.
00 04 * * * root /home/pi/ppl_backup.sh

eingetragen, um die Daten von Paperless-ngx jeden Tag um 4:00^h zu sichern. Hier müssen die gesicherten Daten dann manuell aus dem Verzeichnis /mnt/sicherung weggesichert werden. Im nächsten Punkt wird beschrieben, wie die Daten auf eine NAS gesichert werden können.

Sicherung der Daten auf eine NAS

Auf der NAS wird ein Ordner angelegt. Je nach Modell ist der Vorgang etwas anders, sollte aber für einen Nutzer einer NAS kein Problem darstellen.
Auf dem Raspberry ist bereits ein Verzeichnis /mnt/sicherung eingerichtet. Im Home-Directory von pi wird eine Datei mit dem Namen .smbcredfile angelegt. In dieser werden Username und Passwort hinterlegt:

touch ~/.smbcredfile
sudo nano ~/.smbcredfile

und Username und Passwort eingetragen.

username=pi
password=k0

Nach dem Speichern werden die Rechte vergeben, damit die Datei weitgehend verborgen bleibt.

sudo chmod 600 ~/.smbcredfile

Anschließend wird die fstab geöffnet:

sudo nano /etc/fstab

In dieser wird der Share eingetragen.

//NAS1/pisicherung /mnt/sicherung cifs credentials=/home/pi/.smbcredfile  0 0

Der Eintrag wird ohne Neustart mit der Anweisung sudo mount -a aktiviert. Falls in diesem Share bereits Daten hinterlegt sind, kann das mit ls -lsa /mnt/sicherung/ kontrolliert werden. Um den Share zu deaktivieren, so ist das durch die Eingabe von umount /mnt/sicherung möglich.

Nach einem Reboot wird der Share durch den Eintrag in der fstab aktiviert. Auf der NAS kann ein Job zur Sicherung der Daten auf ein Sicherungslaufwerk eingerichtet werden.

Hinweise für den Import

Es sind einige Punkte zu beachten:

Beide Paperless-Systeme müssen die gleiche Version sein. D.h. dass eventuell vor dem Export die Version angegelichen werden muss oder am Zielsystem die alte Version installiert werden muss.
Der Zielordner, hier /home/pi/paperless-ngx/ muss die Rechte 777 haben.
Dazu in den Ordner cd /home/pi/ wechseln und dort mit chmod -R 777 paperless-ngx/ die entsprechenden Rechte setzen.
Im neu aufgesetzten Paperless-ngx einen im alten System nicht vorhandenen User anlegen. Dies war bei mir nur eine Sicherheitsfunktion, sollte auch ohne neuen User funktionieren. Alle sonstigen User müssen vor dem Restore im neuen System auf alle Fälle gelöscht werden.
Zur Konsole des neuen Systems wechseln und dort in das Verzeichnis /home/pi/paperless-ngx/ gehen.
Hier die unten stehenden Befehle ausführen.

pi@docker0:~/paperless-ngx/export $ cd /home/pi/paperless-ngx
pi@docker0:~/paperless-ngx $ sudo docker-compose exec webserver document_importer ../export
Found existing user(s), this might indicate a non-empty installation
Checking the manifest
Installed 2705 object(s) from 1 fixture(s)
Copy files into paperless...
100%|█████████████████████████████████████████████████████████████████████████████████| 229/229 [00:04<00:00, 52.08it/s]
Updating search index...
100%|█████████████████████████████████████████████████████████████████████████████████| 229/229 [00:11<00:00, 19.66it/s]
pi@docker0:~/paperless-ngx $

Möchte man später die Dokumente in eine Neu-Installation von Paperless-ngx aufnehmen oder zieht man beispielsweise vom Raspberry Pi zu einem Synology-NAS um, so gibt man auf dem Paperless-ngx-Pfad fast den gleichen Befehl ein:

sudo docker-compose exec webserver document_importer ../export

Natürlich müssen zuvor die gesicherten Dateien in den Unterpfad „export“ kopiert werden.

sudo docker-compose exec webserver document_exporter ../export

Quelle: digital-cleaning

Eingabeordner freigeben

Um die Verarbeitung einfacher zu gestalten, wird der consume Ordner freigegeben. Einerseits, wenn ein Netzwerkscanner vorhanden ist, um die Dokumente automatisch nach dem Einscannen in Paperless-ngx zu verarbeiten, andererseits, um Dokumente, die in Windows eingehen, dorthin zu verschieben. Der Ordner wird durch eine Samba-Freigebe zur Verfügung gestellt.

Samba einrichten

Als erstes werden die entsprechenden Pakete installiert:

sudo apt install samba samba-common-bin -y

Prüfen, ob Samba läuft

service smbd status
service nmbd status

Bei beiden Services wird der jeweilige Status angezeigt.

Samba konfigurieren

In der [global] Sektion die folgenden Zeilen eintragen:

sudo nano /etc/samba/smb.conf

workgroup = WORKGROUP
security = user
encrypt passwords = yes

und am Ende der smb.conf

[ppl_input]
comment = consume Ordner von Paperless-ngx
path = /home/pi/paperless-ngx/consume
read only = no
browseable = yes
create mask=0755

Der Ordner /home/pi/paperless-ngx/consume ist der Eingangsordner von Paperless-ngx und wird als ppl_input freigegeben.

Da hier kein Server zur Datensicherung vorliegt, wird die Sicherung auf die interne Festplatte geschrieben. Um die Möglichkeit zu gewährleisten, diese Sicherungsdateien leichter zu kopieren, wird auf dieses Verzeichnis ebenfalls ein Share gelegt:

[ppl_backup]
comment = Backup Ordner von Paperless-ngx
path = /mnt/sicherung
read only = no
browseable = yes
create mask=0755

Diese Konfigurationsdatei wird durch die Eingabe von

testparm

überprüft.

Samba neu starten, entweder mit:

sudo service smbd restart
sudo service nmbd restart

oder

sudo systemctl restart smbd
sudo systemctl restart nmbd

Nun muss noch der User pi in Samba aktiviert werden. Dazu muss er erst ein Samba-Passwort bekommen (k0):

sudo smbpasswd -a pi
New SMB password:
Retype new SMB password:

und dann aktiviert werden:

sudo smbpasswd -e pi

Das Samba-Benutzerkonto ist anschließend sofort aktiv.

Um von Windows auf den Ordner ppl_backup zugreifen zu können, müssen die Rechte für den User pi gesetzt werden:

sudo chown -R pi /mnt/sicherung

Netzlaufwerk verbinden

Im Windows Explorer auf Netzwerk verbinden klicken.

Ich verwende das Laufwerk P: (für Paperless-ngx). Im Feld Ordner wird der Name des Samba-Shares eigegeben:

\\docker100\ppl_input

Außerdem die Kästchen Verbindung bei Anmeldung Wiederherstellen und Verbindung mit anderen Anmeldeinformationen herstellen auswählen.

Nun müssen die Anmeldeinformationen für den User pi, der als Eigentümer des consume Ordners gilt und das bei der Samba-Konfiguration angegebene Passwort eingegeben werden. Den Haken Anmeldedaten speichern setzen, um das Kennwort nicht jedesmal eingeben zu müssen. kloburg0

Nun können Dokumente in den Ordner P: auf dem Windows PC geschoben werden und Paperless-ngx verarbeitet dieses Dokument sofort.

Wenn die Meldung Durch das Öffnen der Dateien entstehen möglicherweise Risken für den Computer erscheint, dann die IP-Adresse des Paperless-Servers ins Lokale Intranet eintragen. Wie das Funktioniert ist hier beschrieben.

Analog dazu muss zum Kopieren der Sicherungsdateien auch ein Netzlaufwerk auf den Ordner ppl_backup gesetzt werden.

Anhang:

API's

Tika

Tika ist ein Dienst, der Word-/LibreOffice-Dokumente in PDF-Dateien konvertieren kann.

Gotenberg

Gotenberg wird im Zuge von Tika mitinstalliert und ist eine API für die Umwandlung von Dokumenten ins PDF-Format.

Redis

Redis ist ein Zwischenspeicher, der deine Daten direkt im Arbeitsspeicher ablegt, um so eine höhere Geschwindigkeit zu gewährleisten.

Quellen:

docker-compose.postgres.yml
Paperless-NGX konfiguieren
Trennseite
https://digital-cleaning.de/index.php/paperless-ngx-teil-24-sofortinstallation/

Inhaltsverzeichnis