Hilfe & Installation
Vom ersten Start bis zur Fehlersuche. Wenn etwas fehlt, hilft der vollständige Quellcode samt Planungsdokumenten auf GitHub weiter.
In drei Minuten startklar.
Docker Desktop bzw. Docker Engine vorausgesetzt. Lade zuerst das Quellpaket herunter.
# 1 · Quellpaket entpacken und hineinwechseln $ tar xzf zettelwirtschaft-1.4.1-source.tar.gz && cd zettelwirtschaft-1.4.1 # 2 · Konfiguration anlegen $ cp .env.example .env # 3 · Stack starten $ docker compose up -d --build # 4 · KI-Modelle einmalig laden (LLM + Embeddings) $ docker compose exec ollama ollama pull qwen2.5:7b-instruct $ docker compose exec ollama ollama pull bge-m3 # 5 · Öffnen # Web-Oberfläche: http://localhost:8080 # Health-Check: http://localhost:8080/api/health
Smartphone-Scan: Rufe http://<rechnername>:8080 im Handy-Browser auf (gleiches WLAN) und füge die Seite zum Startbildschirm hinzu — die PWA öffnet dann direkt die Kamera-Erfassung.
Antworten auf einen Blick.
01 Welche Hardware brauche ich?
Empfohlen sind mindestens 8 GB RAM und rund 10 GB freier Plattenplatz für Modelle und Archiv. Die Dokumentenanalyse läuft auf solcher Hardware in unter 30 Sekunden pro Dokument. Eine GPU ist optional und beschleunigt nur das Sprachmodell.
02 Brauche ich zwingend Docker?
Nein. Es gibt drei Betriebsmodi: Docker (klassischer Stack, Multi-Plattform), Native Windows (Setup.exe installiert einen Hintergrunddienst, ChromaDB embedded) und Dev (direkt aus dem Quellcode mit uvicorn und npm run dev). Für Linux-Server ist Docker der einfachste Weg.
03 Welche KI-Modelle werden verwendet?
Standardmäßig qwen2.5:7b-instruct für die Analyse (Fallback llama3.2) und bge-m3 für die Embeddings der semantischen Suche. Beide laufen lokal über Ollama. Das LLM ist rund 4,5 GB groß und wird beim ersten Start geladen. Über OLLAMA_MODEL bzw. EMBEDDING_MODEL lassen sich andere Modelle einstellen.
04 Werden Daten in die Cloud gesendet?
Nein — und zwar grundsätzlich nicht. Es gibt keinen Cloud-Anbieter, keinen Account-Zwang und keine Telemetrie. OCR, KI-Analyse und Vektorsuche laufen vollständig auf deiner eigenen Hardware. Die Anwendung ist als Open Source jederzeit überprüfbar.
05 Wie sichere ich den Zugang ab?
Über einen optionalen PIN-Schutz: PIN_ENABLED=true und PIN_CODE=xxxx in der .env (bzw. config.toml im Native-Modus). Login-Versuche sind ratenbegrenzt (5 Versuche, dann kurze Sperre). Der Windows-Installer kann beim Einrichten automatisch einen sechsstelligen PIN erzeugen.
06 Wo liegen meine Dokumente und Backups?
Im Ordner data/: hochgeladene Originale unter data/uploads, der Scanner-Eingang unter data/watch, das geordnete Archiv unter data/archive/{bereich}/{jahr}/{monat}/{typ}/ und Sicherungen unter data/backups. Die tägliche Auto-Sicherung lässt sich in den Einstellungen verwalten; .env-Geheimnisse landen bewusst nicht im Backup-ZIP.
07 Wie binde ich mein E-Mail-Postfach an?
Unter Einstellungen → E-Mail-Konten. Zettelwirtschaft holt per IMAP neue Nachrichten ab, ein lokales Sprachmodell entscheidet über die Relevanz, und passende Anhänge werden in die normale Verarbeitungs-Pipeline eingespeist. Das Postfach-Passwort wird Fernet-verschlüsselt gespeichert — dafür muss EMAIL_ENCRYPTION_KEY gesetzt sein (der Installer erzeugt ihn automatisch).
08 Wie aktualisiere ich auf eine neue Version?
Docker: neues Quellpaket entpacken und docker compose up -d --build ausführen — die Datenbankmigrationen laufen automatisch beim Start. Unter Windows erledigt das update.bat inklusive Sicherheitskopie von Datenbank und Konfiguration. Ein Wechsel von Docker zu Native ist dokumentiert (Backup → Daten kopieren → config.toml erzeugen → Dienst installieren).
09 Etwas funktioniert nicht — wo schaue ich nach?
Prüfe zuerst den Health-Check unter http://localhost:8080/api/health. Logs im Docker-Modus: docker compose logs -f backend. Häufigste Ursache bei fehlender Analyse ist ein noch nicht geladenes Ollama-Modell — dann landet das Dokument im Status NEEDS_REVIEW statt abzustürzen (Graceful Degradation). Der Vektor-Index lässt sich in der System-Wartung neu aufbauen.
10 Was kostet Zettelwirtschaft?
Nichts. Die Software steht unter der AGPL-3.0 und ist vollständig quelloffen. Keine Abos, keine Lizenzschlüssel, keine versteckten Cloud-Kosten.