Digitalregal selbst betreiben.

Voraussetzungen

Für den produktiven Betrieb benötigen Sie einen Linux-Server oder ein NAS, auf dem Docker läuft. Planen Sie Speicherplatz passend zur Dokumentenmenge ein und richten Sie regelmäßige externe Sicherungen ein.

• Docker Engine und Docker Compose v2 (docker compose); Git zum Abruf des Quellcodes.
• Mindestens 4 GB Arbeitsspeicher und 2 CPU-Kerne; ab 8 GB für umfangreiche Bestände oder lokale KI empfohlen.
• Freier Speicher für Datenbank, Suchindex und Dokumentdateien; eine SSD wird empfohlen.
• Für den Zugriff aus dem Internet: eine Domain mit DNS-Eintrag sowie erreichbare Ports 80 und 443 für HTTPS.

Installation

Die Compose-Datei startet Digitalregal mit PostgreSQL und Meilisearch. Die Migration des Datenbankschemas wird beim Start automatisch ausgeführt.

git clone https://gitlab.com/digitalregal/digitalregal.git
cd digitalregal/deploy
cp .env.example .env

Bearbeiten Sie .env vor dem Start: Ersetzen Sie alle CHANGE_ME-Werte durch drei voneinander unabhängige, starke Geheimnisse für POSTGRES_PASSWORD, MEILI_MASTER_KEY und SECRET_KEY. Die Werte müssen dauerhaft sicher aufbewahrt werden; .env gehört nicht in ein öffentliches Repository.

openssl rand -hex 32

Führen Sie den Befehl dreimal aus und verwenden Sie für jede Variable einen eigenen Wert.

docker compose up --build -d

Ohne Reverse Proxy ist die Oberfläche zunächst unter http://SERVER:8000 erreichbar. Für produktiven Internetzugriff setzen Sie DIGITALREGAL_DOMAIN in .env auf Ihren Hostnamen und starten mit dem Caddy-Profil:

docker compose --profile proxy up --build -d

Zeigen Sie die Domain per DNS auf den Server und geben Sie TCP 80/443 frei. Caddy stellt HTTPS bereit. Legen Sie das erste Instanz-Administratorkonto beim ersten Aufruf an. Status und Startfehler prüfen Sie mit docker compose ps und docker compose logs.

Konfiguration

Alle Einstellungen für den Betrieb stehen in der .env-Datei. Jede Variable ist dort kommentiert. Wichtig für den Start sind vor allem:

• → die öffentliche Adresse, unter der Digitalregal erreichbar ist
• → ein zufälliger geheimer Schlüssel für Sitzungen
• → ein SMTP-Server für Einladungen und Erinnerungen
• → ob und mit welchem Modell KI-Vorschläge erzeugt werden

Eingangskanäle

Import

Bestehende Ablagen lassen sich unter Einstellungen → Import übernehmen. Unterstützt werden ZIP-Archive mit Ordnerstruktur, ZIP-Archive mit CSV-Manifest und Backups aus paperless-ngx.

Jeder Import startet mit einem Trockenlauf. Er zeigt, wie viele Dateien übernommen werden, welche Duplikate erkannt wurden und ob Fehler auftreten. Erst danach wird tatsächlich importiert.

Sicherung

Das mitgelieferte Skript sichert einen PostgreSQL-Dump sowie die Volumes storage-hot und storage-archive. Führen Sie es im deploy-Verzeichnis aus; das Zielverzeichnis kann absolut angegeben werden:

cd /pfad/zu/digitalregal/deploy
./scripts/backup.sh /srv/backups/digitalregal

Das Skript sichert nicht die .env-Datei, das intake-Volume (Dateien, die noch auf den Import warten), Meilisearch oder optionale Dienste wie Mail-Warteschlange und Caddy-Zertifikate. Sichern Sie benötigte Konfigurationen und Zusatzdaten gesondert. Bewahren Sie .env besonders geschützt auf: SECRET_KEY und die übrigen Zugangsdaten werden für den Betrieb und verschlüsselte Einstellungen benötigt.

Lagern Sie Backups verschlüsselt und getrennt vom Server und testen Sie regelmäßig eine Wiederherstellung. Der Suchindex wird nicht mitgesichert und kann aus der Datenbank neu aufgebaut werden.

Wiederherstellen können Sie ein solches Backup mit ./scripts/restore.sh /absoluter/pfad/zum/backup. Das Skript überschreibt die Datenbank und Dokument-Volumes am Zielserver und verlangt eine Bestätigung.

Zusätzlich gibt es unter Import & Export einen fachlichen Export aller Regale als ZIP mit aktiven Dokumentdateien, JSON-Metadaten und CSV-Manifest. Bei vorhandener Arbeitskopie (zum Beispiel einem OCR-PDF) wird diese statt des Archiv-Originals exportiert. Dieser Export ersetzt kein vollständiges Server-Backup.

Verschlüsselung

Digitalregal kann alle Dateiinhalte verschlüsselt auf der Festplatte ablegen: Archiv-Originale, Arbeitskopien und Vorschaubilder. Jedes Regal erhält einen eigenen Schlüssel, sodass Bereiche kryptografisch voneinander getrennt sind. Aktiviert wird die Verschlüsselung, indem Sie in .env einen Master-Key setzen:

openssl rand -base64 32
# als DIGITALREGAL_ENCRYPTION_KEY in .env eintragen

Neu angelegte Regale werden ab dann automatisch verschlüsselt; bestehende Regale und Dateien bleiben lesbar und können schrittweise nachgerüstet werden. Das Verschieben eines Dokuments in ein anderes Regal schlüsselt es intern auf den Zielschlüssel um, ohne die Datei neu hochladen zu müssen.

• Verschlüsselt sind nur die Dateiinhalte. Titel, Metadaten, Notizen und der Suchindex bleiben lesbar, damit Suche und Filterung weiter funktionieren.
• Der Master-Key gehört wie SECRET_KEY zu den wichtigsten Geheimnissen der Instanz: Ohne ihn sind verschlüsselte Dateien unwiederbringlich verloren. Sichern Sie .env unbedingt gesondert und geschützt.
• Der Schutz richtet sich gegen entwendete Festplatten, Backups und externe Speicher. Ein kompromittierter laufender Server kann die Schlüssel im Arbeitsspeicher vorhalten und wird davon nicht abgewehrt.

Aktualisierung

Lesen Sie vor einer Aktualisierung die Hinweise zur Zielversion und erstellen Sie eine geprüfte Sicherung. Für ein festes Release tragen Sie dessen Versionsnummer (ohne v) als DIGITALREGAL_VERSION in .env ein. Danach:

docker compose pull
docker compose up -d

Bei einem lokalen Build verwenden Sie docker compose up --build -d statt pull. Compose führt den Dienst migrate vor API und Worker aus; prüfen Sie anschließend docker compose ps sowie die Protokolle von migrate, api und worker. Löschen Sie keine Volumes bei der Aktualisierung. Nach einer Schema-Migration können Sie nicht einfach zu einem älteren Image zurückkehren; im Fehlerfall stellen Sie die vorherige Sicherung wieder her.

Umzug auf einen neuen Server

1. Planen Sie ein Wartungsfenster und pausieren Sie Uploads sowie Eingangsverbindungen. Erstellen Sie auf dem alten Host mit scripts/backup.sh ein Backup und übertragen Sie es verschlüsselt auf den neuen Host.
2. Richten Sie auf dem Zielserver dieselbe Digitalregal-Version und PostgreSQL-Hauptversion (Compose verwendet PostgreSQL 17) ein. Übernehmen Sie die .env-Datei sowie benötigte Zusatzkonfigurationen. Behalten Sie insbesondere POSTGRES_PASSWORD, MEILI_MASTER_KEY, SECRET_KEY und DIGITALREGAL_INDEX_PREFIX bei; die Domain dürfen Sie anpassen.
3. Starten Sie den Compose-Stack einmal, damit Datenbank und Ziel-Volumes angelegt werden. Führen Sie dann im deploy-Verzeichnis das Restore-Skript aus; es überschreibt vorhandene Daten und fragt vorher nach:

docker compose up -d
./scripts/restore.sh /absoluter/pfad/zum/backup

Das Restore-Skript stellt PostgreSQL und die beiden Dokument-Volumes wieder her und startet API und Worker erneut. Prüfen Sie Anmeldung, Dokumente und Suche, bevor Sie den DNS-Eintrag auf den neuen Host umstellen. Ein Suchindex-Neuaufbau kann erforderlich sein. intake-Dateien und optionale Dienstedaten müssen separat übertragen werden; sie sind nicht in diesem Skript enthalten.

Von der Online-Version zum Selbstbetrieb wechseln

1. Richten Sie zunächst Ihre selbst betriebene Instanz ein. Legen Sie für jedes Regal, das Sie übernehmen möchten, ein Zielregal an und stellen Sie sicher, dass Ihr Konto dort Bearbeitungsrechte hat.
2. Melden Sie sich in Ihrer Online-Instanz an und öffnen Sie Import & Export. Wählen Sie dort ein Regal aus und klicken Sie auf Regal exportieren. Wiederholen Sie das für jedes Regal, das Sie migrieren möchten. Dafür ist kein Instanz-Admin-Konto nötig; Leserechte für das jeweilige Regal genügen.
3. Öffnen Sie Import & Export auf der neuen Instanz, wählen Sie ein ZIP aus und wählen Sie das passende Zielregal. Starten Sie zuerst den Trockenlauf, prüfen Sie Dateien, Warnungen und Duplikate und starten Sie danach den Import. Wiederholen Sie dies für die übrigen ZIP-Dateien.

Der Export enthält aktive Dokumente und unterstützte Metadaten. Wenn eine Arbeitskopie (zum Beispiel ein OCR-PDF) vorhanden ist, wird diese statt des Archiv-Originals exportiert. Benutzerkonten, Passwörter, Regalberechtigungen, Freigaben, Systemeinstellungen und der vollständige Änderungsverlauf werden nicht übertragen. Laden Sie Personen auf der neuen Instanz erneut ein, richten Sie Berechtigungen und Eingänge neu ein und prüfen Sie die importierten Dokumente, bevor Sie Ihr Online-Konto kündigen oder Daten löschen.

Hilfe

Fragen, Fehlerberichte und Wünsche gehören in die Issues auf GitLab. Kundinnen und Kunden des Unternehmenstarifs erhalten Support per E-Mail.