7.2 KiB

Raw Permalink Blame History

Paperless-NGX

Archivsystem.

Konfiguration

IP: 10.40.10.131
Port: 8000 (WebUI)
Host: NAS (Docker)
Proxy: HAProxy (OPNsense)
URL extern: paper.straso.com
URL intern (alt): http://paper.kb:8000/
Alte IP: 192.168.178.34

Config NPM

   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";

   # proxy_set_header Host $host;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Host $server_name;

   proxy_intercept_errors on;  # the most important directive, make it on;
   add_header P3P 'CP=""'; # may not be required in all setups

MCP-Anbindung (Claude Code)

Damit Claude Code strukturiert (statt per curl) mit Paperless arbeiten kann, läuft ein PaperlessMCP-Container lokal auf der Windows-Workstation. Er übersetzt MCP-Tool-Calls in REST-Aufrufe gegen paper.straso.com.

Architektur

Claude Code ──MCP/HTTP──► PaperlessMCP (127.0.0.1:5000) ──REST/HTTPS──► Paperless-ngx (paper.straso.com)
   (Windows)                 (Docker Desktop, Windows)                    (NAS, 10.40.10.131:8000)

Bewusst nicht in die NAS-Compose aufgenommen — Begründung siehe Abschnitt „Designentscheidungen".

Komponenten

Punkt	Wert
Repo	barryw/PaperlessMCP (.NET, 43 Tools, Bulk-Ops)
Image	`ghcr.io/barryw/paperlessmcp:latest`
Stack-Datei	`scripts/paperless-mcp/docker-compose.yml`
Env-Datei	`scripts/paperless-mcp/.env` (gitignored, Template: `.env.example`)
Bind-Adresse	`127.0.0.1:5000` (lokal-only, kein LAN-Exposure)
MCP-Endpoint	`http://localhost:5000/mcp`
Claude-Config	`paperless` als HTTP-MCP in `.claude/settings.json`
Tool-Prefix in Claude	`mcp__paperless__*`

Betrieb

cd D:\projects\chrka\brain\scripts\paperless-mcp

docker compose up -d              # start
docker compose ps                 # status
docker compose logs -f            # tail logs
docker compose pull && docker compose up -d   # update
docker compose down               # stop

Sicherheit

Token liegt nur in scripts/paperless-mcp/.env (gitignored, identisch zum Token in scripts/.env)
Port-Binding 127.0.0.1:5000 → kein Zugriff aus LAN/Internet, auch nicht versehentlich
Dry-Run default in PaperlessMCP: destruktive Ops (Delete, Bulk-Edit) brauchen explizit confirm=true
Tausche Token bei Bedarf in Paperless: Settings → Django Admin → Tokens, danach .env aktualisieren + docker compose restart

Designentscheidungen

Lokal statt NAS-Compose, weil:
- MCP-Server hat sehr breite Schreibrechte → soll nicht im LAN exponiert sein
- Token muss nicht auf die NAS migriert werden, bleibt im Vault-Workspace
- NAS-Update-Routine bleibt schlank (siehe unten)
- Container läuft nur wenn gebraucht, kein 24/7-Idle
HTTP statt stdio, weil PaperlessMCP nur HTTP unterstützt und Claude Code HTTP-MCPs nativ kann
Eigene .env statt scripts/.env, weil PaperlessMCP andere Variablennamen erwartet (PAPERLESS_BASE_URL, PAPERLESS_API_TOKEN)

Troubleshooting

Symptom	Check
Claude findet `paperless` nicht	Container läuft? `docker compose ps`. Claude Code neu starten.
`Connection refused` auf :5000	Docker Desktop läuft? Port-Binding stimmt? `netstat -an \| findstr 5000`
401 von paper.straso.com	Token in `.env` korrekt? Token in Paperless noch gültig?
`mcpServers`-Key nicht gefunden	`paperless`-Eintrag in `.claude/settings.json` steht auf Root-Ebene; ggf. unter `mcpServers` schieben
Image-Tag broken	In `docker-compose.yml` auf konkrete Version pinnen, siehe Releases

Update

Arbeitsverzeichnis auf der NAS: /volume1/docker/paperless

Aktuelle Version notieren — für Rollback im Fehlerfall.

Altes Backup löschen:

cd /volume1/docker
rm -r paperless_backup/

Anwendung stoppen:

cd /volume1/docker/paperless
sudo docker-compose down

Neues Backup erstellen:

cd /volume1/docker
sudo cp -r ./paperless ./paperless_backup

Container entfernen:

cd /volume1/docker/paperless
sudo docker-compose rm -f

Images aktualisieren:
```
sudo docker-compose pull
```
Anwendung starten:
```
sudo docker-compose up -d
```

DB-Server-Upgrade

Nur den DB-Container starten:

sudo docker-compose up -d db

Backup-Script:

sudo docker exec -it paperless-db-1 pg_dumpall -U paperless > $HOME/upgrade_paperless_backup.sql

Bekannte Stolperfallen

PostgreSQL 14+ Pflicht ab bestimmten Versionen: solariz.de — Paperless broken after upgrade
password authentication failed for user "paperless" — Volumes zurücksetzen (Issue #1552):
```
docker-compose up -V --remove-orphans --force-recreate
```

Updateverlauf

2025-09-26: von 2.13.5 auf 2.18.4

Archivierungsworkflow

Dokumente, die aufbewahrt werden

189er Etiketten für ASNs: bueroshop24 — Avery Zweckform L4731REV
Tool zum Generieren von Barcodes: tobiasmaier.info — ASN QR Code Label Generator

Empfohlener Workflow

Paperless-ngx Docs — Recommended Workflow

ASN-Definition

Zähler-Offset:

Offset	Person
100189	Christian
200189	Vera
300189	Vicky
400189	Justus
500189	Hetti

Beispiel: ASN200000, TAG:Vera

Dokumente exportieren

Voraussetzung: Volume für Export-Verzeichnis festlegen.

volumes:
  - /volume1/docker/paperless/data:/usr/src/paperless/data
  - /volume1/docker/paperless/media:/usr/src/paperless/media
  - /volume1/docker/paperless_export:/usr/src/paperless/export    # https://paperless.readthedocs.io/en/latest/utilities.html#the-exporter
  - /volume1/homes/chk/Drive/Paperless-Input:/usr/src/paperless/consume

Manueller Export:

sudo docker exec paperless-webserver-1 document_exporter ../export

Archiv erzeugen:

tar -czf paper_export.tgz ./paperless_export

Manueller Import:

sudo docker exec paperless-webserver-1 document_importer ../export

Quelle: YouTube — Paperless-ngx Export/Import

Backup NAS in Amazon Cloud

S3 Bucket paperbackup (Amazon Portal S3 → Buckets)

7.2 KiB Raw Permalink Blame History