FAQ & Schnellstart
Kurze Antworten auf häufige Fragen. Ausführliche Schritt-für-Schritt-Anleitungen für Installation, Scanner, E-Mail, Backup und Update stehen unter Anleitungen.
Docker: in drei Minuten startklar.
Für Linux, Server und NAS mit Docker Engine. Unter Windows ist die Setup.exe einfacher — siehe Windows-Anleitung. Lade zuerst das Quellpaket herunter.
# 1 · Quellpaket entpacken und hineinwechseln $ tar xzf zettelwirtschaft-1.8.0-source.tar.gz && cd zettelwirtschaft-1.8.0 # 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 gemma4:e2b-it-qat $ docker compose exec ollama ollama pull qwen3-embedding:4b # 5 · Öffnen # Web-Oberfläche: http://localhost:8080 # Health-Check: http://localhost:8080/api/health
Smartphone-Scan: Die Kamera funktioniert im Browser nur über HTTPS. Richte einmal ein selbstsigniertes Zertifikat ein, öffne die App im Handy (gleiches WLAN) und füge sie zum Startbildschirm hinzu — siehe Anleitung Smartphone-Scan.
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 dauert auf reiner CPU etwa 40 Sekunden pro Dokument, mit einer NVIDIA-GPU nur wenige Sekunden. 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 gemma4:e2b-it-qat für die Analyse und qwen3-embedding:4b für die Embeddings der semantischen Suche — ausgewählt in einem Vergleich von 13 Sprachmodellen auf 70 echten und synthetischen Belegen. Auf Rechnern mit NVIDIA-GPU ab 10 GB Grafikspeicher schlagen die Installer gemma4:12b-it-qat vor, bei weniger als 12 GB RAM qwen3-embedding:0.6b. Alles läuft lokal über Ollama (ab Version 0.30.3); die Modelle (zusammen rund 7 GB) werden beim ersten Start geladen. Über OLLAMA_MODEL bzw. EMBEDDING_MODEL lassen sich andere Modelle einstellen; bestehende Installationen behalten beim Update ihre Modelle.
04 Werden Daten in die Cloud gesendet?
Nein. Dokumente verlassen nie deinen Rechner. Es gibt keinen Cloud-Anbieter, keinen Account-Zwang und keine Telemetrie. OCR, KI-Analyse und Vektorsuche laufen vollständig auf deiner eigenen Hardware. Einzige automatische Internet-Verbindung ist der einmalige Download der KI-Modelle durch Ollama (abschaltbar mit OLLAMA_AUTO_PULL=false); die Update-Prüfung ist optional und standardmäßig aus. Die Anwendung ist als Open Source jederzeit überprüfbar.
05 Wie sichere ich den Zugang ab?
Mit einem PIN. Das Windows-Setup vergibt automatisch einen zufälligen sechsstelligen PIN und zeigt ihn am Ende an. Bei Docker setzt du PIN_ENABLED=true und PIN_CODE in der .env; im Native-Modus stehen die Werte in der config.toml. Fehlversuche sind begrenzt, danach folgt eine Sperre. Ist der Schutz aus, zeigt die App einen Hinweis. Die App gehört ins Heimnetz — nicht direkt ins Internet stellen.
06 Wo liegen meine Dokumente und Backups?
Im Datenordner (Windows-Standard: Dokumente\Zettelwirtschaft, Docker: 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. Täglich läuft automatisch ein Datenbank-Backup; das Vollbackup sichert zusätzlich alle Dokumente. Kopiere Sicherungen regelmäßig auf ein anderes Laufwerk — siehe Anleitung Backup.
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?
Windows (Setup.exe): einfach die neue Setup.exe starten. Sie erkennt die Installation, sichert vorher Datenbank und config.toml und behält Daten, Einstellungen und PIN. Docker: neues Quellpaket entpacken, .env übernehmen und docker compose up -d --build ausführen. Datenbank-Migrationen laufen in beiden Fällen automatisch beim Start. Details: Anleitung Update.
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.
11 Kann mein Netzwerkscanner direkt in Zettelwirtschaft scannen?
Ja. In der Windows-Version richtest du im Setup oder über Startmenü › Zettelwirtschaft › Scanner-Freigabe einrichten eine Freigabe für den Eingangsordner ein. Pfad, Benutzer und Passwort trägst du im Scanner unter „Scan to Network Folder“ (SMB, mindestens SMB2) ein. Alternativ darf der Eingangsordner auf einer NAS liegen. Zur Anleitung.
12 Mein Scanner legt mehrere Briefe in eine PDF — was passiert?
Ab Version 1.7.0 prüft die App PDFs ab drei Seiten auf Dokumentgrenzen, z. B. „Seite 1 von 2“, eine neue Anschrift oder ein Trennblatt. Findet sie mehrere Dokumente, erscheint der Stapel unter „Zu prüfen“ › „Stapel zum Aufteilen“. Im Editor bestätigst oder korrigierst du die Schnitte. Ohne deine Bestätigung wird nichts aufgeteilt. Zur Anleitung.
13 Brauche ich eine Internetverbindung?
Nur einmal für die Installation und den Download der KI-Modelle (zusammen ca. 5–10 GB). Danach laufen Erfassung, Texterkennung, KI-Analyse und Suche vollständig offline.
14 Wie gut erkennt die KI meine Belege?
Im Vergleich auf 70 echten und synthetischen Belegen erkannte das Standardmodell gemma4:e2b-it-qat die Kernfelder (Typ, Datum, Betrag, Aussteller) zu rund 85 %, das größere gemma4:12b-it-qat zu rund 90 %. Unsichere Ergebnisse landen unter „Zu prüfen“ statt ungeprüft im Archiv. Korrekturen merkt sich die App und wendet sie ab dem dritten gleichen Fall automatisch an.
15 Kann ich die App aus dem Internet erreichbar machen?
Davon raten wir ab. Zettelwirtschaft ist für das Heimnetz gebaut: Es gibt einen PIN, aber keine Benutzerverwaltung. Für unterwegs ist ein VPN ins Heimnetz (z. B. über den Router) die sichere Lösung.