Installation · 5 min read · Sep 25, 2025

Wie man Paperless mit Nginx auf Debian installiert

Paperless ist eine Python-Anwendung, die gescannte Dokumente verarbeitet, sie indiziert und in einer benutzerfreundlichen Weboberfläche präsentiert. In diesem Tutorial werden wir Paperless mit einem Nginx HTTPS-Proxy auf Debian 10 installieren.

  • Ein Debian 10-System, auf dem Sie Root-Zugriff haben.
  • Ein registrierter Domainname, der auf Ihren Server verweist.

Alle in diesem Dokument gezeigten Befehle sollten als Root ausgeführt werden, es sei denn, es ist anders angegeben.

Setzen Sie die Umgebungsvariable $VISUAL auf einen Texteditor Ihrer Wahl. Zum Beispiel, um nano zu verwenden:

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

Paperless benötigt mehrere Softwarekomponenten für die Installation und den Betrieb. Installieren Sie 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 Sie mit Dokumenten in anderen Sprachen als Englisch arbeiten möchten, installieren Sie die entsprechenden Tesseract-Sprachdateien. Zum Beispiel für Französisch und Spanisch:

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

Sie können alle verfügbaren Tesseract-Pakete auflisten mit:

apt list tesseract-ocr-*

Wenn Sie sich nicht sicher sind, welcher 3-Buchstaben-Code der gewünschten Sprache entspricht, konsultieren Sie diese ISO 639-2-Codeliste.

Obwohl es möglich ist, Paperless als Root auszuführen, wird dringend empfohlen, einen Benutzer mit niedrigen Rechten und deaktiviertem Login zu verwenden. Erstellen Sie einen Benutzer und eine Gruppe mit dem Namen paperless:

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

Klonen Sie das Paperless-Github-Repository nach /opt/paperless

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

Geben Sie dem Benutzer paperless das Eigentum an diesem Verzeichnis:

chown -R paperless:paperless /opt/paperless

Kopieren Sie die enthaltene Konfigurationsprobe als Ausgangspunkt:

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

Und öffnen Sie es in Ihrem Texteditor:

$VISUAL /etc/paperless.conf

Wählen Sie ein Verzeichnis, aus dem Paperless gescannte Dokumente aufnehmen wird, und setzen Sie den Parameter PAPERLESS_CONSUMPTION_DIR entsprechend:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Suchen Sie die folgenden Zeilen, entfernen Sie das Kommentarzeichen (#) und ändern Sie die Werte in etwas Sicheres:

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

Wenn Ihr Scanner das E-Mailen gescannter Dokumente unterstützt, kann Paperless diese automatisch aus dem empfangenden Posteingang aufnehmen. Um diese Funktion zu aktivieren, setzen Sie die Optionen PAPERLESSCONSUME_MAIL*. Aus Sicherheitsgründen wird empfohlen, ein E-Mail-Konto zu erstellen, das ausschließlich für Paperless verwendet wird. Zum Beispiel:

PAPERLESS_CONSUME_MAIL_HOST="imap.example.com"
PAPERLESS_CONSUME_MAIL_PORT="993"
PAPERLESS_CONSUME_MAIL_USER="[email protected]"
PAPERLESS_CONSUME_MAIL_PASS="imap_password"

Speichern Sie Ihre Änderungen und beenden Sie, ändern Sie dann den Besitzer dieser Datei auf paperless und verschärfen Sie die Berechtigungen:

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

Wechseln Sie zum Benutzer paperless:

su - paperless

Erstellen Sie das Verbrauchsverzeichnis:

mkdir /opt/paperless/paper_in

Erstellen Sie eine Python-virtuelle Umgebung. Dies bietet eine stabile und isolierte Umgebung, in der wir die spezifischen Python-Module und -Versionen installieren können, die von Paperless benötigt werden.

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

Aktivieren Sie es:

. venv/bin/activate

Installieren Sie die von Paperless benötigten Python-Module:

pip3 install -r requirements.txt

Dieser Befehl kann eine Weile dauern. Sobald er abgeschlossen ist, führen Sie 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

Erstellen Sie Anmeldeinformationen für das Administrator-Konto der Weboberfläche, indem Sie den folgenden Befehl ausführen und die Eingabeaufforderungen beantworten:

./manage.py createsuperuser

Bevor wir einen ordentlichen Webserver und systemd-Dienste einrichten, werden wir versuchen, Paperless manuell auszuführen. Zu diesem Zeitpunkt sollten Sie noch als paperless in der virtuellen Python-Umgebung angemeldet sein.

Starten Sie den Webserver und den Dokumentenkonsumenten im Hintergrund:

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

Legen Sie ein gescanntes Dokument in das Verbrauchsverzeichnis, das in Schritt 3 konfiguriert wurde. Zum Beispiel:

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

Gehen Sie zu http://IP_or_DOMAIN:8000/ und melden Sie sich mit den in Schritt 3 gewählten Anmeldeinformationen an. Im Menü “DOKUMENTE” klicken Sie auf “Dokumente”, um die Dokumentenliste anzuzeigen. Innerhalb weniger Minuten sollte das gescannte Dokument verarbeitet und verfügbar sein.

Stoppen Sie Paperless, bevor Sie mit dem nächsten Schritt fortfahren:

pkill -f manage.py

Wir werden systemd-Einheitendateien erstellen, damit wir die Web- und Verbraucherdienste ordnungsgemäß verwalten können. Kehren Sie zu Ihrer Root-Shell zurück:

exit

Erstellen Sie eine Einheitendatei für den Webdienst:

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

Und geben Sie 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öchten Sie die Anzahl der Arbeitsprozesse im ExecStart-Befehl ändern. Der hier gezeigte Dienst startet Gunicorn mit 3 Arbeitern ( -w 3).

Erstellen Sie als Nächstes eine weitere Einheitendatei für den Dokumentenkonsumenten:

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

Und geben Sie 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

Starten Sie diese Dienste:

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

Stellen Sie sicher, dass beide laufen:

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

Wenn Sie möchten, dass Paperless beim Systemstart automatisch startet, führen Sie den Befehl aus:

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

Installieren Sie Nginx und certbot:

apt update
apt install -y nginx certbot

Stellen Sie sicher, dass Nginx aktiviert und läuft:

systemctl enable --now nginx.service

Erhalten Sie ein Let’s Encrypt-Zertifikat für Ihre Domain mit certbot:

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

Deaktivieren Sie die Standard-Nginx-Konfigurationsdatei und öffnen Sie eine neue:

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

Geben Sie Folgendes ein, ersetzen Sie your_domain durch Ihren 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;
    }
}

Aktivieren Sie diese Konfiguration, indem Sie einen Link dazu im Nginx-Verzeichnis sites-enabled erstellen, und überprüfen Sie auf Fehler:

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

Laden Sie dann die Änderungen:

systemctl reload nginx.service

Ihre Paperless-Instanz sollte jetzt unter https://your_domain zugänglich sein.

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

usermod -s /usr/sbin/nologin paperless

Wenn der Gunicorn-Webserver mit der Fehlermeldung [ERROR] Connection in use nicht starten kann, überprüfen Sie, ob bereits Prozesse an Port 8000/tcp gebunden sind:

ss -lntp

Beenden/Deaktivieren Sie den störenden Prozess falls erforderlich oder ändern Sie /etc/systemd/system/paperless-webserver.service und /etc/nginx/sites-enabled/paperless, um einen anderen Netzwerkport für Gunicorn zu verwenden.

Share: X/Twitter LinkedIn
#Installation

Erhalte neue Beiträge in deinem Posteingang.

Kein Spam. Jederzeit abmelden.