Paperless-ngx auf einem VPS installieren

Einführung

In diesem Blogpost geht es darum, Paperless-ngx auf einem VPS zu installieren, um ein papierloses Büro einzurichten. Ein VPS ermöglicht den Zugriff auf Dokumente von überall, bietet Sicherheit durch professionelle Rechenzentren und lässt sich flexibel skalieren. Ich habe dazu ein Video erstellt, das ihr euch auf Youtube anschauen könnt:

Paperless-ngx auf einem VPS installieren (Link zu Youtube)

Im Folgenden findet ihr die Schritte kurz dargestellt, die im Video gezeigt werden.

Falls ihr Paperless-ngx lieber auf einem Synology NAS installieren möchtet, findet ihr hier eine Anleitung: Paperless-ngx auf einem Synology NAS installieren.

Key Takeaways

Paperless-ngx

Paperless-ngx ist ein Open-Source-Dokumentenverwaltungssystem, das den Benutzern das Scannen, Organisieren und Auffinden ihrer Dokumente erleichtert. Es ermöglicht die Archivierung von Rechnungen, Verträgen, Belegen und anderen Dokumenten. Paperless-ngx ist der Nachfolger des Projekts Paperless und wurde mit Blick auf den modernen Benutzer entwickelt. Es bietet eine Reihe von Funktionen, die das papierlose Arbeiten erleichtern.

Entwicklungsverlauf

Ein kleiner Überblick über die Entwicklung von Paperless und Paperless-ngx (viele Releases wurden ausgelassen, um die Übersicht zu wahren):

Features des Paperless-ngx DMS

Mit Paperless-ngx können:

• Dokumente zur einfachen Identifizierung gekennzeichent werden, z.B. Rechnungen, Verträge und Belege einfach archivieren und wiederfinden.
• Inhalte mühelos durchsucht werden.

Paperless-ngx ist mit OCR-Technologie (Optical Character Recognition) ausgestattet, die es ermöglicht, gescannte Dokumente in durchsuchbare PDFs umzuwandeln. Die Software unterstützt auch die automatische Klassifizierung von Dokumenten und die automatische Erkennung von Metadaten.

Wenn es auf einem Server läuft, kann Paperless-ngx von jedem Gerät aus aufgerufen werden, solange ein Browser vorhanden ist.

Gründe für die Installation auf einem VPS

Die Installation auf einem VPS ist aus mehreren Gründen besonders praktisch.

Zentraler Zugriff

Ein VPS erlaubt es euch, von beliebigen Orten mit Internetverbindung auf eure Dokumente zuzugreifen. So seid ihr nicht auf das lokale Netzwerk beschränkt. Das ermöglicht den Zugriff von überall.

Datensicherheit

VPS-Anbieter bieten in der Regel hochsichere Rechenzentren, was euch vor Datenverlust durch physische Schäden wie Feuer oder Diebstahl schützt.

Skalierbarkeit

Mit einem VPS könnt ihr die Serverressourcen anpassen, je nachdem wie eure Anforderungen wachsen – das bedeutet mehr Speicherplatz oder Rechenleistung bei Bedarf.

Professionelles Hosting-Umfeld

Ein VPS bietet ein professionelles Hosting-Umfeld mit dedizierten IP-Adressen und einer schnellen Internetverbindung.

Diese Aspekte machen die Verwendung eines VPS für Paperless zu einer attraktiven Option für Unternehmen und Privatpersonen, die nach einer effizienten und sicheren Lösung für ihr Dokumentenmanagement suchen.

Weitere Tools

Wir beschränken uns allerdings nicht nur auf Paperless, sondern integrieren zusätzliche Software, um den Prozess zu optimieren. Ein zentrales Tool hierbei ist Docker, welches die Installation und Konfiguration von Paperless erheblich erleichtert. Zudem verwende ich Caddy als Reverse-Proxy, um die Anwendung einfacher und sicherer verfügbar zu machen. Mit Wireguard sorgen wir für eine geschützte Verbindung zu unserem VPS.

Nachdem ihr dieser Anleitung gefolgt seid, solltet ihr in der Lage sein, ein papierloses Büro einzurichten.

Voraussetzungen

• Computer mit:

  • Wireguard: Für die sichere Serververbindung.
  • Visual Studio Code: Für die Arbeit auf dem Server.

• Docker-kompatibler Server: Darauf wird Paperless-ngx installiert.

• Domain mit der Option, Subdomains zu erstellen: Für den Zugriff auf Paperless-ngx.

• Mail-Server mit SMTP-Unterstützung: Optional, um Dateien direkt via E-Mail zu archivieren.

Begleitet mich nun durch die einzelnen Schritte, um euer digitales Dokumentenmanagement zu realisieren.

Schritt 1: Server mieten

Als erstes benötigen wir einen Server. Ich empfehle euch, einen VPS bei einem Anbieter eurer Wahl zu mieten. Ich persönlich nutze Netcup. Hier wird eine einfache und schnelle Möglichkeit geboten, einen VPS zu mieten.

Ihr könnt auch hier nach Gutscheinen schauen.

Die Kosten fangen momentan bei 3,25€ pro Monat an. Root-Server (ab 9,81€ pro Monat) bieten durch die dedizierten CPU-Kerne eine deutlich bessere Performance, jedoch braucht ihr das nicht, wenn ihr den Server nur für Paperless-ngx nutzt.

Wenn ihr einen VPS gemietet habt, findet ihr die IP-Adresse im CCP. Ansonsten sollte diese auch in der E-Mail stehen.

Schritt 2: Domain mieten

Als nächstes benötigen wir eine Domain. Auch hier solltet ihr einen Anbieter eurer Wahl nutzen. Domain und Server müssen sich nicht beim selben Anbieter befinden. Dennoch nutze ich auch dafür Netcup. An dieser Stelle habt ihr zwei Möglichkeiten:

1. Zusätzliche Domain mieten
2. Webhosting-Paket mit Inklusiv-Domain mieten

Die zusätzliche Domain hat den Vorteil, dass sie günstiger ist (momentan 5,04€ pro Jahr für eine .de-Domain). Die Webhosting-Pakete (ab 2,17€ pro Monat) bieten euch jedoch zusätzliche Funktionen, wie z.B. E-Mail-Postfächer und Webspace.

Schritt 3: Domain konfigurieren

Nachdem ihr die Domain gemietet habt, müsst ihr sie konfigurieren. Dazu loggt ihr euch in das CCP ein und klickt auf “Domains”. Dort wählt ihr eure Domain aus und klickt auf “DNS”.

Dort fügt ihr zwei neue A-Records hinzu. Der Host ist ”@” (für die Hauptdomain) und ”*” (für alle Subdomains). Als Ziel tragt ihr die IP-Adresse eures Servers ein.

Wenn ihr das Webhosting-Paket habt, löscht zunächst die Einträge für ”@” und ”*” sowohl bei den A-Records als auch bei den AAAA-Records. Der Rest muss so bleiben, wie er ist, damit die E-Mail-Postfächer und der Webspace funktionieren.

Jetzt müsst ihr warten, bis die DNS-Änderungen überall propagiert sind. Das kann bis zu 24 Stunden dauern. Ihr könnt es im Terminal mit ping eure-domain.de testen. Wenn die IP-Adresse eures Servers zurückkommt, ist die Domain bereit.

Schritt 4: Server neu installieren

Ihr könnt euch nun im Control Panel Server einloggen und dort euren Server auswählen. Unter “Medien” und dann “Images” könnt ihr ein neues Betriebssystem auswählen. Ich empfehle Ubuntu 22.04 LTS (Updates bis 2027).

Während der Installation solltet ihr einen Benutzer erstellen.

Schritt 5: SSH-Verbindung herstellen

Nachdem die Installation abgeschlossen ist, könnt ihr euch per SSH mit eurem Server verbinden. Dazu nutzen wir VSCode. Installiert euch das Remote-SSH-Plugin und klickt auf das Symbol in der linken unteren Ecke. Dort könnt ihr “Remote-SSH: Connect to Host…” auswählen und eure SSH-Verbindung konfigurieren. Der Befehl ssh benutzer@ip sollte euch auch verbinden.

Wenn die Verbindung steht, könnt ihr den Home-Ordner eures Benutzers im Explorer öffnen und dort eure Dateien bearbeiten. Außerdem könnt ihr das Terminal nutzen, um Befehle auszuführen:

sudo apt update
sudo apt upgrade

Schritt 6: Docker und Docker-Compose installieren

Als nächstes installieren wir Docker. Dazu führen wir folgende Befehle aus:

sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/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/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Schritt 7: Caddy vorbereiten

Wir nutzen Caddy als Reverse-Proxy, um Paperless-ngx und Wireguard über HTTPS erreichbar zu machen und später externe Verbindungen abzulehnen.

Wir bruchen erst ein Netzwerk, um Caddy mit den anderen Containern zu verbinden:

sudo docker network create proxy

Nun erstellen wir einen Ordner für Caddy und legen die Dateien an:

mkdir caddy
cd caddy
mkdir data config
touch docker-compose.yml Caddyfile

In der docker-compose.yml-Datei tragen wir folgendes ein:

version: "3.7"

networks:
    proxy:
        external: true
        name: proxy

services:
    caddy:
        image: caddy:2
        container_name: caddy
        restart: unless-stopped
        ports:
            - 80:80
            - 443:443
        volumes:
            - ./data:/data
            - ./config:/config
            - ./Caddyfile:/etc/caddy/Caddyfile:ro
        networks:
            - proxy

Schritt 8: WG-Easy installieren

Nun installieren wir WG-Easy, um eine sichere Verbindung zu unserem Server herzustellen. Dazu führen wir folgende Befehle aus:

cd ~
mkdir wireguard
cd wireguard
mkdir data
touch docker-compose.yml

Wir tragen folgendes in die docker-compose.yml-Datei ein:

version: "3.8"

networks:
    proxy:
        name: proxy
        external: true

services:
    wg-easy:
        environment:
            - WG_HOST=wireguard.pixan.de
            - PASSWORD=somepassword
    image: ghcr.io/wg-easy/wg-easy:10
        container_name: wg-easy
        volumes:
            - ./data:/etc/wireguard
    ports:
        - "51820:51820/udp"
    restart: unless-stopped
    cap_add:
        - NET_ADMIN
        - SYS_MODULE
    sysctls:
        - net.ipv4.ip_forward=1
        - net.ipv4.conf.all.src_valid_mark=1
    networks:
        - proxy

Ändert die Umgebungsvariablen WG_HOST und PASSWORD nach euren Wünschen. Jetzt kann der Container gestartet werden:

sudo docker-compose up -d

Schritt 9: Proxy konfigurieren

Nun tragen wir die Konfiguration für Caddy ein. Dazu öffnen wir die Caddyfile-Datei und tragen folgendes ein:

{
    acme_ca https://acme-v02.api.letsencrypt.org/directory
    email   mail@domain.com
}

wireguard.pixan.de {
    reverse_proxy wg-easy:51821
}

Ersetzt die E-Mail-Adresse und die Domain nach euren Wünschen. Jetzt kann Caddy gestartet werden:

sudo docker-compose up -d

Schritt 10: Wireguard Verbindung herstellen

Nun könnt ihr eure gerade festgelegte Domain besuchen. Dort sollte die WG-Easy-Webseite erscheinen. Über das Interface lässt sich ein neuer Client erstellen. Die Konfigurationsdatei kann heruntergeladen werden (oder als QR-Code angezeigt werden).

Die Konfigurationsdatei könnt ihr auf euer Gerät importieren. Dazu benötigt ihr die Wireguard-App. Nachdem ihr die Konfigurationsdatei importiert habt, könnt ihr die Verbindung herstellen.

Schritt 11: Externe Verbindungen blockieren

Zum Schluss blockieren wir externe Verbindungen zu unserem Server. Dazu ändern wir das Caddyfile:

{
    acme_ca https://acme-v02.api.letsencrypt.org/directory
    email   mail@domain.com
}

wireguard.pixan.de {
    @blocked not remote_ip private_ranges
    respond @blocked 403
    reverse_proxy wg-easy:51821
}

Und wir starten Caddy neu:

cd ~/caddy
sudo docker-compose down
sudo docker-compose up -d

Schritt 12: Paperless-ngx installieren

Nun können wir Paperless-ngx installieren. Dazu erstellen wir einen neuen Ordner und legen die Dateien an:

cd ~
mkdir paperless
cd paperless
mkdir consume db export media data redis db-backup
touch docker-compose.yml

Wir brauchen noch unsere Benutzer-ID für die Berechtigungen:

id benutzernamedesservers

Die Ausgabe sollte so aussehen:

uid=1000(benutzernamedesservers) gid=1000(benutzernamedesservers) groups=1000(benutzernamedesservers)

In die docker-compose.yml-Datei tragen wir folgendes ein:

version: "3.4"

networks:
    internal:
        external: false
    proxy:
        name: proxy
        external: true

services:
    broker:
        container_name: paperless-redis
        image: redis:7
        networks:
            - internal
        restart: unless-stopped
        volumes:
            - ./redis:/data

    db:
        container_name: paperless-db
        image: postgres:16
        networks:
            - internal
        restart: unless-stopped
        volumes:
            - ./db:/var/lib/postgresql/data
        environment:
            POSTGRES_DB: paperless
            POSTGRES_USER: paperless
            POSTGRES_PASSWORD: einPasswort # ggf. an drei Stellen ändern

    webserver:
        container_name: paperless
        image: ghcr.io/paperless-ngx/paperless-ngx:2.4
        networks:
            - internal
            - proxy
        restart: unless-stopped
        depends_on:
            - db
            - broker
        healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:8000"]
            interval: 30s
            timeout: 10s
            retries: 5
        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: einPasswort # ggf. an drei Stellen ändern
            USERMAP_UID: 1000 # ggf. ändern
            USERMAP_GID: 1000 # ggf. ändern
            PAPERLESS_OCR_LANGUAGES: eng deu # ggf. ändern
            PAPERLESS_SECRET_KEY: pa6lHUuc1W8PQWdsP6wXViH1cJoKV38zj9ixRkDeTv3Q0iX8O9pti6tr5edgeheim # ändern
            PAPERLESS_ALLOWED_HOSTS: "localhost,paperless.pixan.de" # ändern
            PAPERLESS_TIME_ZONE: Europe/Berlin # ggf. ändern
            PAPERLESS_OCR_LANGUAGE: deu # ggf. ändern
            PAPERLESS_FILENAME_FORMAT: "{created_year}/{correspondent}/{title}" # ggf. ändern
            PAPERLESS_TIKA_ENABLED: 1
            PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000/
            PAPERLESS_TIKA_ENDPOINT: http://tika:9998
            PAPERLESS_URL: "https://paperless.pixan.de" # ändern

    db-backup:
        container_name: paperless-db-backup
        image: postgres:16
        volumes:
            - ./db-backup:/dump
            - /etc/localtime:/etc/localtime:ro
        environment:
            PGHOST: db
            PGDATABASE: paperless
            PGUSER: paperless
            PGPASSWORD: einPasswort # ggf. an drei Stellen ändern
            BACKUP_NUM_KEEP: 10
            BACKUP_FREQUENCY: 7d
        entrypoint: |
            bash -c 'bash -s <<EOF
            trap "break;exit" SIGHUP SIGINT SIGTERM
            sleep 2m
            while /bin/true; do
                pg_dump -Fc > /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.psql
                (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql)|sort|uniq -u|xargs rm -- {}
                sleep $$BACKUP_FREQUENCY
            done
            EOF'
        networks:
            - internal

    gotenberg:
        image: gotenberg/gotenberg:8
        restart: unless-stopped
        environment:
            CHROMIUM_DISABLE_ROUTES: 1
        command:
            - "gotenberg"
            - "--chromium-disable-javascript=true"
            - "--chromium-allow-list=file:///tmp/.*"
        networks:
            - internal

    tika:
        image: apache/tika:2.9.1.0
        restart: unless-stopped
        networks:
            - internal

Passt die Umgebungsvariablen an eure Gegebenheiten an. Die PAPERLESS_SECRET_KEY sollte ein zufälliger String sein. Die PAPERLESS_URL sollte eure Domain sein. Die PAPERLESS_ALLOWED_HOSTS sollte eure Domain und localhost enthalten.

Nun kann der Container gestartet werden:

sudo docker-compose up -d

Schritt 13: Benutzer hinzufügen

Wir benötigen einen Benutzer, um uns in Paperless-ngx einloggen zu können. Dazu führen wir folgenden Befehl aus:

sudo docker exec -it paperless python manage.py createsuperuser

Oder:

sudo docker exec -it paperless sh
python manage.py createsuperuser
exit

Schritt 14: Paperless-ngx Proxy konfigurieren

Zum Schluss tragen wir die Konfiguration für Paperless-ngx in das Caddyfile ein:

{
    acme_ca https://acme-v02.api.letsencrypt.org/directory
    email   mail@domain.com
}

wireguard.pixan.de {
    @blocked not remote_ip private_ranges
    respond @blocked 403
    reverse_proxy wg-easy:51821
}

paperless.pixan.de {
    @blocked not remote_ip private_ranges
    respond @blocked 403
    reverse_proxy paperless:8000
}

Und wir starten Caddy neu:

cd ~/caddy
sudo docker-compose down
sudo docker-compose up -d

Schritt 15: Paperless-ngx konfigurieren

Nun könnt ihr euch in Paperless-ngx einloggen und die Konfiguration anpassen. Dazu geht ihr auf eure Domain und loggt euch mit eurem Benutzer ein. Dort könnt ihr die Einstellungen anpassen und Dokumente hinzufügen.

Wichtig wäre hier die Einrichtung des Mail-Servers, um Dateien direkt via E-Mail zu archivieren.

Vergesst nicht auch eine Regel dafür einzurichten.

Ihr könnt auch weitere Benutzer hinzufügen und ihnen Rechte geben.

Schritt 16: Dokumente archivieren

Nun könnt ihr Dokumente hinzufügen und archivieren. Ihr habt mehrere Möglichkeiten:

• Dateien per Drag & Drop in das User Interface ziehen
• Dateien in den consume-Ordner auf dem Server legen (z. B. per SFTP)
• Dateien per E-Mail an eure Paperless-ngx-Adresse schicken
• Paperless-Share auf eurem Android-Smartphone nutzen

Unterstützt werden PDFs, Office-Dokumente, Text-Dateien, E-Mails.

Schritt 17: Paperless-ngx sichern

Zum Schluss solltet ihr eure Paperless-ngx-Instanz sichern. Dazu könnt ihr die Datenbank und die Dateien sichern im Media-Ordner sichern.

Ihr könnt auch den document_exporter nutzen, um die Dokumente zu exportieren.

sudo docker exec -it paperless python manage.py document_exporter

Danach muss der Export-Ordner gesichert werden. Möglich wäre das beispielsweise mit Borg oder Rclone.

Schritt 18: Aktualisieren

Ihr solltet regelmäßig Updates einspielen.

Server aktualisieren:

sudo apt update
sudo apt upgrade

Images aktualisieren:

cd ~/caddy
sudo docker-compose pull
sudo docker-compose down && sudo docker-compose up -d
cd ~/wireguard
sudo docker-compose pull
sudo docker-compose down && sudo docker-compose up -d
cd ~/paperless
sudo docker-compose pull
sudo docker-compose down && sudo docker-compose up -d

Ihr könnt auch sowas wie Watchtower nutzen, um das automatisch zu machen. Werden die Tags nach Semvar festgelegt, sollte ein Update keine Probleme machen.

Grundsätzlich gibt dann die erste Zahl die Hauptversion an. Diese kann größere Änderungen enthalten, die zu Inkompatibilitäten führen können. Die zweite Zahl gibt Änderungen (neue Funktionalitäten) an, die abwärtskompatibel sind. Die dritte Zahl gibt Bugfixes und Sicherheitsupdates an, die abwärtskompatibel sind.

In Paperless wird nach der oben erstellen Konfiguration, die Version 2.4 genutzt. Das kann sowohl 2.4.0 als auch 2.4.1 usw. sein. Wenn ihr 2.5 nutze n wollt, müsst ihr das Image in der docker-compose.yml-Datei anpassen.

Voher müsst ihr das Image in der docker-compose.yml-Datei anpassen.

Bei Postgres solltet ihr nicht einfach die Version aktualisieren, ohne eine Migration durchzuführen.

Es ist im Übrigen nicht nötig die neuste Hauptversion zu benutzen, solange es Sicherheitsupdates gibt. Ihr müsst auch prüfen, ob die neuste Version überhaupt unterstützt wird.

Fazit

Herzlichen Glückwunsch! Ihr habt Paperless-ngx auf einem VPS installiert. Nun könnt ihr von überall auf eure Dokumente zugreifen und sie sicher verwalten. Wenn ihr Fragen oder Anmerkungen habt, könnt ihr sie gerne in den Kommentaren hinterlassen.