Installieren¶

Was die App braucht, die drei Wege, sie zu installieren, und wie sie aktuell bleibt. Sobald sie installiert ist, verbindet Einrichten sie mit Paperless-ngx. Um sie zuerst bei der Arbeit zu sehen, ohne deine eigenen Server anzufassen, probiere die Demo aus.

In drei Minuten ausprobieren¶

Ein Befehl startet ein echtes Paperless-ngx und ein echtes Nextcloud in Docker auf deinem eigenen Rechner, mit fünf synthetischen Dokumenten, eingerichtetem Paperless Sync und dieser App, und endet mit einer Suche, die die Dokumente findet. Dein eigenes Nextcloud und Paperless bleiben unberührt:

git clone https://github.com/Dennis-Otto/paperless-unified-search.git
cd paperless-unified-search
bash demo/seed.sh

Er braucht Docker mit Compose und Bash, unter Windows Git Bash, und erzeugt die Passwörter der Demo auf deinem Rechner. Beide Weboberflächen lauschen nur auf 127.0.0.1. Sobald das Skript die Konten ausgibt, melde dich als jamie unter http://localhost:8180 an und suche nach invoice: Die Verlängerung der Hausratversicherung ist unter den Treffern, weil ihr Text „invoice“ sagt, ihr Titel aber nicht. Die Anleitung der Demo sagt, was du noch ausprobieren kannst und wie du sie wieder entfernst.

---
config:
  flowchart:
    wrappingWidth: 400
    nodeSpacing: 30
---
flowchart TB
    accTitle: Was die Demo einrichtet
    accDescr: Du startest bash demo/seed.sh. Das Skript erzeugt den geheimen Schlüssel von Paperless und die Passwörter der Demo in demo/.env und startet Paperless-ngx mit Redis und Nextcloud mit seinen Hintergrundjobs in Docker, nur auf 127.0.0.1. Paperless liest fünf synthetische Briefe ein. Paperless Sync, ein festgelegtes, signiertes Release, schreibt jeden in die Dateien des Archiv-Kontos paperless, das das Archiv nur lesend mit jamie teilt. occ paperless_unified_search:setup verbindet die App mit Paperless, mit dem API-Token über eine Pipe. Eine Suche als jamie nach invoice zeigt drei Paperless-Dokumente, und das Skript nennt die Adressen und die Konten zum Anmelden.

    run(["bash demo/seed.sh"])
    secrets["demo/.env: der geheime Schlüssel<br>und die Passwörter, erzeugt"]
    start["`Docker: **Paperless-ngx** mit Redis,<br>**Nextcloud** mit seinen Hintergrundjobs`"]
    letters["Paperless liest fünf<br>synthetische Briefe ein"]
    sync["`**Paperless Sync** schreibt sie<br>in die Dateien des<br>Archiv-Kontos paperless`"]
    share["paperless teilt das Archiv<br>nur lesend mit jamie"]
    setup["`occ **paperless_unified_search:setup**,<br>das Token über eine Pipe`"]
    found(["jamie sucht nach invoice:<br>drei Paperless-Dokumente"])

    run --> secrets --> start --> letters --> sync --> share --> setup --> found

    classDef person fill:#f59e0b2e,stroke:#f59e0b,stroke-width:2px
    classDef bot fill:#526cfe2e,stroke:#526cfe,stroke-width:2px
    classDef done fill:#16a34a2e,stroke:#16a34a,stroke-width:2px
    class run person
    class secrets,start,letters,sync,share,setup bot
    class found done

Was sie braucht¶

	Braucht
Nextcloud	33 bis 35
PHP	8.2 oder neuer, soweit die Version von Nextcloud es unterstützt
Paperless-ngx	Ein Paperless-ngx mit seiner REST-API; die Kompatibilität listet die Versionen, die die Tests abdecken
Das Netzwerk	Der Nextcloud-Server erreicht Paperless über HTTP oder HTTPS, verbindet sich innerhalb von 3 Sekunden und bekommt jede Antwort innerhalb von 10. Die Browser und die Apps der Benutzer sprechen nie mit Paperless
Ein Paperless-Konto	Eines, das die zu durchsuchenden Dokumente ansehen darf, mit einem API-Token, wie es Einrichten anlegt
Das Archiv	Jedes Dokument als Datei eines Nextcloud-Kontos, des Archiv-Kontos, mit der Kennung `[P<ID>]` im Namen, etwa die Dateien von Paperless Sync oder von jeder anderen Synchronisierung

Die App fügt der Datenbank von Nextcloud keine Tabelle hinzu, führt keinen Hintergrundjob aus und braucht keine Erweiterung von PHP über die von Nextcloud hinaus. Niemand braucht ein Konto in Paperless, um seine Dokumente zu finden: Die Freigaben von Nextcloud entscheiden, wer welches sieht.

Aus dem App Store¶

Öffne als Administrator von Nextcloud Apps, suche nach Paperless Unified Search und wähle Herunterladen und aktivieren. Der App Store führt die App unter Integration, Dateien und Suche.

occ macht dasselbe auf der Befehlszeile: app:install lädt die App aus dem App Store herunter und aktiviert sie. Führe es als Benutzer des Webservers aus, so wie es zu deiner Installation passt:

# Nextcloud on a server of its own
sudo -u www-data php /var/www/nextcloud/occ app:install paperless_unified_search
# The Docker image of Nextcloud, whose service in compose.yaml is app
docker compose exec --user www-data app php occ app:install paperless_unified_search
# Nextcloud All-in-One
sudo docker exec --user www-data nextcloud-aio-nextcloud php occ app:install paperless_unified_search
# The snap of Nextcloud
sudo nextcloud.occ app:install paperless_unified_search

Der Rest dieser Dokumentation schreibt occ für den Befehl, der davon passt.

Von Hand, aus einem signierten Release¶

Wo Nextcloud den App Store nicht erreicht, etwa hinter einer Firewall, die keine Anfrage hinauslässt, installierst du das Paket eines Releases:

Lade das Paket und seine Signatur vom neuesten Release herunter, im Browser oder mit der GitHub CLI:

gh release download --repo Dennis-Otto/paperless-unified-search \
  --pattern 'paperless_unified_search.tar.gz*'

Prüfe, bevor du es entpackst, dass das Paket das ist, das der Release-Workflow gebaut und signiert hat: seine Build-Provenienz und seine Signatur mit dem Zertifikat der App, das der Nextcloud App Store ausgestellt hat.

gh attestation verify paperless_unified_search.tar.gz --repo Dennis-Otto/paperless-unified-search
curl -fsSLO https://raw.githubusercontent.com/nextcloud/app-certificate-requests/master/paperless_unified_search/paperless_unified_search.crt
openssl x509 -in paperless_unified_search.crt -pubkey -noout > paperless_unified_search.pub
openssl dgst -sha512 -verify paperless_unified_search.pub \
  -signature paperless_unified_search.tar.gz.sig paperless_unified_search.tar.gz

Der letzte Befehl sagt Verified OK. Verify a release in der Sicherheitsrichtlinie prüft auch das Release selbst und seine SBOM.

Entpacke es in einen Ordner für Apps, in den Nextcloud schreiben darf, custom_apps im Docker-Image von Nextcloud und apps in den meisten anderen Installationen (apps_paths in der config.php nennt sie), und übergib es dem Benutzer des Webservers:
```
sudo tar -xzf paperless_unified_search.tar.gz -C /var/www/nextcloud/apps
sudo chown -R www-data:www-data /var/www/nextcloud/apps/paperless_unified_search
```

Aktiviere es:

occ app:enable paperless_unified_search

Das Paket trägt die Signatur jeder seiner Dateien, also besteht die Prüfung der Integrität seines Codes durch Nextcloud wie bei einer App aus dem App Store.

Updates¶

Nextcloud meldet seinen Administratoren eine neue Version einer App aus dem App Store; Apps → Aktualisierungen oder occ app:update paperless_unified_search installiert sie. Ein von Hand installiertes Paket wird so aktualisiert, wie es installiert wurde: herunterladen, prüfen und an der Stelle des Ordners der alten Version entpacken. Die Einstellungen bleiben, wie sie sind.

Die Änderungen sagen, was sich in jeder Version geändert hat, und die Ankündigungen in den Diskussionen oder Watch → Custom → Releases auf GitHub melden dir jedes Release.

Weiter¶

Einrichten verbindet die App mit Paperless und teilt das Archiv mit seinen Lesern.
Deinstallieren sagt, wie du die App wieder entfernst und was zurückbleibt.