Einrichtung und Betrieb

Wie du Ablago installierst – auf Synology, UGREEN, QNAP, TrueNAS, Unraid, umbrelOS, ZimaOS, CasaOS oder jedem Server mit Docker –, steht im eigenen Bereich Wie komme ich an ein DMS?. Diese Seite beschreibt, was danach kommt: den Einrichtungsassistenten, die Anbindung an die Datenbank, Ordner, Einstellungen und den Betrieb hinter einem Reverse-Proxy.

Einen Bereich nicht in der Leiste gefunden?

Manche Bereiche der Werkbank, zum Beispiel Wartungsmodus, Datenbank-Anbindung oder Wartungsoperationen, sind in der Vorlage Haushalt ausgeblendet. Unten in der Leiste steht, wie viele Bereiche ausgeblendet sind; ein Klick zeigt sie. Dauerhaft einblenden kannst du sie unter Werkbank anpassen. Ausgeblendet heißt nicht abgeschaltet.

Ablago läuft – empfohlen – als zwei Container: die Anwendung (ghcr.io/motom001/dms) und PostgreSQL (postgres:17). Alternativ gibt es ghcr.io/motom001/dms-komplett, in dem beides in einem Container läuft (Gegenüberstellung unter Ein oder zwei Container?). Bei jedem Push auf main baut GitHub Actions beide Images neu (Tag main, zusätzlich je Commit ein Kurz-Hash und je Release die Versionsnummer).

Erst einrichten, dann freigeben

Mach Ablago erst über einen Reverse-Proxy oder Port-Freigabe erreichbar, wenn die Einrichtung abgeschlossen ist. Der Einrichtungscode schützt zwar davor, dass ein Fremder sie übernimmt – sicherer ist es trotzdem.

Der Einrichtungsassistent

Beim ersten Aufruf führt ein Assistent in zehn Schritten durch die Einrichtung. Jeder Schritt hat oben ein ?, das genau den passenden Abschnitt hier öffnet. Übersprungenes lässt sich in der Werkbank nachholen; die Übersicht erinnert daran.

Einrichtungscode

Damit niemand sonst im Netz Ablago einrichtet, fragt es zuerst nach einem Code wie K7PX-3MNA-Q9TR. Er steht an zwei Stellen:

• im Protokoll des Containers – in der Docker-Oberfläche des NAS den Container app des Projekts öffnen und das Protokoll ansehen (bei UGREEN Docker → Container → dms-app → Protokoll, bei Synology Container Manager → Container → Details → Protokoll) oder docker compose logs app (bei dms-komplett: docker compose logs dms). Gesucht ist die Zeile Einrichtungscode für Ablago: XXXX-XXXX-XXXX;
• in der Datei EINRICHTUNGSCODE im Ordner geheim (in der Vorlage /volume1/docker/dms/geheim).

Wo genau das bei deinem Gerät ist, zeigt die Anleitung deiner Plattform unter Wie komme ich an ein DMS? – für Synology, UGREEN, QNAP, Unraid, TrueNAS, umbrelOS, ZimaOS, CasaOS und andere.

Nach dem Anlegen des Administrators ist der Code wertlos; Ablago löscht die Datei. Nach zehn falschen Versuchen sperrt es die Eingabe für zehn Minuten.

Datenbank

Server (in der Vorlage db), Port 5432, Datenbank und Benutzer dms und das Passwort aus der .env. Verbindung prüfen meldet verständlich, was nicht stimmt – Server nicht erreichbar, Passwort falsch, Datenbank fehlt (mit Knopf zum Anlegen, wenn der Benutzer das darf). Übernehmen und weiter speichert die Anbindung und startet Ablago – ohne Neustart des Containers; die Tabellen legt es selbst an. Der Schritt entfällt, wenn eine Anbindung schon funktioniert (siehe Datenbank-Anbindung).

Neu einrichten oder wiederherstellen

Bei einer leeren Datenbank fragt Ablago, ob du neu anfängst oder eine Sicherung zurückholst. Wiederherstellen führt in den Ablauf unter Wiederherstellen und endet bei der Anmeldung mit den bisherigen Zugangsdaten.

Haushalt

Der Name von Ablago, meist der Name der Familie („Familie Mustermann“) oder der Firma. Er erscheint als Schriftzug in der Kopfzeile, im Browser-Tab und auf der Anmeldeseite (änderbar unter Werkbank → Designs).

Administrator

Name, E-Mail-Adresse und Passwort des Administrators. Danach bist du als Administrator angemeldet.

Erster Benutzer

Administratoren richten ein, arbeiten aber nicht in der Ablage. Lege deshalb einen normalen Benutzer an – zum Beispiel dich selbst mit einer zweiten Adresse. Ohne E-Mail-Versand zeigt der Assistent den Einladungslink zum Kopieren.

Schlüssel und Notfallblatt

Der Schlüssel verschlüsselt gespeicherte Passwörter und alle Sicherungen (siehe Verschlüsselung); das Notfallblatt enthält ihn zum Ausdrucken. Druck es aus und leg es zu deinen wichtigen Unterlagen – ohne Schlüssel lässt sich keine Sicherung zurückholen.

Pakete dazuholen

Erst in diesem Schritt fragt Ablago den offiziellen Paketkatalog ab – vorher baut es keine Verbindung dafür auf. Die Liste zeigt je Paket Name, Beschreibung und was es anlegt; Pakete mit Code tragen „mit Code“.

• Texterkennung ist vorausgewählt – ohne sie werden gescannte Dokumente nicht durchsuchbar. Darunter fragt Weitere Sprachen? nach Zusatzsprachen (Deutsch und Englisch sind immer dabei). Alles andere kreuzt du an.
• Abhängigkeiten kommen mit, z. B. „Basis“ für „Haushalt“; sie sind mit „kommt mit – gebraucht von …“ markiert.
• Weiter führt zu einer Seite mit allen Fragen: die Rechte aller Pakete mit Code (ein Haken für alle), Namen nur bei Konflikten, Beispiel-Mappen und Pflicht-Einstellungen – dann ein Knopf. Siehe Mehrere Pakete in einem Schritt installieren.
• Überspringen geht jederzeit; Pakete holst du später unter Werkbank → Pakete.

Ist der Katalog nicht erreichbar (kein Internet), sagt der Schritt das deutlich: Es fehlen dann die Pakete, etwa die Texterkennung. Dann lädst du hier eine Sammeldatei hoch, die du an einem anderen Gerät auf der Katalog-Webseite zusammengestellt hast (siehe Pakete ohne Internet installieren) – oder du überspringst den Schritt und holst die Pakete später nach.

Optionales

Adresse von Ablago (vorbelegt mit der Adresse im Browser), Bundesland für Feiertage, Beispiel-Mappentypen und der E-Mail-Versand. Alles lässt sich auch später in der Werkbank einstellen.

Fertig

Mit Links zu beiden Handbüchern, „Problem melden“ als vorbereitetes GitHub-Issue und dem Hinweis auf GitHub Sponsors.

Danach: unter Werkbank → Sicherung den Zeitplan einschalten, eigene Mappentypen anlegen und weitere Benutzer einladen.

Datenbank-Anbindung

Die Anbindung an PostgreSQL steht in der Datei datenbank.json im Ordner /data/geheim (nur für den Container lesbar, mit Passwort). Sie ist führend:

• Gibt es die Datei, nimmt Ablago sie – auch wenn in der Compose-Datei DATABASE_URL gesetzt ist. Weicht die Variable ab, weist die Werkbank-Übersicht darauf hin; sie wird ignoriert und kann entfernt werden.
• Gibt es sie nicht, aber DATABASE_URL (bisherige Installationen), prüft Ablago die Variable beim Start und übernimmt sie in die Datei. Danach ist die Variable überflüssig.
• Gibt es sie nicht, aber DMS_DB_PASSWORT (Vorlagen für Synology, UGREEN, QNAP, TrueNAS, Unraid), nimmt Ablago die Standard-Anbindung – Server db (oder DMS_DB_HOST), Port 5432, Datenbank und Benutzer dms – mit diesem Passwort und übernimmt sie ebenso. Das Passwort steht so nur einmal in der Compose-Datei, ohne Sonderzeichen für eine URL maskieren zu müssen.
• Gibt es beides nicht – oder klappt die Verbindung nicht –, startet Ablago im Einrichtungsmodus: Es liefert nur den Assistenten aus und fragt die Anbindung ab (mit Einrichtungscode). Alle anderen Schnittstellen antworten bis dahin mit 503. Eine gespeicherte Anbindung, deren Datenbank nur noch nicht erreichbar ist (der Datenbank-Container startet noch), versucht es alle zehn Sekunden weiter.

Unter Werkbank → Datenbank-Anbindung siehst und änderst du die Anbindung. Im Abschnitt Verbindung steht, womit Ablago gerade verbunden ist („Aktuell verbunden: dms@postgres:5432/dms · in Betrieb“). Ändern: erst Verbindung prüfen, dann Übernehmen. Die neue Anbindung gilt nach einem Neustart (Jetzt neu starten – im Container startet Docker Ablago gleich wieder). Die Daten wandern dabei nicht mit; für einen Umzug in eine andere Datenbank nimm eine Sicherung.

In der Datei steht auch die interne Id des Haushalts (früher die Umgebungsvariable HAUSHALT_ID). Bisherige Installationen übernehmen sie beim ersten Start; die Variable kann danach entfernt werden.

Unter der Verbindung zeigt die Seite, wie es der Datenbank im Betrieb geht: die langen Datenbankzugriffe und was gerade läuft. Früher stand das unter Wartung und Fehlersuche → Datenbank; alte Links und Lesezeichen führen hierher.

Lange Datenbankzugriffe

Jeder Datenbankzugriff wird gestoppt. Was länger dauert als eine Schwelle, landet in der Liste und als Warnung im Protokoll (Modul datenbank). Direkt über der Liste stellst du ein:

• Lang ab – die Schwelle in Millisekunden (Standard 500),
• Aufbewahren – wie viele Tage die Einträge bleiben (Standard 30).

Die Liste zeigt die neuesten oben, etwa zehn Einträge; darin scrollst du. Ein Klick auf einen Eintrag klappt ihn auf: Abfrage, Aufrufer (Anfrage und Benutzer), Dauer und Zeit. Ein Datenbankzugriff ist eine Methode der Datenzugriffsschicht (z. B. mappen.seite für eine Seite einer Ansicht) und kann mehrere SQL-Anweisungen umfassen.

Was läuft gerade

Die Abfragen, die gerade in der Datenbank laufen, mit Dauer, Zustand und Prozess – alle fünf Sekunden aktualisiert. Laufen welche schon länger als die Schwelle, weist ein Hinweis darauf hin.

E-Mail und Adresse

Unter Werkbank → E-Mail und Adresse stellst du ein, was früher Umgebungsvariablen waren. Änderungen gelten sofort, ohne Neustart.

• Adresse von Ablago – unter dieser Adresse öffnen die Benutzer Ablago, z. B. http://nas.local:8080 oder https://dms.example.org. Sie steht in den Links der E-Mails. Solange keine gepflegt ist, nimmt Ablago die Adresse, unter der es gerade aufgerufen wird; Diese Adresse übernehmen speichert sie. Beginnt sie mit https://, gilt die Anmeldung nur noch über HTTPS.
• E-Mail-Versand – Server, Verbindungsart (STARTTLS, meist Port 587; SSL/TLS, meist 465; unverschlüsselt nur im Heimnetz), Benutzer, Passwort und Absender. Verbindung prüfen meldet sich am Server an, ohne etwas zu senden; Testmail senden schickt eine Mail an eine Adresse deiner Wahl – beides mit den Werten im Formular, auch bevor du speicherst. Schlägt etwas fehl, steht die Meldung des Mailservers darunter.
• Selbstsigniertes Zertifikat erlauben – nur für einen eigenen Mailserver im Heimnetz.
• Der Absender ist auch der Absender, wenn Benutzer eine Mappe per E-Mail versenden. Ablago trägt dabei die Adresse des Benutzers als Antworten an ein – so kommen Antworten bei ihm an, ohne dass Ablago fremde Absender vortäuscht (das würden viele Empfänger als Spam einstufen). Dieselbe Einstellung braucht die tägliche Zusammenfassung der Aufgaben.
• Ohne E-Mail-Versand (Haken „E-Mails verschicken“ aus) zeigt die Benutzerverwaltung die Einladungs- und Passwort-Links zum Kopieren an; „Passwort vergessen“ setzt dann der Administrator zurück.

Passwort verschlüsselt

Das SMTP-Passwort speichert Ablago verschlüsselt; den Schlüssel dazu erzeugst du einmal unter Werkbank → Verschlüsselung. Solange es keinen gibt, lässt sich kein Passwort speichern. Das Passwort wird nie an die Oberfläche zurückgegeben. Nimm trotzdem am besten ein eigenes Passwort nur für den Versand, etwa ein App-Passwort deines Mailanbieters.

Von einer älteren Version

Bis Version 0.8 waren das die Umgebungsvariablen APP_URL und SMTP_*. Beim ersten Start von 0.9 übernimmt Ablago ihre Werte einmalig in die Werkbank; danach werden sie ignoriert, und das Protokoll weist darauf hin, dass sie aus der Compose-Datei entfernt werden können.

Ordner und Volumes

Die Ordner im Container sind fest. Wohin sie auf dem NAS zeigen, bestimmst du allein über die Volumes der Compose-Datei – dafür gibt es keine Umgebungsvariablen.

Ordner im Container	Inhalt	Volume in der Vorlage
/data/files	hochgeladene Dokumente, Logos, Bilder gemeldeter Fehler	/volume1/docker/dms/files
/data/geheim	Schlüssel für gespeicherte Passwörter (dms.schluessel), Datenbank-Anbindung (datenbank.json), Einrichtungscode (EINRICHTUNGSCODE, nur bis zur Einrichtung), RESCUE-Datei	/volume1/docker/dms/geheim
/data/sicherung	Sicherungen, verschlüsselt	/volume1/docker/dms/sicherung
/eingang (optional)	Eingangsordner für Scanner und NAS	/volume1/docker/dms/eingang

Jeder der drei Ordner unter /data muss ein eigenes Volume sein; sonst ist sein Inhalt weg, sobald der Container neu erstellt wird (z. B. beim Update). Die Datenbank liegt im Volume des PostgreSQL-Containers – beim Image dms-komplett im vierten Ordner /data/postgres. Wie viel Platz in jedem Ordner frei ist, zeigen Werkbank → Systemzustand und Werkbank → Technik.

    volumes:
      - /volume1/docker/dms/files:/data/files
      - /volume1/docker/dms/geheim:/data/geheim
      - /volume1/docker/dms/sicherung:/data/sicherung

Von einer älteren Version (bis 0.22)

Früher legten FILES_DIR, DMS_SCHLUESSEL_DATEI und DMS_SICHERUNG_DIR die Ordner fest. Steht eine davon noch mit dem festen Wert in der Compose-Datei (z. B. FILES_DIR: /data/files), läuft alles weiter; das Protokoll und die Werkbank-Übersicht weisen darauf hin, dass du sie entfernen kannst. Zeigt sie auf einen anderen Ordner, startet Ablago nicht – sonst sähe es plötzlich einen leeren Dateiordner. Die Meldung im Protokoll des Containers nennt dann, welches Volume stattdessen auf den festen Ordner zeigen muss. Siehe Aktualisieren.

Einstellungen

Diese Einstellungen sind Umgebungsvariablen im Compose-Projekt:

Variable	Bedeutung
DATABASE_URL	Nur noch für den Umstieg: wird beim ersten Start in die Datenbank-Anbindung übernommen und danach ignoriert
DMS_DB_PASSWORT, DMS_DB_HOST, DMS_DB_PORT	Statt DATABASE_URL: Passwort (sowie Server, Standard db, und Port, Standard 5432) der Standard-Anbindung; ebenfalls nur für den ersten Start
DMS_EINRICHTUNGSCODE	aus: Einrichtungsassistent ohne Code – für App-Stores, in denen das Container-Protokoll nicht ohne Kommandozeile lesbar ist. Bis der Administrator angelegt ist, kann dann jeder im Netz die Einrichtung übernehmen
TRUST_PROXY	Wem Ablago die Angaben eines Reverse-Proxys glaubt. Nicht gesetzt oder auto: dem eigenen Rechner und privaten Netzen – passt fast immer. false: niemandem, true: allen, oder eine Liste wie 172.18.0.0/16. Siehe Hinter einem Reverse-Proxy
DMS_EINBETTEN	Seiten, die Ablago einbetten dürfen (z. B. ein Dashboard), etwa https://ha.example.org http://nas:8123. Nicht gesetzt: nur Ablago selbst. Siehe Sicherheits-Header
LOG_LEVEL	Grundstufe des Protokolls: debug, info (Standard), warn, error
PORT, HOST	Port (Standard 3000) und Adresse (Standard 0.0.0.0, alle), auf denen Ablago im Container lauscht. Normalerweise änderst du nicht PORT, sondern den Port nach außen in der Compose-Datei (in der Vorlage 8080:3000, z. B. 8090:3000). Die eingebaute Gesundheitsprüfung des Images folgt PORT; setzt du HOST auf eine einzelne Adresse, muss sie 127.0.0.1 mit einschließen, sonst gilt der Container als unhealthy
DMS_DB_VERBINDUNGEN	Höchstzahl der Verbindungen zur Datenbank, 2–100 (Vorgabe 10). Nur für größere Installationen mit mehr Kernen, siehe Technik → Viele gleichzeitige Anfragen
DMS_MAX_ANFRAGEN	Ab so vielen gleichzeitigen Anfragen antwortet Ablago sofort mit „gerade sehr beschäftigt“ (HTTP 503), 20–10.000 (Vorgabe 250), siehe Technik
DMS_ARBEITER	Zahl der Arbeiter für PDF und Exporte, 1–16. Nicht gesetzt: die Hälfte der Kerne des Containers, mindestens 1, höchstens 4. 0 schaltet sie aus (nur zur Fehlersuche)
DMS_EINGANG	Nur für Sonderfälle: anderer Ort des Eingangsordners im Container (Standard /eingang). Üblich ist, den Ordner des NAS auf /eingang einzubinden

Hinter einem Reverse-Proxy

Läuft Ablago hinter einem Reverse-Proxy (Nginx Proxy Manager, nginx, Caddy, Traefik, der Proxy deines NAS …), ist nur eines zu tun: In der Werkbank unter E-Mail und Adresse die öffentliche Adresse eintragen, z. B. https://dms.example.org. Beginnt sie mit https://, setzt Ablago das Sitzungs-Cookie nur noch über HTTPS, und Links in E-Mails führen auf diese Adresse.

HTTPS und Zertifikate

Ablago spricht selbst nur HTTP und verwaltet keine Zertifikate. Das übernimmt der Reverse-Proxy: Er nimmt die HTTPS-Verbindung an, kümmert sich um das Zertifikat und dessen Erneuerung und reicht die Anfrage an Ablago weiter. Übliche Wege:

• Nginx Proxy Manager als zusätzlicher Container: Zertifikat von Let's Encrypt per Mausklick. So läuft es beim Entwickler, siehe Beispielaufbau.
• Der Proxy deines NAS: Synology, UGREEN und QNAP bringen einen Reverse-Proxy samt Let's-Encrypt-Zertifikaten mit.
• Caddy: holt und erneuert Zertifikate von selbst, die Konfiguration ist wenige Zeilen lang.

Für Let's Encrypt braucht es eine eigene Domain, die auf deinen Anschluss zeigt. Soll Ablago nur zu Hause erreichbar sein, reicht HTTP im Heimnetz.

Nutzt ihr das WebDAV-Laufwerk, braucht es HTTPS auch zu Hause (Windows verlangt es), und der Proxy muss die WebDAV-Methoden wie PROPFIND und LOCK durchlassen – siehe Hinter einem Reverse-Proxy.

Was der Proxy Ablago mitteilt

Der Proxy leitet jede Anfrage an Ablago weiter. Für Ablago sieht sie deshalb so aus, als käme sie vom Proxy. Was das Gerät dahinter ist, schreibt der Proxy in Zusatzangaben (X-Forwarded-For, X-Forwarded-Proto). Ablago braucht sie für:

Wofür	Mit den Angaben des Proxys	Ohne sie
IP-Adressen im Protokoll und bei den Sitzungen eines Benutzers	die Adresse des Handys oder Laptops	immer die Adresse des Proxys
Sperre nach falschen Passwörtern (Anmeldeschutz, je E-Mail-Adresse und IP sowie je IP)	trifft nur das Gerät, von dem die Fehlversuche kamen	trifft alle Geräte: Fehlversuche von außen sperren die Anmeldung auch zu Hause
HTTPS erkennen, solange keine Adresse gepflegt ist	Cookie nur über HTTPS, Links mit https://	Cookie auch über HTTP, Links mit der internen http://-Adresse

Seit Version 0.43.0 nimmt Ablago diese Angaben von selbst an, wenn der Proxy im eigenen Rechner oder in einem privaten Netz sitzt (127.0.0.1, 10.x.x.x, 172.16–31.x.x, 192.168.x.x und die entsprechenden IPv6-Netze). Das trifft auf einen Proxy-Container neben Ablago und auf den Proxy eines NAS praktisch immer zu. Anfragen direkt aus dem Internet können so keine fremde IP und kein HTTPS vortäuschen. Unter Einstellungen → Technik steht bei TRUST_PROXY, was gerade gilt.

Wann TRUST_PROXY doch setzen?

• TRUST_PROXY: "false": Wenn du ganz ausschließen willst, dass ein Gerät in deinem Heimnetz, das Ablago direkt über Port 8080 erreicht, eine andere IP-Adresse vortäuscht. Die IP-Adressen und die Sperre verhalten sich dann wie in der rechten Spalte oben.
• Eine Liste, z. B. TRUST_PROXY: "172.18.0.5": Nur genau diesem Proxy glauben.
• TRUST_PROXY: "true": Wenn der Proxy eine öffentliche Adresse hat, etwa ein Tunnel- oder Cloud-Dienst, der direkt ans Ablago weiterleitet. Dann darf Ablago selbst nicht aus dem Internet erreichbar sein.

Vor Version 0.43.0 war false der Standard. Wer TRUST_PROXY: "true" schon gesetzt hat, kann es stehen lassen oder entfernen.

Die Adresse trotzdem pflegen

Die Adresse in der Werkbank ist verlässlicher als jede Erkennung: E-Mails aus dem Hintergrund (Erinnerungen, Zusammenfassung) haben keine Anfrage, aus der Ablago die Adresse ablesen könnte.

Sicherheits-Header

Ablago setzt die üblichen Sicherheits-Header selbst – dein Reverse-Proxy muss sie nicht noch einmal setzen (doppelte Header schaden nicht, verwirren aber bei der Fehlersuche):

• X-Frame-Options: SAMEORIGIN und Content-Security-Policy: frame-ancestors 'self' – keine fremde Seite kann Ablago unsichtbar einbetten,
• eine strenge Content-Security-Policy für die Oberfläche (nur eigene Skripte),
• X-Content-Type-Options: nosniff, Referrer-Policy: same-origin, Permissions-Policy,
• Strict-Transport-Security, sobald Ablago über HTTPS aufgerufen wird.

Soll Ablago in einer anderen Seite erscheinen, etwa in einem Home-Assistant-Dashboard, trage deren Ursprung in DMS_EINBETTEN ein (mehrere durch Leerzeichen getrennt). Ungültige Angaben ignoriert Ablago und nennt sie im Protokoll.

Ein Beispiel für nginx:

server {
    listen 443 ssl;
    server_name dms.example.org;
    # ssl_certificate …; ssl_certificate_key …;

    client_max_body_size 110m;          # Dokumente bis 100 MB

    location / {
        proxy_pass http://<NAS>:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

Lange Arbeiten wie das Erzeugen tausender Demo-Mappen laufen im Hintergrund, damit der Proxy nicht wegen einer Zeitüberschreitung abbricht. Die Live-Anzeige des Protokolls fragt alle zwei Sekunden nach und braucht keine besondere Proxy-Einstellung.