Papermerge installieren – Anleitung für Portainer & ZimaOS als native App

Viktor Dite, Autor des Beitrags

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


Ich wurde gefragt, ob ich nicht eine Anleitung für die Papermerge Installation erstellen könnte. Wer schon mal in die offizielle Dokumentation geschaut hat, weiß: Sie ist unglaublich modular. Man findet Anleitungen für die App, für den OCR-Worker, für die Datenbank – aber kaum eine funktionierende „Copy & Paste“-Lösung für ein komplettes System. Ich biete Dir hier zwei Lösungen an, einmal für die native Installation unter ZimaOS als App oder über Portainer. Du entscheidest, welche Version Du installieren willst.

Papermerge installieren
Papermerge DMS installieren

Nach einigem Basteln und Debuggen (besonders mit den Dateirechten von Apache Solr!) habe ich jetzt eine perfekt laufende Konfiguration.

Vorbereitung: Wo Papermerge seine Daten speichert

Papermerge braucht drei Speicherorte:

  1. pgdata: Für die Datenbank.
  2. media_data: Für deine PDFs und Dokumente.
  3. solr_data: Für den Suchindex.

Anlegen musst du die Ordner nicht, Docker erstellt sie beim ersten Start. Unter ZimaOS solltest du bei /DATA/AppData/papermerge bleiben, so wie in den Vorlagen unten. Apps unter /DATA/AppData/<App-Name> bekommen von ZimaOS saubere Rechte. Nutzt du ein anderes System, passe den Pfad an deine Ordnerstruktur an.

Die YAML mit dem Generator erstellen

Statt die YAML unten von Hand anzupassen, kannst du sie dir hier zusammenstellen lassen. Wähle den Installationsweg, trag Port und Datenordner ein und, wenn du magst, deine Passwörter. Das Datenbank-Passwort setzt der Generator an allen vier Stellen ein, an denen Papermerge es braucht. Die Befehle zum Anlegen der Ordner bekommst du gleich mit.

YAML-Generator für Papermerge

Trag deine Werte ein, die fertige YAML erscheint darunter. Alles passiert in deinem Browser, nichts wird übertragen oder gespeichert. Passwörter und Schlüssel kannst du auch leer lassen und die Platzhalter später selbst ersetzen.

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

Darin landen Datenbank, Dokumente und Suchindex. Unter ZimaOS am besten so lassen: Apps unter /DATA/AppData/<App-Name> bekommen saubere Rechte.

Damit meldest du dich in Papermerge an. Wähle eins, das du dir merken kannst.

Brauchst du nie zum Einloggen. Erzeugen im Terminal: openssl rand -hex 24. Erlaubt sind Buchstaben, Ziffern und . _ - ~.

Erzeugen im Terminal: openssl rand -hex 32


Die Ordner musst du nicht anlegen, Docker erstellt sie beim ersten Start. Die Rechte für den Suchindex Solr setzt der Hilfs-Container init-solr, du brauchst also kein Terminal.

Die fertige YAML nimmst du dann in Methode 1 oder Methode 2 statt der Vorlage.

Methode 1: Installation über Portainer (Empfohlen)

Das ist der sauberste Weg. Portainer bietet uns „Stacks“ (Docker Compose), bessere Logs und volle Kontrolle über das Netzwerk.

Schritt 1: Stack erstellen

  1. Öffne Portainer (auf deinem ZimaOS).
  2. Gehe links auf Stacks und klicke oben rechts auf Add stack.
  3. Nenne den Stack papermerge.
  4. Kopiere den folgenden Code in den Web-Editor.
Papermerge installieren
Papermerge in Portainer installieren

Schritt 2: Die Docker-Compose YAML (Portainer)

Hast du die YAML mit dem Generator erstellt, nimm diese und überspringe den folgenden Block.

Wichtig: Ich habe an den entsprechenden Stellen Kommentare eingefügt (# <--- ...), wo du unbedingt eigene Passwörter setzen solltest!

version: "3.8"

services:
  # Dieser Hilfs-Container repariert automatisch die Rechte für die Suchmaschine Solr
  init-solr:
    image: solr:9.7
    container_name: fix-solr-permissions
    user: root
    command: chown -R 8983:8983 /var/solr
    volumes:
      # ACHTUNG: Pfad anpassen!
      - /DATA/AppData/papermerge/solr_data:/var/solr
    networks:
      - papermerge_net

  db:
    image: postgres:16.1
    restart: unless-stopped
    environment:
      - POSTGRES_DB=pmgdb
      - POSTGRES_USER=pmg_user
      # ÄNDERN: Dein Datenbank-Passwort
      - POSTGRES_PASSWORD=Vergib_Hier_Ein_Sicheres_DB_Passwort! # <--- ÄNDERN
    volumes:
      # ACHTUNG: Pfad anpassen!
      - /DATA/AppData/papermerge/pgdata:/var/lib/postgresql/data
    healthcheck:
      # Prüft, ob die DB bereit ist, damit die App nicht zu früh startet
      test: ["CMD-SHELL", "pg_isready -U pmg_user -d pmgdb"]
      interval: 5s
      timeout: 10s
      retries: 5
      start_period: 10s
    networks:
      - papermerge_net

  redis:
    image: redis:7.2
    restart: unless-stopped
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
    networks:
      - papermerge_net

  solr:
    image: solr:9.7
    restart: unless-stopped
    command:
      - solr-precreate
      - pmg
    volumes:
      # ACHTUNG: Pfad anpassen!
      - /DATA/AppData/papermerge/solr_data:/var/solr
    depends_on:
      init-solr:
        condition: service_completed_successfully
    networks:
      - papermerge_net

  webapp:
    image: papermerge/papermerge:3.5.3
    restart: unless-stopped
    ports:
      - "12000:80" # Erreichbar unter http://server-ip:12000
    environment:
      - PAPERMERGE__AUTH__USERNAME=admin
      # ÄNDERN: Dein Login-Passwort für die Weboberfläche
      - PAPERMERGE__AUTH__PASSWORD=Vergib_Hier_Ein_Admin_Login_Passwort! # <--- ÄNDERN
      # ÄNDERN: Muss mit dem DB-Passwort oben übereinstimmen
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__MAIN__MEDIA_ROOT=/var/media/pmg
      - PAPERMERGE__OCR__DEFAULT_LANG_CODE=deu
      - PAPERMERGE__OCR__LANG_CODES=deu,eng
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
      - PAPERMERGE__SEARCH__URL=solr://solr:8983/pmg
      # ÄNDERN: Generiere einen zufälligen Key (z.B. wild auf die Tastatur hauen)
      - PAPERMERGE__SECURITY__SECRET_KEY=Hier_Muss_Ein_Langer_Zufalls_String_Hin_XyZ123 # <--- ÄNDERN
    volumes:
      # ACHTUNG: Pfad anpassen!
      - /DATA/AppData/papermerge/media_data:/var/media/pmg
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
      solr:
        condition: service_started
    networks:
      - papermerge_net

  ocr_worker:
    image: papermerge/ocrworker:0.3.1
    restart: unless-stopped
    command: worker
    environment:
      - OCR_WORKER_ARGS=-Q ocr -c 2
      # ÄNDERN: Muss mit dem DB-Passwort oben übereinstimmen
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__MAIN__MEDIA_ROOT=/var/media/pmg
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
    volumes:
      # ACHTUNG: Pfad anpassen!
      - /DATA/AppData/papermerge/media_data:/var/media/pmg
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - papermerge_net

  i3worker:
    image: papermerge/i3worker:0.3
    restart: unless-stopped
    command: worker
    environment:
      - I3_WORKER_ARGS=-Q i3 -c 2
      # ÄNDERN: Muss mit dem DB-Passwort oben übereinstimmen
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
      - PAPERMERGE__SEARCH__URL=solr://solr:8983/pmg
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
      solr:
        condition: service_started
    networks:
      - papermerge_net

networks:
  papermerge_net:
    driver: bridge

Troubleshooting: „Permission Denied“ bei Solr

Das häufigste Problem bei der Installation ist der Suchindex Solr. Er startet, stürzt ab und startet neu (Bootloop). Der Grund: Solr läuft intern als Benutzer 8983, aber die Ordner auf dem ZimaOS gehören oft root.

In beiden Konfigurationen, für Portainer und für ZimaOS, habe ich dafür den Dienst init-solr eingebaut. Das ist ein winziger „Wegwerf-Container“, der kurz vor dem eigentlichen Start hochfährt, die Rechte des Ordners /DATA/AppData/papermerge/solr_data repariert (chown 8983) und sich dann sofort wieder beendet (Exit 0).

Das ist viel eleganter, als manuell im Terminal mit chown hantieren zu müssen!

Schritt 3: Starten

Klicke auf Deploy the stack. Portainer lädt jetzt alle Images herunter. Das erste Hochfahren dauert etwas, besonders bis die Datenbank den „Healthy“-Status meldet.

App aufrufen

Nach der fertigen Installation lässt sich die App unter http://DEINE-IP:12000 aufrufen.

Methode 2: ZimaOS Custom App (Nativ)

Wer Portainer nicht nutzen möchte, kann die App auch direkt über die ZimaOS-Oberfläche importieren.

Achtung: Hier ist es extrem wichtig, dass wir unten in der YAML ein eigenes Netzwerk definieren (networks:), sonst finden sich die Container (Datenbank, Solr, Webapp) gegenseitig nicht, da ZimaOS Apps standardmäßig isoliert.

Papermerge installieren unter ZimaOS
Papermerge 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 die YAML aus dem Generator ein (Installationsweg „ZimaOS Custom App“) oder nimm die folgende und passe die markierten Stellen an:
name: papermerge
services:
  # Dieser Hilfs-Container repariert automatisch die Rechte für die Suchmaschine Solr
  init-solr:
    image: solr:9.7
    container_name: fix-solr-permissions
    restart: "no"
    user: root
    command: chown -R 8983:8983 /var/solr
    volumes:
      - /DATA/AppData/papermerge/solr_data:/var/solr
    networks:
      - papermerge_net

  db:
    image: postgres:16.1
    environment:
      - POSTGRES_DB=pmgdb
      - POSTGRES_USER=pmg_user
      - POSTGRES_PASSWORD=Vergib_Hier_Ein_Sicheres_DB_Passwort! # <--- ÄNDERN
    volumes:
      - /DATA/AppData/papermerge/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pmg_user -d pmgdb"]
      interval: 5s
      timeout: 10s
    networks:
      - papermerge_net

  redis:
    image: redis:7.2
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
    networks:
      - papermerge_net

  solr:
    image: solr:9.7
    command:
      - solr-precreate
      - pmg
    volumes:
      - /DATA/AppData/papermerge/solr_data:/var/solr
    depends_on:
      init-solr:
        condition: service_completed_successfully
    networks:
      - papermerge_net

  webapp:
    image: papermerge/papermerge:3.5.3
    ports:
      - "12000:80"
    environment:
      - PAPERMERGE__AUTH__USERNAME=admin
      - PAPERMERGE__AUTH__PASSWORD=Vergib_Hier_Ein_Admin_Login_Passwort! # <--- ÄNDERN
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__MAIN__MEDIA_ROOT=/var/media/pmg
      - PAPERMERGE__OCR__DEFAULT_LANG_CODE=deu
      - PAPERMERGE__OCR__LANG_CODES=deu,eng
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
      - PAPERMERGE__SEARCH__URL=solr://solr:8983/pmg
      - PAPERMERGE__SECURITY__SECRET_KEY=Hier_Muss_Ein_Langer_Zufalls_String_Hin_XyZ123 # <--- ÄNDERN
    volumes:
      - /DATA/AppData/papermerge/media_data:/var/media/pmg
    depends_on:
      db:
        condition: service_healthy
    networks:
      - papermerge_net

  ocr_worker:
    image: papermerge/ocrworker:0.3.1
    command: worker
    environment:
      - OCR_WORKER_ARGS=-Q ocr -c 2
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__MAIN__MEDIA_ROOT=/var/media/pmg
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
    volumes:
      - /DATA/AppData/papermerge/media_data:/var/media/pmg
    networks:
      - papermerge_net

  i3worker:
    image: papermerge/i3worker:0.3
    command: worker
    environment:
      - I3_WORKER_ARGS=-Q i3 -c 2
      - PAPERMERGE__DATABASE__URL=postgresql://pmg_user:Vergib_Hier_Ein_Sicheres_DB_Passwort!@db:5432/pmgdb # <--- ÄNDERN
      - PAPERMERGE__REDIS__URL=redis://redis:6379/0
      - PAPERMERGE__SEARCH__URL=solr://solr:8983/pmg
    networks:
      - papermerge_net

networks:
  papermerge_net:
    driver: bridge

x-casaos:
  main: webapp
  author: self
  icon: https://icon.casaos.io/main/all/papermerge.png
  title:
    en_us: Papermerge DMS
  index: /
  port_map: "12000"
  scheme: http

Viel Erfolg bei der Installation!