Paperless-ngx auf einem Ubuntu VPS installieren

Paperless-ngx ist eine beliebte Software für die Verwaltung und Digitalisierung von Dokumenten verschiedener Arten. Das Tool glänzt vor allem mit einer OCR Texterkennung, einer intelligenten Suchfunktion und innovativen Dokumenten Struktur.

In Verbindung mit einem geeigneten Scanner lassen sich Dokumente einfach digitalisieren, ablegen und wiederfinden. Es gibt verschiedene Möglichkeiten Paperless-ngx zu installieren. Z. B.:

• Auf der eigenen Serverstruktur (z. B. einer NAS)
• Auf einem Computer
• Auf einem virtuellen privaten Server, den du mietest.

Diese Anleitung erklärt wie du Paperless-ngx auf einem virtuellen privaten Server installierst (VPS) und auf einer Subdomain bereitstellst. Somit kannst du über das Web von jedem beliebigen Gerät auf dein Archiv zugreifen.

Der Vorteil des VPS liegt in den günstigen Kosten (Du kannst über verschiedene Anbieter monatlich einen VPS mieten). Eine NAS kann im Vergleich gerne 500 Euro kosten. Ein VPS ist eine gute Möglichkeit günstig zu starten und den Paperless Workflow zu testen.

Wir haben Paperless-ngx nach dieser Anleitung installiert. Das Ergebnis siehst du hier: paperless.digitizerspace.com

Du kannst dir überlegen unter welcher Subdomain du Paperless-ngx bereitstellen möchtest (z. B. paperless.deine-firmen-domain.de. Alternativ kannst du nach der Installation über die IP Adresse deines VPS auf die Software zugreifen.

Zunächst brauchst du einen VPS. Falls du noch keinen Anbieter hast, schaue dir die Angebote von contabo an. Wir arbeiten selbst mit contabo und haben bisher sehr gute Erfahrungen gemacht.

Wir empfehlen einen Linux Server zu wählen mit einer Ubuntu Version von 20.04 oder neuer. Bei contabo kannst du während der Bestellung Docker auswählen, so dass du diese Software später nicht mehr installieren musst.

Nachdem du ein Paket bestellt hast, erhältst du die Zugangsdaten per E-Mail. Für die Installation benötigst du die IP Adresse deines VPS und das root Passwort.

Eine Subdomain erstellst du bei deinem Domainanbieter (in der Regel wo deine Webseite gehostet ist). Du kannst einen beliebigen Namen wählen, der deiner Top-Level-Domain vorangestellt ist (z.B. paperless.deine-top-level-domain.de. Unter dieser Adresse wirst du später auf die Paperless-ngx Installation zugreifen können.

Anschließend musst du die DNS-Einstellungen für deine Domain anpassen. Die neue Subdomain muss auf die IP-Adresse deines VPS zeigen. Die DNS-Einstellungen findest du ebenfalls bei dem Anbieter, wo du deine Domain registriert hast.

Wenn du die Einstellungen aufrufst, legst du einen A-Record mit dem Namen deiner Subdomain (z. B. paperless) an. In dem IP-Feld trägst du die IP-Adresse deines VPS ein, die du bei der Bestellung erhalten hast.

Anschließend legst du einen zweiten A-Record an mit der Syntax www.deine-Subdomain (z.B. www.paperless) und der gleichen IP-Adresse wie vorher. Dies sorgt dafür, dass deine Domain sowohl mit als auch ohne Eingabe von www. auf deinen VPS zeigt.

Abschließend speicherst du die DNS-Einstellungen. Es kann bis zu 48h dauern bis die DNS-Einstellungen global überschrieben wurden.

Du kannst auf Webseiten wie z. B. dnschecker prüfen, ob deine Einstellungen bereits übernommen wurden. Dazu gibst du deine Subdomain in das Eingabefeld ein (z. B. paperless.deine-firma.de und wählst A-Record aus.

Dein VPS sollte dann über deinen Browser aufrufbar sein.

In diesem Schritt loggst du dich in deinen VPS ein und legst einen neuen Benutzer mit Admin Rechten an. Über diesen Benutzer installieren wir im Anschluss Paperless-ngx. Wir empfehlen nicht den root Benutzer zu verwenden.

Öffne ein Terminal und logge dich zunächst über SSH in deinen VPS mit dem root Benutzer ein. Ersetze die IP-Adresse mit der IP deines VPS:

ssh root@185.209.228.63

Anschließend wirst du nach einem Passwort gefragt. Gebe das Passwort ein, das du während des Bestellprozesses deines VPS gewählt hast.

root@185.209.228.63's password:

Jetzt kannst du einen neuen Benutzer mit einem beliebigen Namen erstellen:

sudo adduser tobias

Output

Adding user `tobias' ...

Adding new group `tobias' (1001) ...

Adding new user `tobias' (1001) with group `tobias' ...

Creating home directory `/home/tobias' ...

Copying files from `/etc/skel' ...

New password:

Vergib ein sicheres Passwort. Danach wirst du nach Informationen zu dem Benutzer gefragt. Du kannst Werte eingeben oder es leer lassen, indem du ENTER drückst.

Output

passwd: password updated successfully

Changing the user information for tobias

Enter the new value, or press ENTER for the default

	Full Name []:

	Room Number []:

	Work Phone []:

	Home Phone []:

	Other []:

Is the information correct? [Y/n] y

Dein neuer Benutzer ist nun angelegt. Wenn du alles richtig gemacht hast, solltest du bei Eingabe dieses Befehls

id tobias

folgenden Output bekommen:

uid=1001(tobias) gid=1001(tobias) groups=1001(tobias)

Der Benutzer hat aktuell Standardrechte. Wir geben dem Benutzer im nächsten Schritt Adminrechte, damit wir Software installieren können:

sudo usermod -a -G sudo tobias

Wir wechseln nun zu dem neuen Benutzer:

su -l tobias

Folgender Befehl ist nun ausführbar, wenn du das zuvor gewählte Passwort für den neuen Benutzer eingibst:

sudo apt update

Dies prüft die installierten Pakete auf Updates.

Für die nächsten Schritte benötigst du den angelegten Benutzer.

Diesen Schritt kannst du überspringen, falls du Docker bei der Bestellung deines VPS ausgewählt hast. Du kannst prüfen, ob Docker bei dir bereits installiert ist, wenn du folgenden Befehl eingibst und eine Version zurückbekommst:

docker -v

Output

Docker version 24.0.7, build afdd53b

Sollte Docker nicht installiert sein, kannst du in der Docker Dokumentation die wesentlichen Schritte nachlesen, die wir im Folgenden durchgehen.

1. Erstelle das Docker apt Verzeichnis.

Füge Docker’s offiziellen GPG Schlüssel hinzu:

sudo apt-get update

sudo apt-get install ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

Füge das Verzeichnis zu den Apt Quellen hinzu:

echo \

  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] 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

2. Die Docker Pakete installieren

Um die neueste Version zu installieren, führe diesen Befehl aus:

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

3. Verifiziere, dass Docker erfolgreich installiert wurde, indem du das hello-world image ausführst:

sudo docker run hello-world

Dieser Befehl lädt ein Testimage und führt es in einem Container aus. Sobald der Container gestartet wurde, wird eine Bestätigung ausgegeben und danach beendet sich der Container wieder.

Jetzt bist du bereit, Paperless-ngx auf deinem VPS zu installieren. Wir werden das Installationsskript von Paperless-ngx nutzen. Weitere Möglichkeiten der Installation kannst du in der Paperless-ngx Dokumentation nachlesen.

Führe folgenden Befehl aus, um die Installation zu starten:

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Output

#############################################

###   paperless-ngx docker installation   ###

#############################################

This script will download, configure and start paperless-ngx.

1. Application configuration

============================

The URL paperless will be available at. This is required if the

installation will be accessible via the web, otherwise can be left blank.

Example: https://paperless.example.com

URL []:

Gib nun die vollständige Adresse deiner Subdomain ein, worüber du auf Paperless-ngx zugreifen möchtest:

URL []: https://paperless.deine-firma.de

Output

The port on which the paperless webserver will listen for incoming

connections.

Port [8000]:

Drücke einfach ENTER, um den vorgegebenen Port 8000 zu verwenden.

Output

Paperless requires you to configure the current time zone correctly.

Otherwise, the dates of your documents may appear off by one day,

depending on where you are on earth.

Example: Europe/Berlin

See here for a list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Current time zone []:

Hier gibst du deine Zeitzone an. Den richtigen Identifier findest du auf der angegebenen Wikipedia Seite.

Output

Database backend: PostgreSQL, MariaDB, and SQLite are available. Use PostgreSQL

if unsure. If you're running on a low-power device such as Raspberry

Pi, use SQLite to save resources.

Database backend (postgres sqlite mariadb) [postgres]:

Hier wählst du eine Datenbank aus. Wir empfehlen PostgreSQL. Für postgres drücke einfach ENTER.

Output

Paperless is able to use Apache Tika to support Office documents such as

Word, Excel, Powerpoint, and Libreoffice equivalents. This feature

requires more resources due to the required services.

Enable Apache Tika? (yes no) [no]:

In diesem Schritt wählst du aus, ob du Apache Tika verwenden möchtest. Falls du später Office Dokumente in Paperless-ngx laden möchtest, solltest du diese Option aktivieren.

Der Hintergrund ist, dass Paperless-ngx nur permanente Dateiformate akzeptiert (wie z. B. PDF). Das Hochladen von Office Dokumenten wie Word, Excel, Powerpoint funktioniert standardmäßig nicht.

Apache Tika liest die Dokumente aus und erstellt PDFs, die Paperless-ngx problemlos verarbeiten kann. Falls du Apache Tika aktivieren möchtest, tippe yes.

Output

Specify the default language that most of your documents are written in.

Use ISO 639-2, (T) variant language codes:

https://www.loc.gov/standards/iso639-2/php/code_list.php

Common values: eng (English) deu (German) nld (Dutch) fra (French)

This can be a combination of multiple languages such as deu+eng

OCR language [eng]:

Dieser Schritt ist wichtig, um die Sprache deiner Dokumente festzulegen, damit die OCR Suchfunktion später korrekt funktioniert. Wenn du z.B. Deutsch und Englisch aktivieren möchtest, gib deu+eng ein. Der exakte Ländercode ist wichtig.

Ein Liste aller Ländercodes findest du unter dem angegebenen Link.

Output

Specify the user id and group id you wish to run paperless as.

Paperless will also change ownership on the data, media and consume

folder to the specified values, so it's a good idea to supply the user id

and group id of your unix user account.

If unsure, leave default.

User ID [501]:

Drücke ENTER, um die Vorgaben zu übernehmen.

Output

Group ID [20]:

Drücke ENTER, um die Vorgaben zu übernehmen.

Output

2. Folder configuration

=======================

The target folder is used to store the configuration files of

paperless. You can move this folder around after installing paperless.

You will need this folder whenever you want to start, stop, update or

maintain your paperless instance.

Target folder [/home/tobias/paperless-ngx]:

Hier wählst du den Ordner aus, in dem Paperless-ngx installiert werden soll. Mit ENTER übernimmst du die Vorgaben.

Output

The consume folder is where paperless will search for new documents.

Point this to a folder where your scanner is able to put your scanned

documents.

CAUTION: You must specify an absolute path starting with / or a relative

path starting with ./ here. Examples:

  /mnt/consume

  ./consume

Consume folder [/home/tobias/paperless-ngx/consume]:

In diesem Schritt kannst du den Pfad des Consume Ordners ändern. Das ist der Ordner, in dem dein Scanner die Dateien ablegen muss, damit der Import korrekt funktioniert.

Output

The media folder is where paperless stores your documents.

Leave empty and docker will manage this folder for you.

Docker usually stores managed folders in /var/lib/docker/volumes.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Media folder []:

In diesem Schritt wirst du nach dem Speicherpfad des Media Ordners gefragt. In diesem Ordner werden deine importierten Dokumente gespeichert.

Standardmäßig verwaltet Docker diesen Ordner. Wir empfehlen es auf ./media zu setzen, damit du später einfach darauf zugreifen kannst.

Output

The data folder is where paperless stores other data, such as your

search index and other data.

As with the media folder, leave empty to have this managed by docker.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Data folder []:

Das gleiche gilt für den Data Ordner. Wir empfehlen es auf ./data zu setzen.

Output

The database folder, where your database stores its data.

Leave empty to have this managed by docker.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Database folder []:

Für den Database Ordner gilt dies ebenso. Wir empfehlen hier ./database anzugeben.

Output

3. Login credentials

====================

Specify initial login credentials. You can change these later.

A mail address is required, however it is not used in paperless. You don't

need to provide an actual mail address.

Paperless username [tobias]:

Paperless password:

Paperless password (again):

Email [tobias@localhost]:

Jetzt setzt du einen Benutzernamen und ein Passwort. Das brauchst du gleich für den Login. Eine valide E-Mail Adresse ist nicht nötig, kann aber gesetzt werden.

Anschließend siehst du eine Zusammenfassung deiner initialen Konfigurationen. Drücke eine beliebige Taste, um die Konfiguration zu bestätigen und Paperless-ngx zu installieren.

Paperless-ngx läuft jetzt auf Port 8000. Öffne deinen Browser und navigiere zu deiner Subdomain mit der Angabe des Ports. Z.B. http://paperless.deine-firma.de:8000/. Paperless-ngx sollte starten und du kannst dich einloggen.

Aktuell ist die Angabe des Ports noch zwingend nötig. Im nächsten Schritt zeigen wir dir wie du auf Paperless-ngx ohne Angabe des Ports zugreifen kannst.

Ein Reverse Proxy ist die empfohlene Methode, um einen Anwendungsserver im Internet erreichbar zu machen. Nginx ist ein beliebter Webserver und eine beliebte Reverse Proxy Lösung.

1. Nginx installieren

Nginx kannst du über apt auf Ubuntu installieren. Aktualisiere erst deinen Verzeichnisindex. Dann installierst du Nginx:

sudo apt update

sudo apt install nginx

Drücke Y, um die Installation auszuführen. Falls du gefragt wirst, ob du den Dienst neustarten möchtest, drücke ENTER, um die Vorgaben zu akzeptieren.

Du musst den Zugang zu Nginx in deiner Firewall gewähren. Dazu fügst du folgende Regel hinzu:

sudo ufw allow 'Nginx HTTP'

Jetzt kannst du prüfen, ob Nginx läuft.

systemctl status nginx

Output

● nginx.service - A high performance web server and a reverse proxy server

     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)

     Active: active (running) since Tue 2024-01-25 06:52:46 UTC; 39min ago

       Docs: man:nginx(8)

   Main PID: 9919 (nginx)

      Tasks: 2 (limit: 2327)

     Memory: 2.9M

        CPU: 50ms

     CGroup: /system.slice/nginx.service

             ├─9919 "nginx: master process /usr/sbin/nginx -g daemon on; master_process on;"

             └─9920 "nginx: worker process

2. Server Block konfigurieren

Es wird empfohlen, eine separate Konfigurationsdatei zu erstellen, anstatt die Standard Konfiguration direkt zu bearbeiten. Erstelle und öffne eine neue Nginx Konfiguration mithilfe von nano oder einem anderen Texteditor:

sudo nano /etc/nginx/sites-available/paperless.deine-firma.de

Füge diesen Code Block in deine Datei ein und ersetze paperless.deine-firma.de mit deiner Domain. client_max_body_size definiert die maximal zulässige Dateigröße für Dokumente. Modfiziere diesen Wert, falls du größere Dateien hochladen möchtest. Die Parameter nach proxy_pass sind notwendig, damit Websockets mit Paperless funktionieren.

client_max_body_size 10M;

server {

    listen 80;

    listen [::]:80;

    server_name paperless.deine-firma.de www.paperless.deine-firma.de;

    location / {

        proxy_pass http://localhost:8000;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection "upgrade";

        proxy_redirect off;

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Host $server_name;

    }

}

Speichere und beende nano, indem du CTRL+X drückst. Danach bestätigst du mit Y und drückst ENTER.

Danach aktivierst du die Konfiguration. Dazu erstellst du einen Link von der Konfiguration zu dem sites-enabled Verzeichnis, welches Nginx beim Start liest:

sudo ln -s /etc/nginx/sites-available/paperless.deine-firma.de /etc/nginx/sites-enabled/

Du kannst nun deine Konfiguration auf Syntax Fehler testen:

sudo nginx -t

Falls keine Probleme ausgegeben werden, starte Nginx neu, um die Änderungen zu übernehmen:

sudo systemctl restart nginx

Nginx ist jetzt als Reverse Proxy für deinen Anwendungsserver konfiguriert. Du kannst über den Browser ohne die Angabe des Ports auf Paperless-ngx zugreifen.

Du hast vielleicht bereits beim Aufruf deiner Domain festgestellt, dass diese mit http:// beginnt anstatt mit https://. Dies stellt eine unsichere Verbindung dar.

Installiere zunächst snap auf Ubuntu:

sudo apt install snapd

Sichere deine Anwendung mit Let’s Encrypt, indem du folgenden Befehl eingibst:

sudo snap install --classic certbot

Verlinke den certbot Befehl von dem snap Installationsverzeichnis mit deinem Pfad, so dass du certbot direkt ausführen kannst:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Als nächstes erlaube HTTPS Traffic mit dem Nginx Full Profil:

sudo ufw allow 'Nginx Full'

Lösche das Nginx HTTP Profil, dass wir nicht mehr benötigen:

sudo ufw delete allow 'Nginx HTTP'

Nun nutzt du certbot mit deinem Domainnamen, um das Zertifikat zu bekommen:

sudo certbot --nginx -d paperless.deine-firma.de -d www.paperless.deine-firma.de

Du wirst im Anschluss gebeten, eine E-Mail Adresse einzugeben und den Terms of Service zuzustimmen. Du kannst außerdem entscheiden, ob du dich in eine E-Mail Liste eintragen möchtest oder nicht. Danach bekommst du die Nachricht, dass der Prozess erfolgreich war und das Zertifikat ausgestellt wurde:

Output

. . .

Successfully received certificate.

Certificate is saved at: /etc/letsencrypt/live/paperless.deine-firma.de/fullchain.pem

Key is saved at: /etc/letsencrypt/live/paperless.deine-firma.de/privkey.pem

This certificate expires on 2024-04-01.

These files will be updated when the certificate renews.

Certbot has set up a scheduled task to automatically renew this certificate in the background.

Deploying certificate

Successfully deployed certificate for paperless.deine-firma.de to /etc/nginx/sites-enabled/paperless.deine-firma.de

Successfully deployed certificate for www.paperless.deine-firma.de /etc/nginx/sites-enabled/paperless.deine-firma.de

Congratulations! You have successfully enabled HTTPS on https://paperless.deine-firma.de and https://www.paperless.deine-firma.de

. . .

Navigiere zu deiner Domain. Du wirst automatisch zu https:// weitergeleitet.

In dieser Anleitung habst du deinen VPS eingerichtet, eine Subdomain konfiguriert, die auf deinen VPS zeigt. Ebenso hast du einen Benutzer angelegt, Docker und Paperless-ngx installiert. Abschließend hast du Nginx als Reverse Proxy konfiguriert und deine Domain mit einem SSL Zertifikat gesichert.

Paperless-ngx sollte jetzt über deine Subdomain aufrufbar sein und automatisch auf https weiterleiten. Du kannst nun das Terminal schließen. Im Falle eines Serverneustarts startet Docker Paperless-ngx automatisch neu.

Logge dich ein und starte mit der Einrichtung von weiteren Benutzern und deinem Workflow.

🛠️ Paperless-ngx IT-Support 🛠️

Du benötigst Unterstützung bei der Installation oder Konfiguration von Paperless-ngx? Ich helfe dir gerne weiter! Schreib mir einfach eine Mail an: hello@digitizerspace.com