MagBrowser

MagBrowser ist eine kleine, passwortgeschützte Webanwendung zum Verwalten einer Magazinablage. Dateien und Ordner lassen sich zwischen einem Eingangsordner („Mags“) und einem Archiv verschieben, sicher löschen und bei Bedarf wiederherstellen.

Die Anwendung kann außerdem Bibliotheksscans in Komga und Ubooquity starten. Sie funktioniert direkt unter / sowie hinter einem Reverse Proxy unter /manage/.

Funktionen

• Anmeldung mit Benutzername und Passwort
• gemeinsames Verschieben mehrerer Dateien und Ordner
• Papierkorb mit Anzeige, Auswahl und Wiederherstellung
• endgültiges Leeren des Papierkorbs mit Sicherheitsabfrage
• automatische Gruppierung von Magazinen im Archiv und Papierkorb
• rekursive Bereinigung aller Nicht-Dokumente
• Aktualisierung von Komga und Ubooquity
• helles und dunkles Design
• integrierte Versions- und Updateanzeige
• Bedienung am Desktop und auf kleinen Bildschirmen

Was bedeuten „Mags“, „Archiv“ und „Papierkorb“?

• Mags ist der Eingangsordner. Hier liegen neu eingetroffene Magazine.
• Archiv ist der Zielordner für einsortierte Magazine.
• Papierkorb ist ein eigener, von MagBrowser verwalteter Ordner. Normales Löschen entfernt Dateien nicht sofort endgültig.

Das Archiv kann innerhalb des Mags-Ordners liegen. MagBrowser blendet es dann automatisch aus der Mags-Ansicht aus.

Voraussetzungen

• Python 3.11 oder neuer
• Schreibrechte auf Mags-, Archiv- und Papierkorbverzeichnis
• für automatische Updates: Git und Linux mit systemd
• optional: erreichbare Komga- und/oder Ubooquity-Installation

Schnellstart unter Windows und PyCharm

1. Das Projekt in PyCharm öffnen.

2. Eine virtuelle Python-Umgebung für das Projekt anlegen.

3. Im PyCharm-Terminal die Abhängigkeiten installieren:

   pip install -r requirements.txt
   

4. Unter Run → Edit Configurations → Environment variables mindestens folgende Werte eintragen:

   AUTH_USERNAME=admin
   AUTH_PASSWORD=ein-langes-einmaliges-testpasswort
   AUTH_COOKIE_SECURE=false
   SOURCE_DIR=C:\Users\DEINNAME\Documents\Dateibrowser\mags
   ARCHIVE_DIR=C:\Users\DEINNAME\Documents\Dateibrowser\mags\Archiv
   TRASH_DIR=C:\Users\DEINNAME\Documents\Dateibrowser\.mags-trash
   

5. Die Anwendung starten:

   uvicorn app.main:app --reload
   

6. Im Browser öffnen:

   http://127.0.0.1:8000

Alternativ kann main.py direkt über PyCharm gestartet werden.

Wichtig: MagBrowser lädt eine lokale .env-Datei nicht selbstständig. Unter PyCharm müssen die Werte in der Run Configuration stehen. Unter Linux wird weiter unten eine systemd-Umgebungsdatei eingerichtet.

Installation unter Linux

Die folgenden Beispiele verwenden /opt/magBrowser als Installationspfad und magbrowser als Dienstbenutzer.

1. Projekt und Python-Umgebung vorbereiten

cd /opt/magBrowser
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Der Dienstbenutzer benötigt Schreibrechte auf das Projektverzeichnis, wenn die automatische Git-Aktualisierung verwendet werden soll. Er benötigt außerdem Schreibrechte auf SOURCE_DIR, ARCHIVE_DIR und TRASH_DIR.

2. Konfiguration anlegen

Die Zugangsdaten gehören nicht in das Git-Repository. Lege stattdessen eine geschützte Datei an:

sudo nano /etc/magbrowser.env

Minimalbeispiel:

SOURCE_DIR=/mnt/extern/usenet/mags
ARCHIVE_DIR=/mnt/extern/usenet/mags/Archiv
TRASH_DIR=/mnt/extern/usenet/.mags-trash

AUTH_USERNAME=admin
AUTH_PASSWORD=hier-ein-langes-zufälliges-passwort-eintragen
AUTH_SESSION_HOURS=12
AUTH_COOKIE_SECURE=true

SYSTEMD_SERVICE=magbrowser

Datei schützen:

sudo chown root:root /etc/magbrowser.env
sudo chmod 600 /etc/magbrowser.env

Bei einem reinen HTTP-Test muss AUTH_COOKIE_SECURE=false gesetzt werden. Im HTTPS-Produktivbetrieb gehört der Wert auf true.

3. systemd-Dienst einrichten

Datei /etc/systemd/system/magbrowser.service anlegen:

[Unit]
Description=MagBrowser Webanwendung
After=network.target

[Service]
Type=simple
User=magbrowser
Group=magbrowser
WorkingDirectory=/opt/magBrowser
EnvironmentFile=/etc/magbrowser.env
ExecStart=/opt/magBrowser/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8001
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Dienst aktivieren:

sudo systemctl daemon-reload
sudo systemctl enable --now magbrowser
sudo systemctl status magbrowser --no-pager -l

Live-Protokoll anzeigen:

sudo journalctl -u magbrowser -n 50 -f

Die Anzeige wird mit Strg+C beendet.

Konfiguration

Erforderliche Einstellungen

Variable	Bedeutung
AUTH_USERNAME	Benutzername der Webanmeldung
AUTH_PASSWORD	Passwort der Webanmeldung
SOURCE_DIR	Eingangsordner „Mags“
ARCHIVE_DIR	Archivordner
TRASH_DIR	von MagBrowser verwalteter Papierkorb

Ohne AUTH_USERNAME und AUTH_PASSWORD verweigert die Anwendung aus Sicherheitsgründen den Start.

Weitere Einstellungen

Variable	Standard	Bedeutung
AUTH_SESSION_HOURS	12	Gültigkeitsdauer einer Anmeldung; erlaubt sind 1 bis 168 Stunden
AUTH_COOKIE_SECURE	false	true verwenden, wenn der öffentliche Zugriff ausschließlich über HTTPS erfolgt
AUTH_PROXY_ENABLED	false	Anmeldung über vertrauenswürdige Authentik-Proxy-Header aktivieren
AUTH_PROXY_TRUSTED_IPS	leer	kommagetrennte IP-Adressen der zugelassenen Reverse Proxys
AUTH_PROXY_REQUIRED_GROUP	magazine-users	erforderliche Authentik-Gruppe
SYSTEMD_SERVICE	magbrowser	Name des Dienstes für den automatischen Neustart nach Updates

Die Sitzung wird in einem signierten HttpOnly-Cookie gespeichert. Eine Passwortänderung macht vorhandene Sitzungen automatisch ungültig.

Authentik-Proxy-Anmeldung

MagBrowser akzeptiert die Header X-Authentik-Username und X-Authentik-Groups nur dann als Anmeldung, wenn die Anfrage unmittelbar von einer in AUTH_PROXY_TRUSTED_IPS hinterlegten IP-Adresse stammt. Direkte Anfragen mit selbst gesetzten Headern werden abgewiesen. Der lokale Login mit AUTH_USERNAME und AUTH_PASSWORD bleibt als Rückfallmöglichkeit erhalten.

Beispiel:

AUTH_PROXY_ENABLED=true
AUTH_PROXY_TRUSTED_IPS=10.0.1.134
AUTH_PROXY_REQUIRED_GROUP=magazine-users

Bei aktivierter Proxy-Anmeldung führt Abmelden zu /outpost.goauthentik.io/sign_out und beendet die Sitzung des Authentik-Proxy-Providers.

Komga anbinden

MagBrowser benötigt einen Komga-API-Schlüssel mit Administratorrechten sowie die ID der gewünschten Bibliothek.

KOMGA_URL=http://10.0.1.231:2211
KOMGA_LIBRARY_ID=0MA91TPYQ28P5
KOMGA_API_KEY=hier-den-komga-api-key-eintragen

Bibliotheks-ID ermitteln

Mit einem Komga-Admin-Benutzer:

curl -sS -u 'DEINE_KOMGA_EMAIL' \
  http://10.0.1.231:2211/api/v1/libraries | python3 -m json.tool

curl fragt nach dem Passwort. In der Ausgabe steht für jede Bibliothek ein Feld id.

In den Scanner-Einstellungen der Komga-Bibliothek sollte Empty trash automatically after every scan aktiviert sein. So entfernt Komga nicht mehr vorhandene Einträge nach einem Scan automatisch aus seiner Datenbank.

Ubooquity anbinden

Unter Ubooquity 3 muss in Advanced die Option Allow remote scan triggering using secret API key aktiviert und gespeichert werden.

UBOOQUITY_SCAN_URL=http://10.0.1.231:2202/ubooquity/public-api/scan
UBOOQUITY_API_KEY=hier-den-ubooquity-api-key-eintragen

Je nach Installation kann der URL-Pfad ohne /ubooquity lauten. Der von Ubooquity in der Hilfe angezeigte Beispielaufruf ist maßgeblich.

Sicherer Funktionstest ohne Schlüssel in der Shell-Historie:

read -rsp 'Ubooquity API-Key: ' UBOO_KEY
echo
curl -i --request POST \
  --url http://10.0.1.231:2202/ubooquity/public-api/scan \
  --data-raw "$UBOO_KEY"
unset UBOO_KEY

Verhalten des Bibliotheksbuttons

Der Button zeigt anhand der geladenen Konfiguration das verfügbare Backend:

• K+U · Komga + Ubooquity: beide vollständig konfiguriert
• K · Komga: nur Komga vollständig konfiguriert
• U · Ubooquity: nur Ubooquity vollständig konfiguriert
• kein Button: kein Backend vollständig konfiguriert

Bei Betätigung werden alle konfigurierten Backends aufgerufen. Sind Komga und Ubooquity eingerichtet, werden immer beide versucht – unabhängig von der aufrufenden Domain. Fällt ein Backend aus, wird das andere trotzdem gestartet und die Oberfläche meldet den Teilerfolg.

Änderungen in /etc/magbrowser.env werden erst nach einem Neustart übernommen:

sudo systemctl restart magbrowser

Bedienung

Dateien verschieben

1. Gewünschte Dateien oder Gruppen über die Checkboxen auswählen.
2. In „Mags“ mit → Archiv ins Archiv verschieben.
3. Im Archiv mit ← Mags zurück auf den Server verschieben.

Alle Zielkonflikte werden vor dem ersten Verschieben geprüft. Existiert am Ziel bereits ein gleichnamiger Eintrag, wird die gesamte Mehrfachaktion abgebrochen.

Dateien löschen und wiederherstellen

Der Papierkorb-Button rechts zeigt die Anzahl der verwalteten Einträge.

1. 🗑 anklicken.
2. Einzelne Einträge, Gruppen oder „Alle“ auswählen.
3. Wiederherstellen wählen.

MagBrowser stellt die Einträge am ursprünglichen Ort wieder her und legt fehlende Elternordner neu an. Vorhandene Dateien oder Ordner werden niemals überschrieben. Direkt danach werden alle konfigurierten Bibliotheken automatisch aktualisiert. War der Aufruf erfolgreich, wird der Bibliotheksbutton wieder ausgegraut; bei einem Fehler bleibt er zum manuellen Nachholen aktiv.

Auswahl löschen entfernt nur die markierten Papierkorb-Einträge unwiderruflich. Gesamten Papierkorb löschen entfernt dagegen alle Einträge, unabhängig von der aktuellen Auswahl. Für beide Aktionen ist eine eindeutige Sicherheitsbestätigung erforderlich.

Verzeichnisse bereinigen

Der 🧹-Button durchsucht Mags, Archiv und alle Unterordner.

• .pdf und .epub bleiben erhalten; Groß- und Kleinschreibung spielt keine Rolle.
• alle anderen Dateien werden in den wiederherstellbaren MagBrowser-Papierkorb verschoben.
• Verzeichnisse, die ausschließlich durch diese Bereinigung leer werden, werden direkt entfernt.
• bereits vorher leere Verzeichnisse bleiben erhalten.
• anschließend werden alle konfigurierten Bibliotheks-Backends aktualisiert.

Vor der Bereinigung zeigt ein Dialog die Anzahl betroffener Dateien und erläutert die Aktion.

Archiv- und Papierkorbgruppen

MagBrowser erkennt in Mags, Archiv und Papierkorb viele Magazin-Familien automatisch, beispielsweise GEO, CHIP, c’t, PC, Playboy, Mac Life und Linux. Größere Familien erhalten Untergruppen. Gruppen mit nur einem Eintrag werden nicht unnötig eingeklappt.

Reverse Proxy und /manage/

Die Anwendung akzeptiert Anfragen direkt unter / und unter /manage/. Der Reverse Proxy sollte den ursprünglichen Hostnamen weiterreichen, damit in der Kopfzeile beispielsweise kiosk.hintergasse.de Manager erscheint.

Öffentliche Zugriffe sollten ausschließlich über HTTPS erfolgen. In diesem Fall muss gesetzt sein:

AUTH_COOKIE_SECURE=true

Automatische Programmaktualisierung

Die Fußzeile zeigt die Version aus VERSION, den Git-Commit, dessen Datum und lokale Änderungen. Alle fünf Minuten wird geprüft, ob der konfigurierte Git-Upstream neue Commits enthält.

Unter Linux kann MagBrowser ein Update mit git pull --ff-only installieren und anschließend den in SYSTEMD_SERVICE genannten Dienst neu starten. Der Dienstbenutzer benötigt dafür eine eng begrenzte sudo-Freigabe für genau diesen Dienst. Lokale Änderungen oder fehlende Git-Berechtigungen können das Update verhindern.

Tests

Alle Tests starten:

python -m unittest discover -s tests -v

Die Tests verwenden temporäre Verzeichnisse und verändern keine produktiven Magazinordner.

Häufige Probleme

Der Dienst startet nicht

sudo systemctl status magbrowser --no-pager -l
sudo journalctl -u magbrowser -n 50 --no-pager

Häufige Ursachen sind fehlende AUTH_*-Variablen, unvollständig ausgelieferte neue Python-Dateien oder fehlende Dateirechte.

Die Anmeldung funktioniert, bleibt aber nicht gespeichert

Bei HTTP muss AUTH_COOKIE_SECURE=false gelten. Bei HTTPS sollte der Wert true sein.

Der Bibliotheksbutton fehlt

Mindestens ein Backend muss vollständig konfiguriert sein. Für Komga werden drei, für Ubooquity zwei Variablen benötigt. Danach den MagBrowser-Dienst neu starten.

Ubooquity antwortet mit 401

Der Fernscan ist nicht aktiviert oder der API-Schlüssel ist falsch. In Ubooquity Allow remote scan triggering using secret API key aktivieren, einen neuen Schlüssel erzeugen und die Einstellungen speichern.

Eine Wiederherstellung wird abgelehnt

Am ursprünglichen Ort existiert bereits ein gleichnamiger Eintrag. MagBrowser überschreibt grundsätzlich nichts. Den vorhandenen Eintrag zuerst manuell prüfen und umbenennen oder verschieben.

Sicherheitshinweise

• API-Schlüssel und Passwörter niemals in Git einchecken oder in Chats veröffentlichen.
• /etc/magbrowser.env mit Modus 600 schützen.
• MagBrowser nur per HTTPS oder in einem vertrauenswürdigen internen Netz bereitstellen.
• Dem Dienstbenutzer nur die wirklich benötigten Dateirechte geben.
• Vor dem endgültigen Leeren des Papierkorbs die Auswahl sorgfältig prüfen.