Papra installieren auf ZimaOS oder in Portainer

Viktor Dite, Autor des Beitrags

Von - Publiziert in Homeserver
Dipl. Informatiker und Tech-Blogger seit 2006.
Aktualisiert am


Papra ist ein modernes, webbasiertes Dokumenten-Management-System (DMS), das sich auf einfache Organisation, automatische Verarbeitung und einen sauberen Import-Workflow konzentriert. Gerade in Kombination mit einem Scanner oder Netzlaufwerk eignet sich Papra sehr gut für ein lokales Paperless-Setup auf ZimaOS oder anderen Docker-Hosts.

In dieser Anleitung zeige ich dir Schritt für Schritt, wie du Papra mit Docker über Portainer installierst, korrekt konfigurierst und den automatischen Dokumenten-Import (Ingestion) aktivierst.

papra installieren

Vorbereitung für beide Wege

Wo Papra seine Daten speichert

Papra speichert Datenbank und Dokumente in einem Ordner auf deinem Server, in dieser Anleitung /DATA/AppData/papra. Darin liegt auch der Import-Ordner ingestion, dazu weiter unten mehr.

Anlegen musst du die Ordner nicht, Docker erstellt sie beim ersten Start. Papra läuft aus Sicherheitsgründen nicht als root, sondern als Benutzer 1000. Damit Papra in die Ordner schreiben darf, setzt ein kleiner Hilfs-Container (init-perms) vor jedem Start die Rechte und beendet sich danach wieder.

Die YAML mit dem Generator erstellen

Am einfachsten lässt du dir die YAML hier zusammenstellen. Wähle den Installationsweg, trag die IP-Adresse deines Servers ein und passe bei Bedarf Port und Datenordner an.

YAML-Generator für Papra

Trag deine Werte ein, die fertige YAML erscheint darunter. Alles passiert in deinem Browser, nichts wird übertragen oder gespeichert. Den Auth Secret kannst du auch leer lassen und den Platzhalter später selbst ersetzen.

Unter diesem Port rufst du Papra später im Browser auf. Er darf auf dem Server noch nicht belegt sein.

Darin liegen Datenbank, Dokumente und der Import-Ordner ingestion. Anlegen musst du nichts, Docker erstellt die Ordner beim ersten Start und ein Hilfs-Container setzt die Rechte.

Erzeugen im Terminal: openssl rand -hex 48


Den Auth Secret erzeugst du am besten selbst im Terminal mit openssl rand -hex 48 und trägst ihn ein. Lässt du das Feld leer, steht in der YAML ein Platzhalter, den du vor dem Start ersetzen musst.

Die Docker-Compose-YAML zum Selbst-Anpassen

Lieber von Hand? Dann nimm diese YAML. Sie funktioniert für beide Wege, Portainer ignoriert den Block x-casaos am Ende einfach.

name: papra
services:
  # Hilfs-Container: gibt Papra (Benutzer 1000) einmalig die Rechte auf den Datenordner
  init-perms:
    image: alpine:3.20
    container_name: papra-init-perms
    restart: "no"
    command: ["sh", "-c", "chown -R 1000:1000 /data"]
    volumes:
      - /DATA/AppData/papra:/data

  papra:
    image: ghcr.io/papra-hq/papra:latest
    container_name: papra
    restart: unless-stopped
    depends_on:
      init-perms:
        condition: service_completed_successfully
    ports:
      - "1221:1221"
    environment:
      # ÄNDERN: eigenen Schlüssel erzeugen mit: openssl rand -hex 48
      - AUTH_SECRET=DEIN_AUTH_SECRET
      # ÄNDERN: IP-Adresse deines Servers
      - APP_BASE_URL=http://192.168.x.x:1221
      # Automatischer Import aus dem Ordner ingestion
      - INGESTION_FOLDER_IS_ENABLED=true
    volumes:
      - /DATA/AppData/papra:/app/app-data
      - /DATA/AppData/papra/ingestion:/app/ingestion
    user: "1000:1000"

# Nur für den Import in ZimaOS oder CasaOS: Kachel mit Icon und Port im Dashboard
x-casaos:
  main: papra
  author: papra-hq
  developer: papra-hq
  category: Documents
  description:
    en_us: Minimalistic document management and archiving platform.
    de_de: Schlankes Dokumenten-Management zum Selbsthosten.
  icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/papra.png
  tagline:
    en_us: Document management
    de_de: Dokumenten-Management
  title:
    en_us: Papra
  index: /
  port_map: "1221"
  scheme: http

Was du anpassen musst

  • AUTH_SECRET: Erzeuge im Terminal mit openssl rand -hex 48 einen eigenen Schlüssel und ersetze DEIN_AUTH_SECRET.
  • APP_BASE_URL: Trage die IP-Adresse deines Servers ein. Ohne die richtige Adresse laden Bilder und Skripte nicht.
  • Datenordner: Soll Papra woanders speichern, ändere /DATA/AppData/papra an allen drei Stellen.
  • Port: Ist 1221 schon belegt, ändere die erste Zahl bei ports, in der APP_BASE_URL und bei port_map.

Papra installieren über Portainer

  • Öffne Portainer auf deinem ZimaOS.
  • Gehe links im Menü auf Stacks.
  • Klicke oben rechts auf + Add stack.
  • Gib dem Stack einen Namen, z.B. papra.
  • Füge im Web-Editor deine YAML ein.
  • Klicke unten auf Deploy the stack.

Papra direkt über ZimaOS installieren (ohne Portainer)

ZimaOS bringt eine eigene, stark vereinfachte Docker-Oberfläche mit. Für viele Setups ist Portainer daher nicht zwingend notwendig. Papra lässt sich auch direkt über diese ZimaOS-Weboberfläche als benutzerdefinierte App installieren. Im App-Store von ZimaOS gibt es Papra nicht, der Import der YAML ist aber genauso schnell.

Papra installieren unter ZimaOS
Papra installieren unter ZimaOS
  • Klicke im ZimaOS Dashboard auf das Plus oben rechts über den Apps
  • Klicke dann auf Install custom App.
  • Klick dann auf Import
  • Füge deine YAML aus dem Generator (Installationsweg „ZimaOS oder CasaOS“) oder die YAML von oben ein
  • Klicke auf Submit

Jetzt prüfst Du noch bei den Ordnern (mit dem Ordner-Picker), ob das Verzeichnis wie gewünscht gesetzt ist und Du auf der gewünschten HDD installierst. Um die Rechte musst du dich nicht kümmern, das erledigt der Hilfs-Container.

Papra in ZimaOS

Nach der Installation erscheint Papra mit eigenem Icon als Kachel im Dashboard, ein Klick darauf öffnet die App.

Weiter geht es mit der Installation, egal ob über Portainer oder ZimaOS direkt.

Erster Start und Login

Nach ein paar Sekunden sollte der Container laufen. Rufe nun Papra im Browser auf:

http://DEINE-IP:1221

Du wirst begrüßt und kannst einen ersten Benutzer registrieren. Sobald du eingeloggt bist, siehst du das Dashboard.

Den automatischen Import (Ingestion) einrichten

Das ist der Teil, über den viele stolpern. Papra überwacht den Ordner /ingestion nicht direkt nach Dateien, sondern erwartet eine bestimmte Struktur.

So geht es:

Papra Organization ID
  • Logge dich in Papra ein und schau in die Adresszeile deines Browsers oder in die Einstellungen.
  • Suche deine Organization ID. Diese sieht meist so aus: org_xyz123.
  • Gehe nun zurück in deinen File Manager (oder Konsole).
  • Erstelle im Ingestion-Ordner einen Unterordner mit genau diesem Namen.
  • Der Pfad muss am Ende so in etwa aussehen: /DATA/AppData/papra/ingestion/org_xyz123/
Papra Organization Ingestion

Legst du den Ordner mit dem Dateimanager oder als root an, starte Papra danach einmal neu. Dann setzt der Hilfs-Container auch für den neuen Ordner die Rechte.

Test: Lege eine PDF-Datei in diesen neuen Unterordner org_xyz123. Nach wenigen Augenblicken sollte sie in Papra auftauchen und verarbeitet werden.

Sobald Dateien dort abgelegt werden:

  • erkennt Papra sie automatisch
  • Import & Verarbeitung starten ohne UI-Interaktion

Ideal für:

  • Scanner
  • SMB-Shares
  • automatisierte Upload-Jobs

Diesen Ordner kannst Du im Netzwerk freigeben, sodass dann bspw. Scanner automatisch dahin scannen können

Papra vs. Paperless-NGX – Kurzvergleich für die Entscheidung

Während Papra einen leichtgewichtigen, monolithischen DMS-Stack ohne separate Datenbank verfolgt, bietet Paperless-NGX ein modulares, regelbasiertes Dokumentenmanagement mit externer Datenbank und Worker-Queues, was besonders bei größeren Archiven und automatisierten Workflows Vorteile bringt.

Wenn du zu Paperless-NGX noch keine eigenen Erfahrungen hast, findest du eine ausführliche Installations- und Betriebsanleitung in meinem Artikel zu Paperless NGX

Im Folgenden findest du eine konkrete Empfehlungstabelle, die dir hilft, basierend auf Archivgröße und deiner ZimaBlade/Celeron-Hardware die richtige Entscheidung zwischen Papra und Paperless-NGX zu treffen.

Kriterium Papra Paperless-NGX
Architektur Ein Container, keine externe Datenbank Mehrere Container (DB, Worker, optional Redis)
Installation Sehr einfach, schnell produktiv Deutlich komplexer
Ressourcenbedarf Niedrig Mittel bis hoch
Automatischer Import Ja (Ordnerbasiert) Ja (Ordner + Regeln)
OCR & Automatisierung Basis Sehr umfangreich
Metadaten / Regeln Einfach Fein granular, mächtig
Skalierung Für kleine bis mittlere Archive Für große Archive & Teams
Wartungsaufwand Gering Höher
Typischer Einsatz Home-Server, Single-User, Minimal-Setup Power-User, Teams, große Dokumentenmengen
Multi-Organization Ja (nativ) Nein (nur Workarounds)

Multi-Organization als Entscheidungsfaktor

Der Multi-Organization-Ansatz von Papra ist ein echter struktureller Vorteil, insbesondere wenn du:

  • Privat + Verein trennen willst
  • mehrere Mandanten sauber isolieren möchtest
  • unterschiedliche Scanner- oder Ingestion-Pfade brauchst
  • keine zweite Instanz betreiben willst

Papra löst das konzeptionell sauber:

  • getrennte Organisationen
  • getrennte Ingestion-Ordner
  • getrennte Daten & Berechtigungen
  • ein Container, ein Stack

Paperless-NGX kennt dieses Modell nicht nativ. Vergleichbare Trennung ist dort nur möglich über:

  • mehrere Instanzen
  • separate Datenbanken
  • höheren Wartungs- und Backup-Aufwand

Papra ist die bessere Wahl, wenn mindestens eines zutrifft:

  • Privat und Verein / Ehrenamt
  • mehrere logische Dokumentenräume
  • begrenzte Hardware (Celeron, wenig RAM)
  • möglichst wenig Wartung
  • klar getrennte Scanner-Workflows

Paperless-NGX bleibt sinnvoll, wenn:

  • ein einziger großer Dokumentenbestand
  • sehr viele Automatisierungsregeln nötig sind
  • OCR-Pipelines im Vordergrund stehen
  • Multi-Organization keine Rolle spielt

Hardwareanforderungen

Auf Mini-Server-Hardware mit Celeron-CPU liefert Papra typischerweise das beste Leistungs-Verhältnis, vor allem für den Home-Server-Einsatz und bis mittlere Archivgrößen.