HowtoForge

So installierst du Paperless mit Nginx unter Debian

von ·

Paperless ist eine Python-Anwendung, die gescannte Dokumente einliest, indiziert und in einer benutzerfreundlichen Weboberfläche darstellt. In diesem Lernprogramm installieren wir Paperless mit einem Nginx HTTPS Reverse Proxy unter Debian 10.

Voraussetzungen

  • Ein Debian 10 System, auf dem du Root-Zugriff hast.
  • Ein registrierter Domainname, der auf deinen Server zeigt.

Alle in diesem Dokument gezeigten Befehle sollten als root ausgeführt werden, sofern nicht anders angegeben.

Setze die Umgebungsvariable $VISUAL auf einen Texteditor deiner Wahl. Du kannst zum Beispiel nano verwenden:

echo "export VISUAL=nano" >> ~/.bashrc
. ~/.bashrc

Schritt 1: Installieren der Abhängigkeiten

Für die Installation und den Betrieb von Paperless werden verschiedene Softwarekomponenten benötigt. Installiere sie wie folgt:

apt update
apt install -y gnupg2 python3 python3-dev python3-pip python3-virtualenv tesseract-ocr tesseract-ocr-eng unpaper imagemagick libpoppler-cpp-dev optipng git gcc g++

Wenn du mit Dokumenten in anderen Sprachen als Englisch arbeiten willst, installiere die passenden Tesseract-Sprachdateien. Zum Beispiel für französisch und spanisch:

apt install -y tesseract-ocr-fra tesseract-ocr-spa

Du kannst alle verfügbaren Tesseract-Pakete mit auflisten:

apt list tesseract-ocr-*

Wenn du dir nicht sicher bist, welcher 3-Buchstaben-Code der gewünschten Sprache entspricht, sieh dir diese ISO 639-2 Codeliste an.

Schritt 2: Einen Systembenutzer anlegen

Es ist zwar möglich, paperless als root auszuführen, aber es wird dringend empfohlen, einen Benutzer mit geringen Rechten und deaktivierter Anmeldung zu verwenden. Erstelle einen Benutzer und eine Gruppe mit dem Namen paperless:

useradd -d /opt/paperless -M -r -s /bin/bash -U -p x paperless

Schritt 3: Installieren von Paperless

Klone das Paperless-Github-Repository nach /opt/paperless

git clone https://github.com/the-paperless-project/paperless.git /opt/paperless

Gib dem Benutzer paperless die Rechte an diesem Verzeichnis:

chown -R paperless:paperless /opt/paperless

Kopiere das mitgelieferte Konfigurationsbeispiel als Ausgangspunkt:

cp /opt/paperless/paperless.conf.example /etc/paperless.conf

Öffne es in deinem Texteditor:

$VISUAL /etc/paperless.conf

Wähle ein Verzeichnis, aus dem Paperless gescannte Dokumente einlesen soll, und setze den Parameter PAPERLESS_CONSUMPTION_DIR entsprechend:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Finde, entkommentiere (indem du das #-Zeichen entfernst) und ändere die Werte der folgenden Zeilen in etwas Sicheres:

#PAPERLESS_PASSPHRASE="secret"
#PAPERLESS_SECRET_KEY="change-me"

Wenn dein Scanner das Versenden von gescannten Dokumenten per E-Mail unterstützt, kannst du sie automatisch aus dem Posteingang einlesen lassen. Um diese Funktion zu aktivieren, setze die Optionen PAPERLESS_CONSUME_MAIL_*. Aus Sicherheitsgründen empfiehlt es sich, ein eigenes E-Mail-Konto für Paperless einzurichten. Ein Beispiel:

PAPERLESS_CONSUME_MAIL_HOST="imap.example.com"
PAPERLESS_CONSUME_MAIL_PORT="993"
PAPERLESS_CONSUME_MAIL_USER="paperless@example.com"
PAPERLESS_CONSUME_MAIL_PASS="imap_password"

Speichere deine Änderungen und beende das Programm, dann ändere den Besitzer dieser Datei auf papierlos und erhöhe die Berechtigungen:

chown paperless:paperless /etc/paperless.conf
chmod 0400 /etc/paperless.conf

Wechsle zum Paperless-Benutzer:

su - paperless

Erstelle das Verzeichnis consumption:

mkdir /opt/paperless/paper_in

Erstelle eine virtuelle Python-Umgebung. Diese bietet eine stabile und isolierte Umgebung, in der wir die spezifischen Python-Module und -Versionen installieren können, die Paperless benötigt.

python3 -m virtualenv --python=/usr/bin/python3 venv

Aktiviere sie:

. venv/bin/activate

Installiere die von Paperless benötigten Python-Module:

pip3 install -r requirements.txt

Dieser Befehl kann eine Weile dauern. Sobald er abgeschlossen ist, führe die folgenden Befehle aus, um die Datenbank zu initialisieren und die statischen Dateien für den Webdienst zu erstellen:

cd src/
./manage.py migrate
./manage.py collectstatic

Erstelle die Anmeldedaten für das Administratorkonto der Weboberfläche, indem du den folgenden Befehl ausführst und die Eingabeaufforderungen beantwortest:

./manage.py createsuperuser

Schritt 4: Erste Tests

Bevor wir einen richtigen Webserver und systemd-Dienste einrichten, versuchen wir, Paperless manuell zu starten. Zu diesem Zeitpunkt solltest du noch als Paperless in der virtuellen Python-Umgebung angemeldet sein.

Starte den Webserver und den Dokumentenverbraucher im Hintergrund:

./manage.py runserver 0.0.0.0:8000 &
./manage.py document_consumer &

Lege ein beliebiges gescanntes Dokument in das in Schritt 3 konfigurierte Konsumverzeichnis. Ein Beispiel:

wget https://i.imgur.com/DPr5wWG.jpg -O /opt/paperless/paper_in/test1.jpg

Gehe zu http://IP_or_DOMAIN:8000/ und melde dich mit den in Schritt 3 gewählten Zugangsdaten an. Im Menü „DOKUMENTE“ klickst du auf „Dokumente“, um die Dokumentenliste anzuzeigen. Innerhalb weniger Minuten sollte das gescannte Dokument verarbeitet und verfügbar sein.

Beende Paperless, bevor du mit dem nächsten Schritt fortfährst:

pkill -f manage.py

Schritt 5: Systemd-Dienste

Wir erstellen systemd-Unit-Dateien, damit wir die Web- und Verbraucherdienste richtig verwalten können. Gehe zurück zu deiner Root-Shell:

exit

Erstelle eine Unit-Datei für den Webdienst:

$VISUAL /etc/systemd/system/paperless-webserver.service

Und gib Folgendes ein:

[Unit]
Description=Paperless Gunicorn Web Server
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/gunicorn --pythonpath=/opt/paperless/src paperless.wsgi -w 3 -b 127.0.0.1:8000
Restart=on-failure
[Install]
WantedBy=multi-user.target

HINWEIS: Möglicherweise möchtest du die Anzahl der Worker-Prozesse im ExecStart-Befehl ändern. Der hier gezeigte Dienst startet Gunicorn mit 3 Workern(-w 3).

Als Nächstes erstellst du eine weitere Unit-Datei für den Document Consumer Process:

$VISUAL /etc/systemd/system/paperless-consumer.service

Und gib Folgendes ein:

[Unit]
Description=Paperless Document Consumer
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/python3 /opt/paperless/src/manage.py document_consumer
Restart=on-failure
[Install]
WantedBy=multi-user.target

Starte diese Dienste:

systemctl daemon-reload
systemctl start paperless-webserver.service paperless-consumer.service

Vergewissere dich, dass beide Dienste laufen:

systemctl status paperless-webserver.service paperless-consumer.service

Wenn du möchtest, dass Paperless beim Systemstart automatisch gestartet wird, führe den Befehl aus:

systemctl enable paperless-webserver.service paperless-consumer.service

Schritt 6: Nginx Reverse Proxy und HTTPS

Installiere Nginx und certbot:

apt update
apt install -y nginx certbot

Stelle sicher, dass Nginx aktiviert ist und läuft:

systemctl enable --now nginx.service

Besorge dir mit certbot ein Let’s Encrypt-Zertifikat für deine Domain:

certbot certonly --webroot --webroot-path /var/www/html -d your_domain

Deaktiviere die Standardkonfigurationsdatei von Nginx und öffne eine neue Datei:

rm /etc/nginx/sites-enabled/default
$VISUAL /etc/nginx/sites-available/paperless

Gib Folgendes ein und ersetze deine_Domain durch deinen Domainnamen:

server {
    listen 80;
    server_name your_domain;
    return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
}
server {
    listen 443 ssl;
    server_name your_domain;
    index index.html index.htm index.php;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
    ssl on;
    ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
    location /static {
        autoindex on;
        alias /opt/paperless/static;
    }
    location / {
        proxy_set_header Host $http_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-Proto $scheme;
        proxy_pass http://127.0.0.1:8000;
    }
}

Aktiviere diese Konfiguration, indem du sie im Nginx-Verzeichnis sites-enabled verlinkst, und überprüfe sie auf eventuelle Fehler:

ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled
nginx -t

Lade dann die Änderungen:

systemctl reload nginx.service

Deine Paperless-Instanz sollte jetzt unter https://your_domain erreichbar sein .

Schritt 7: Weiterentwicklungen

Da der Paperless-Systembenutzer nach der Ersteinrichtung keinen Zugriff auf eine funktionierende Shell benötigt, können wir ihn in /usr/sbin/nologin ändern:

usermod -s /usr/sbin/nologin paperless

Fehlersuche

Wenn der Gunicorn Webserver mit der Fehlermeldung [ERROR] Connection in use nicht startet, überprüfe, ob bereits Prozesse an Port 8000/tcp gebunden sind:

ss -lntp

Beende/deaktiviere den störenden Prozess, falls nötig, oder ändere /etc/systemd/system/paperless-webserver.service und /etc/nginx/sites-enabled/paperless, um einen anderen Netzwerkport für Gunicorn zu verwenden.

Das könnte dich auch interessieren …