232 lines
7.2 KiB
Markdown
232 lines
7.2 KiB
Markdown
---
|
|
tags:
|
|
- server
|
|
- paperless
|
|
- dms
|
|
- heimnetz
|
|
---
|
|
|
|
# Paperless-NGX
|
|
|
|
Archivsystem.
|
|
|
|
## Konfiguration
|
|
|
|
- **IP:** 10.40.10.131
|
|
- **Port:** 8000 (WebUI)
|
|
- **Host:** NAS (Docker)
|
|
- **Proxy:** HAProxy (OPNsense)
|
|
- **URL extern:** [paper.straso.com](https://paper.straso.com/)
|
|
- **URL intern (alt):** [http://paper.kb:8000/](http://paper.kb:8000/)
|
|
- **Alte IP:** 192.168.178.34
|
|
|
|
|
|
|
|
### Config NPM
|
|
|
|
```yaml
|
|
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](https://github.com/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
|
|
|
|
```bash
|
|
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](https://github.com/barryw/PaperlessMCP/releases) |
|
|
|
|
# Update
|
|
|
|
Arbeitsverzeichnis auf der NAS: `/volume1/docker/paperless`
|
|
|
|
1. **Aktuelle Version notieren** — für Rollback im Fehlerfall.
|
|
|
|
2. **Altes Backup löschen:**
|
|
```bash
|
|
cd /volume1/docker
|
|
rm -r paperless_backup/
|
|
```
|
|
|
|
3. **Anwendung stoppen:**
|
|
```bash
|
|
cd /volume1/docker/paperless
|
|
sudo docker-compose down
|
|
```
|
|
|
|
4. **Neues Backup erstellen:**
|
|
```bash
|
|
cd /volume1/docker
|
|
sudo cp -r ./paperless ./paperless_backup
|
|
```
|
|
|
|
5. **Container entfernen:**
|
|
```bash
|
|
cd /volume1/docker/paperless
|
|
sudo docker-compose rm -f
|
|
```
|
|
|
|
6. **Images aktualisieren:**
|
|
```bash
|
|
sudo docker-compose pull
|
|
```
|
|
|
|
7. **Anwendung starten:**
|
|
```bash
|
|
sudo docker-compose up -d
|
|
```
|
|
|
|
## DB-Server-Upgrade
|
|
|
|
Nur den DB-Container starten:
|
|
|
|
```bash
|
|
sudo docker-compose up -d db
|
|
```
|
|
|
|
Backup-Script:
|
|
|
|
```bash
|
|
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](https://solariz.de/posts/25/paperless-broken-after-upgrade-postgress/#paperless-ngx-postgresql-14-or-later-is-required-error)
|
|
- **`password authentication failed for user "paperless"`** — Volumes zurücksetzen ([Issue #1552](https://github.com/jonaswinkler/paperless-ng/issues/1552)):
|
|
```bash
|
|
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](https://docs.paperless-ngx.com/advanced_usage/#archive-serial-number-assignment): [bueroshop24 — Avery Zweckform L4731REV](https://www.bueroshop24.de/5670-avery-zweckform-etiketten-l4731rev-25-wei%C3%9F-25-4-x-10-0-mm-345520?mkz=724)
|
|
- Tool zum Generieren von Barcodes: [tobiasmaier.info — ASN QR Code Label Generator](https://tobiasmaier.info/asn-qr-code-label-generator/)
|
|
|
|
## Empfohlener Workflow
|
|
|
|
[Paperless-ngx Docs — Recommended Workflow](https://docs.paperless-ngx.com/usage/#usage-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.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
sudo docker exec paperless-webserver-1 document_exporter ../export
|
|
```
|
|
|
|
Archiv erzeugen:
|
|
|
|
```bash
|
|
tar -czf paper_export.tgz ./paperless_export
|
|
```
|
|
|
|
Manueller Import:
|
|
|
|
```bash
|
|
sudo docker exec paperless-webserver-1 document_importer ../export
|
|
```
|
|
|
|
Quelle: [YouTube — Paperless-ngx Export/Import](https://www.youtube.com/watch?v=F-NtIbxF6oc)
|
|
|
|
# Backup NAS in Amazon Cloud
|
|
|
|
- [S3 Bucket `paperbackup`](https://s3.console.aws.amazon.com/s3/buckets/paperbackup?region=eu-west-1&tab=objects) (Amazon Portal S3 → Buckets)
|