Anleitungen & Tutorials

1. Ollama installieren

   Lade Ollama von ollama.com/download und installiere es. Benötigt wird Version 0.30.3 oder neuer. Ollama führt die KI-Modelle lokal aus und läuft als eigener Dienst.

2. Setup herunterladen

   Lade Zettelwirtschaft-1.7.0-Native-Setup.exe von der Download-Seite. Optional: Prüfsumme in PowerShell mit Get-FileHash .\Zettelwirtschaft-1.7.0-Native-Setup.exe vergleichen.

3. Setup starten

   Doppelklick auf die Datei. Windows zeigt eventuell „Der Computer wurde durch Windows geschützt“, weil der Installer nicht signiert ist. Klicke auf Weitere Informationen und dann Trotzdem ausführen.

4. Datenordner wählen

   Standard ist Dokumente\Zettelwirtschaft. Hier liegen Datenbank, Archiv und Uploads. Ein externes Laufwerk oder ein Cloud-Sync-Ordner ist ebenfalls möglich.

5. Netzwerkzugriff festlegen

   Soll die App nur auf diesem PC laufen, setze den Haken „Nur von diesem PC erreichbar“. Für Smartphone-Scan und andere Geräte im Heim-WLAN lässt du ihn weg. Optional richtest du hier gleich die Scanner-Freigabe ein.

6. PIN notieren

   Die Abschlussseite zeigt einen zufälligen sechsstelligen PIN. Notiere ihn: Die App fragt beim Öffnen danach.

7. App öffnen

   Öffne http://localhost:8080. Beim ersten Start lädt die App die KI-Modelle selbst herunter (je nach Hardware zusammen ca. 5–10 GB). Den Fortschritt zeigt System → Systemstatus. Eine Willkommens-Tour erklärt die wichtigsten Bereiche.

Ergebnis: Der Dienst ZettelwirtschaftBackend startet ab jetzt automatisch mit Windows. Steuern lässt er sich über services.msc. Logs liegen im Datenordner.

1. Quellpaket laden und entpacken

   $ tar xzf zettelwirtschaft-1.7.0-source.tar.gz
   $ cd zettelwirtschaft-1.7.0

2. Konfiguration anlegen

   $ cp .env.example .env
   # wichtig: PIN_ENABLED=true und eigenen PIN_CODE setzen

   Die Datei .env.example erklärt jede Einstellung. Port der Weboberfläche: FRONTEND_PORT (Standard 8080).

3. Stack starten

   $ docker compose up -d --build

4. KI-Modelle laden

   Das Backend lädt fehlende Modelle beim Start automatisch. Den Download kannst du auch vorab anstoßen:

   $ docker compose exec ollama ollama pull gemma4:e2b-it-qat
   $ docker compose exec ollama ollama pull qwen3-embedding:4b

5. Prüfen und öffnen

   Health-Check: curl http://localhost:8080/api/health. Danach die Weboberfläche unter http://<server>:8080 öffnen. Logs: docker compose logs -f backend.

Ohne lokalen Build: Die fertigen Images von der Download-Seite mit docker load -i … laden und per docker-compose.override.yml einbinden (Weg B auf der Download-Seite).

1. Datei hochladen

   Öffne Upload und ziehe eine Rechnung per Drag & Drop ins Fenster. Erlaubt sind PDF, JPG, PNG, TIFF und BMP bis 50 MB pro Datei.

2. Analyse abwarten

   Die App liest den Text per OCR und lässt das lokale Sprachmodell Typ, Datum, Betrag, Aussteller, Steuer- und Garantieangaben bestimmen. Auf reiner CPU dauert das etwa 40 Sekunden, mit NVIDIA-GPU wenige Sekunden.

3. Ergebnis ansehen

   Das Dokument erscheint unter Dokumente. In der Detailansicht siehst du Vorschau und erkannte Felder. Falsche Werte korrigierst du direkt im Formular.

4. Rückfragen beantworten

   War die KI unsicher, liegt das Dokument unter Zu prüfen. Beantworte die Rückfrage oder bestätige mit „So übernehmen“. Wiederholte Korrekturen merkt sich die App und wendet sie ab dem dritten Mal automatisch an.

Weitere Eingänge: Watch-Ordner (Datei ablegen, wird automatisch erkannt), Smartphone-Scan, Netzwerkscanner und E-Mail-Import.

1. HTTPS einrichten

   Docker:

   $ bash ssl/generate-cert.sh
   $ docker compose -f docker-compose.yml -f docker-compose.ssl.yml up -d

   Windows: Zertifikat mit dem gebündelten Python erzeugen (<Programmordner>\bin\python.exe ssl\generate-self-signed-cert.py), dann in config.toml SERVER_SSL_CERTFILE und SERVER_SSL_KEYFILE setzen und den Dienst neu starten.

2. App im Handy öffnen

   Im selben WLAN https://<rechnername-oder-IP> aufrufen (Docker: Port 443, Windows: konfigurierter Port). Die Zertifikatswarnung einmalig bestätigen („Erweitert“ → „Trotzdem fortfahren“). Im Heimnetz ist das normal.

3. Zum Startbildschirm hinzufügen

   Im Browser-Menü „Zum Startbildschirm hinzufügen“ wählen. Die App startet dann wie eine normale App.

4. Beleg scannen

   Auf Scan tippen, Beleg fotografieren, Vorschau prüfen und hochladen. Die Analyse läuft auf deinem Rechner, nicht auf dem Handy.

Ohne HTTPS: Fotos mit der normalen Kamera-App aufnehmen und über Upload hochladen. Das funktioniert auch über http://.

Variante 1 — Scanner scannt direkt auf den PC

1. Freigabe einrichten

   Im Setup die Option „Eingangsordner im Netzwerk freigeben“ wählen oder später Startmenü › Zettelwirtschaft › Scanner-Freigabe einrichten starten (Administratorrechte nötig).

2. Zugangsdaten notieren

   Angezeigt werden der Pfad \\<PC>\Zettelwirtschaft-Eingang, der Benutzer zw-scanner und ein Passwort. Das Passwort erscheint nur einmal.

3. Scanner konfigurieren

   Im Scanner-Menü bzw. Web-Interface unter „Scan to Network Folder“ / SMB Pfad, Benutzer und Passwort eintragen. Der Scanner braucht mindestens SMB2.

4. Testscan

   Eine Seite scannen. Sie erscheint nach kurzer Zeit im Dashboard und wird verarbeitet.

Sicherheit: Das Scanner-Konto darf nur in den Eingangsordner schreiben. Die Firewall öffnet SMB (TCP 445) im privaten Netz für den ganzen PC; mit -ScannerAddress nur für die Adresse des Scanners. Die Zugangsdaten nur im Scanner hinterlegen.

Variante 2 — Scanner speichert auf der NAS

1. Ordner eintragen

   Unter System → Ordner den Eingangsordner als UNC-Pfad eintragen, z. B. \\nas\scan, mit Benutzer und Passwort der Freigabe. Laufwerksbuchstaben wie V: sieht der Hintergrunddienst nicht.

2. Verbindung testen

   „Verbindung testen“ klicken. Die App prüft den Ordner regelmäßig (Standard alle 30 Sekunden) und verbindet sich nach einem NAS-Neustart selbst wieder.

1. Stapel öffnen

   Erkennt die App mehrere Dokumente oder ist sie unsicher, erscheint der Stapel unter Zu prüfen › Stapel zum Aufteilen, mit Benachrichtigung.

2. Schnitte prüfen

   Im Editor siehst du alle Seiten als Vorschaubilder. Schnitte setzt oder entfernst du per Klick zwischen zwei Seiten. Orange Stellen sind unsicher, die Begründung steht daneben (z. B. „Seite 1 von 2“, neue Anschrift, Trennblatt).

3. Seiten weglassen

   Leere Trennblätter kannst du weglassen. Die App verwirft nie automatisch eine Seite.

4. Bestätigen

   Nach dem Bestätigen wird jeder Teil als eigenes Dokument analysiert, abgelegt und durchsuchbar.

Weitere Wege: Beim Upload die Option „Enthält mehrere Dokumente“ wählen, oder ein archiviertes Dokument in der Detailansicht über „Dokument aufteilen“ zerlegen. „Aufteilung rückgängig“ geht, solange kein Teil bearbeitet wurde. Einstellungen: System → Verarbeitung.

1. Konto anlegen

   Unter System im Abschnitt E-Mail-Konten ein neues Konto anlegen: IMAP-Server, Port (meist 993 mit SSL), Benutzername und Passwort. Das Passwort wird verschlüsselt gespeichert.

2. Ordner wählen

   Posteingangs-Ordner (z. B. INBOX oder ein eigener Ordner „Rechnungen“) und Zielordner für verarbeitete Mails festlegen. Verarbeitete Mails werden dorthin verschoben.

3. Zeitplan wählen

   Manuell (nur auf Knopfdruck), Zeitgesteuert (CRON-Ausdruck, z. B. 0 7 * * * für täglich 7 Uhr) oder Automatisch (alle 5 Minuten).

4. Testen und abrufen

   Verbindung testen, dann „Jetzt abrufen“. Der Verlauf zeigt, welche Mails als relevant erkannt wurden.

Tipp: Nur ungelesene Mails werden abgerufen. Mit einer Postfach-Regel, die Rechnungen in einen eigenen Ordner sortiert, sieht die App nur, was sie sehen soll. IMAP-Server mit selbstsigniertem Zertifikat werden abgelehnt.

1. Steuerrelevanz prüfen

   In der Dokumentenliste ist die Steuerrelevanz direkt sichtbar und per Klick änderbar. Die KI schlägt Kategorien vor, z. B. Werbungskosten, Handwerkerleistungen oder haushaltsnahe Dienstleistungen.

2. Jahr wählen

   Seite Steuer öffnen, Steuerjahr wählen und bei mehreren Ablagebereichen optional einen Bereich (z. B. nur „Privat“).

3. Exportieren

   „ZIP exportieren“ klicken. Die Summen enthalten nur Euro-Beträge. Belege in anderen Währungen werden gesondert aufgeführt.

Hinweis: Zettelwirtschaft ersetzt keine Steuerberatung. Die Kategorien sind Vorschläge der KI und vor der Abgabe zu prüfen.

1. Vollbackup erstellen

   Unter System → Backups: „Backup (DB)“ sichert die Datenbank, „Vollbackup“ zusätzlich alle Originaldokumente. Unter Windows geht es auch offline über Startmenü „Backup jetzt“ bzw. backup.bat /full.

2. Sicherung auslagern

   Die ZIPs liegen im Datenordner unter backups. Kopiere sie regelmäßig auf eine externe Platte oder NAS. Ein Backup auf derselben Platte schützt nicht vor einem Plattendefekt.

3. Wiederherstellen (Windows)

   restore-backup.bat <backup.zip> als Administrator ausführen. Das Skript stoppt den Dienst, spielt Datenbank (und bei Vollbackups die Dokumente) zurück und startet den Dienst neu.

4. Suchindex neu aufbauen

   Nach einer Wiederherstellung unter System → Wartung „Vektor-Index aufbauen“ starten, damit der KI-Assistent wieder alle Dokumente findet.

Docker: Den Ordner data/ sichern (Datenbank, Archiv, Backups). Geheimnisse aus der .env landen bewusst nicht im Backup-ZIP — die .env separat sicher aufbewahren.

1. Windows: Setup ausführen

   Neue Native-Setup.exe starten. Sie erkennt die bestehende Installation, erstellt vorher eine Sicherung nach Dokumente\Zettelwirtschaft-Backups und aktualisiert die Programmdateien. Alternativ: Update-Paket in einen Temp-Ordner entpacken und update-wizard.bat als Administrator starten.

2. Docker: Stack neu bauen

   $ tar xzf zettelwirtschaft-1.7.0-source.tar.gz
   $ cp ../zettelwirtschaft-alt/.env zettelwirtschaft-1.7.0/
   $ cd zettelwirtschaft-1.7.0 && docker compose up -d --build

   Den data/-Ordner übernehmen oder vorher sichern. Unter Windows mit Docker erledigt das update.bat inklusive Sicherung.

3. Version prüfen

   Unter System steht die installierte Version. Wer will, aktiviert dort die Update-Prüfung: Sie fragt nur eine Versionsdatei ab, ohne Nutzungs- oder Dokumentdaten, und ist standardmäßig aus.