---
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

![image](https://docs.paperless-ngx.com/assets/logo_full_white.svg#only-dark)

### 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)