timer-app/DEPLOY.md

Timer App — Übergabe- und Installationsdokument

Für die Claude-Code-Instanz, die diese App in die Firmeninfrastruktur einbaut.

Stand: 03.08.2026 · Version 2.0 · Getestet auf Debian 13, Node 20.19.2

---

0. Das Wichtigste in 60 Sekunden

Kleine, in sich geschlossene Node-App zur Zeiterfassung mit Kostenberechnung, gedacht für den Einsatz im Ladengeschäft (Tresen-Tablet, mehrere Plätze parallel).

• Keine externen Dienste. Kein Cloud-Backend, keine API-Keys, keine Telemetrie, keine CDN-Einbindung. Ausgehend spricht die App nur mit zwei Zielen im eigenen Netz: Authentik (Anmeldung) und — falls eingerichtet — dem Bondrucker-Pi (Abschnitt 6). Kein Ziel außerhalb des eigenen Netzes.
• Keine Datenbank-Installation nötig. SQLite, eine einzelne Datei.
• Keine Build-Kette. Kein Webpack, kein TypeScript, kein npm run build. Vanilla JS im Frontend, Express im Backend.
• Abhängigkeiten: 8 npm-Pakete, alle etabliert (express, express-session, express-rate-limit, sqlite3, bcrypt, dotenv, openid-client, ssh2). ssh2 ist reines JavaScript und wird nur für die Einrichtung eines Drucker-Pi gebraucht (Abschnitt 6).

Realistisch: In 15 Minuten deployt, wenn die drei Stolpersteine aus Abschnitt 3 beachtet werden. Ohne sie kann es beliebig lange dauern, weil zwei davon stumm scheitern.

---

1. Was die App fachlich tut

Ein Mitarbeiter startet am Tresen einen Timer, optional mit einem Namen („Tisch 2", „Herr Müller", „Reparatur Werkbank"). Die App zählt die Zeit und rechnet daraus laufend einen Betrag aus. Beim Beenden wandert der Vorgang in die Historie und kann später als CSV exportiert werden.

Abrechnungsregel: Jede angefangene Einheit wird voll berechnet. Standard ist 10 € pro 10 Minuten, im Menü „Einstellungen" änderbar.

Dauer	Betrag (bei 10 €/10 Min)
1 Sekunde	10 €
10 Minuten	10 €
10 Min 1 Sek	20 €
25 Minuten	30 €
60 Minuten	60 €

Diese Regel ist bewusst so — sie war die fachliche Vorgabe. Falls im Betrieb minutengenau abgerechnet werden soll, ist das eine Änderung an genau einer Funktion (calcAmount, siehe Abschnitt 7).

---

2. Architektur — und warum sie so ist

Timer leben auf dem Server, nicht im Browser

Das ist die zentrale Designentscheidung und der Grund für die meisten Endpunkte. Ein laufender Timer ist eine Zeile in der Tabelle active_timers, kein JavaScript-Objekt im Browser.

Was das im Ladenalltag bedeutet:

Situation	Verhalten
Tab wird versehentlich geschlossen	Timer läuft weiter, ist nach erneutem Öffnen da
F5 / Seite neu geladen	Timer läuft weiter
Tablet-Akku leer, Neustart	Timer läuft weiter
Kollege schaut am zweiten Gerät nach	sieht dieselben Timer live
Dienst wird neu gestartet (Update)	Timer läuft weiter, Anmeldung bleibt auch bestehen
Browser über Nacht zu	Zeit läuft weiter wie eine Wanduhr

Der letzte Punkt ist eine bewusste fachliche Entscheidung: Ein laufender Timer zählt die reale verstrichene Zeit, weil der Kunde ja tatsächlich weiter im Laden sitzt. Wer die Zeit anhalten will, drückt „Pause". Falls das für den Firmeneinsatz anders gewünscht ist, siehe Abschnitt 9.

Der Browser zählt zwischen zwei Server-Abgleichen nur lokal hoch, damit die Anzeige flüssig läuft (alle 250 ms). Abgeglichen wird alle 15 Sekunden und zusätzlich sofort, wenn der Tab wieder sichtbar wird. Beim Rechnen wird bewusst nur mit Zeitdifferenzen gearbeitet, nie mit absoluten Zeitstempeln — so ist eine falsch gestellte Uhr auf dem Tablet unerheblich.

Der Betrag entsteht auf dem Server

Der Browser berechnet den Betrag nur für die Anzeige. Was in die Historie geschrieben wird, rechnet ausschließlich der Server (POST /api/timers/:id/stop). Ein manipulierter Client kann den gespeicherten Betrag nicht beeinflussen.

Eigener Sitzungsspeicher

express-session legt Sitzungen standardmäßig im Arbeitsspeicher ab — nach jedem Neustart müssten sich alle Geräte neu anmelden. Da die Timer den Neustart überleben, wäre das ein Bruch im Ablauf. Deshalb steckt in server.js eine kleine SqliteSessionStore-Klasse (~50 Zeilen), die Sitzungen in derselben SQLite-Datei ablegt. Bewusst ohne Zusatzpaket, um die Abhängigkeitsliste kurz zu halten.

---

3. Die drei Stolpersteine — bitte zuerst lesen

3.1 COOKIE_SECURE (scheitert stumm!)

In der .env steht standardmäßig COOKIE_SECURE=true. Das heißt: Der Browser nimmt das Sitzungs-Cookie nur über HTTPS an.

Symptom bei falscher Einstellung: Das Passwort wird akzeptiert (die API antwortet mit 200), aber der Nutzer landet sofort wieder auf der Login-Maske. Endlosschleife, keine Fehlermeldung, nichts im Log.

Deployment	Einstellung
Über Reverse Proxy mit HTTPS (https://timer.firma.de)	COOKIE_SECURE=true
Intern ohne TLS (http://192.168.1.50:3003)	COOKIE_SECURE=false
Über http://localhost zum Testen	COOKIE_SECURE=false

3.2 HOST — Bindeadresse

Standard ist HOST=127.0.0.1. Die App ist dann nur lokal erreichbar, was richtig ist, wenn ein Reverse Proxy davorsteht.

Ohne Reverse Proxy (App direkt im LAN): HOST=0.0.0.0 setzen, sonst kommt kein anderes Gerät heran. Dann aber unbedingt auch COOKIE_SECURE=false (siehe oben) und TRUST_PROXY=false.

3.3 node_modules nicht kopieren

Das Paket sqlite3 enthält kompilierte native Binärdateien. Ein aus dieser ZIP oder von einem anderen Rechner kopiertes node_modules führt zu Error: invalid ELF header oder Module did not self-register.

Immer auf dem Zielsystem installieren:

cd backend
npm ci        # bevorzugt, nutzt package-lock.json
# oder: npm install

Falls npm ci mangels Compiler scheitert (node-gyp-Fehler), fehlen die Build-Werkzeuge:

# Debian/Ubuntu
apt-get install -y python3 make g++
# RHEL/Alma
dnf install -y python3 make gcc-c++

---

4. Installation Schritt für Schritt

# 1. Entpacken
unzip timer-app.zip -d /opt/
cd /opt/timer-app

# 2. Abhängigkeiten (auf dem Zielsystem bauen!)
cd backend
npm ci

# 3. Konfiguration anlegen
cp .env.example .env

# 4. Zufallswert für SESSION_SECRET erzeugen
npm run gen-secret
#    -> Ausgabe in die .env bei SESSION_SECRET eintragen

# 5. Passwort-Hash erzeugen
npm run hash-password -- "EuerPasswort"
#    -> Ausgabe in die .env bei PASSWORD_HASH eintragen

# 6. Datenverzeichnis sicherstellen
mkdir -p ../data

# 7. Testlauf im Vordergrund
node server.js
#    Erwartete Ausgabe:
#      Timer App laeuft auf http://127.0.0.1:3003
#      Datenbank verbunden: .../data/timer.db
#      Standardtarif gesetzt: 10 EUR pro 10 Minuten
#      Datenbank bereit

# 8. Prüfen
curl http://127.0.0.1:3003/health

Die App bricht beim Start bewusst ab, wenn SESSION_SECRET oder das Passwort fehlen — lieber laut scheitern als unsicher laufen.

---

5. Konfiguration (.env)

Variable	Standard	Bedeutung
PORT	3003	Lauschender Port
HOST	127.0.0.1	Bindeadresse — siehe 3.2
TRUST_PROXY	1	Anzahl Proxy-Ebenen davor; ohne Proxy false
COOKIE_SECURE	true	Cookie nur über HTTPS — siehe 3.1
SESSION_SECRET	—	Pflicht. Zufallswert, npm run gen-secret
PASSWORD_HASH	—	bcrypt-Hash, npm run hash-password -- "…"
PASSWORD	—	Notfall-Alternative im Klartext; App warnt beim Start
LOGIN_MAX_ATTEMPTS	20	Anmeldeversuche pro Zeitfenster
LOGIN_WINDOW_MIN	15	Länge des Zeitfensters in Minuten
DB_PATH	../data/timer.db	Pfad zur SQLite-Datei
RATE_PER_10MIN	10	Nur beim allerersten Start. Danach steht der Tarif in der Datenbank und wird über die Oberfläche gepflegt.
PRINTER_HOST	leer	IP des Bondrucker-Pi. Leer = Druckfunktion aus, die App verhält sich wie vorher
PRINTER_PORT	9100	Port der Brücke auf dem Pi
PRINTER_TOKEN	leer	muss mit PRINT_TOKEN in /etc/bondrucker/env übereinstimmen
PRINTER_WIDTH	42	Zeichen je Zeile: 42 bei 80-mm-Papier, 32 bei 58 mm
PRINTER_TIMEOUT_MS	6000	Abbruch, wenn der Pi nicht antwortet

Die vier PRINTER_*-Werte oberhalb von PRINTER_TIMEOUT_MS sind nur Startwerte beim allerersten Start — genau wie RATE_PER_10MIN. Danach lebt der Druckerzugang in der Datenbank und wird über die Oberfläche gepflegt; eine spätere Änderung in der .env bleibt wirkungslos. Der Grund steht in Abschnitt 6: ein Druckerwechsel soll kein Server-Zugang sein.

SESSION_SECRET muss ein echter Zufallswert sein. In der Vorgängerversion stand dort versehentlich der literale Text $(openssl rand -base64 32) — die Befehlssubstitution war beim Anlegen der Datei nie ausgeführt worden. Mit einem erratbaren Secret lassen sich Sitzungs-Cookies fälschen und die Anmeldung umgehen. Deshalb: Wert immer mit npm run gen-secret erzeugen, nie von Hand ausdenken, nie aus einer Doku kopieren.

---

6. Betrieb

systemd-Unit

Vorlage liegt bei unter deploy/timer-app.service. Anpassen: WorkingDirectory, User, ggf. ExecStart-Pfad zu node.

cp deploy/timer-app.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now timer-app
systemctl status timer-app
journalctl -u timer-app -f

Die Unit läuft in der Vorlage als eigener Benutzer (nicht root) und enthält die üblichen Härtungsoptionen. Wenn ein eigener Benutzer angelegt wird, muss ihm das data/-Verzeichnis gehören:

useradd --system --no-create-home --shell /usr/sbin/nologin timerapp
chown -R timerapp:timerapp /opt/timer-app/data
chown timerapp:timerapp /opt/timer-app/backend/.env
chmod 600 /opt/timer-app/backend/.env

Reverse Proxy

Beispiele liegen bei: deploy/Caddyfile.example und deploy/nginx.conf.example.

Wichtig in beiden Fällen:

• X-Forwarded-Proto durchreichen (sonst greift trust proxy nicht richtig)
• /health ist der Endpunkt für Health-Checks (antwortet ohne Anmeldung)
• Websockets werden nicht gebraucht

Bondrucker

Vollständige Einrichtung: deploy/bondrucker/README.md. Hier nur das Wesentliche.

Der Drucker hängt per USB an einem Raspberry Pi im Laden. Auf dem Pi läuft ein kleiner Python-Dienst, der fertige ESC/POS-Daten per HTTP annimmt und in /dev/usb/lp0 schreibt. Der Bon selbst entsteht in dieser App (backend/receipt.js) — auf dem Pi liegt bewusst keine Layout-Logik.

Timer-App  ──HTTP POST /print──▶  Pi (bondrucker.service)  ──▶  /dev/usb/lp0
 receipt.js baut den Bon              schiebt Bytes durch          Epson TM-T88IV

Drei Wege führen zu einem Bon:

Auslöser	Beleg	Timer danach
🖨 Bon auf der Timer-Karte	Zwischenstand	läuft unverändert weiter
✓ Beenden	Endbeleg	ist beendet und in der Historie
🖨 in der Historie	Nachdruck desselben Belegs	—

Reihenfolge ist Absicht: Beim Beenden wird erst gespeichert, dann gedruckt. Ein leerer Papierhalter ist damit ein Papierproblem und kein Datenproblem — der Vorgang steht in der Historie und lässt sich von dort nachdrucken. Die Oberfläche sagt in dem Fall ausdrücklich, dass der Bon nicht gedruckt wurde.

Kopf- und Fußzeilen des Bons stehen in der Datenbank und werden unter Einstellungen gepflegt, ebenso der Schalter „Bon beim Beenden automatisch drucken". Der Probedruck dort beantwortet die Frage, ob es am Drucker oder an der App liegt.

Einen Pi einrichten

⚙️ Einstellungen → 🔧 Drucker einrichten richtet einen frisch aufgesetzten Raspberry Pi vollständig selbst ein: IP, Benutzer und Passwort eintragen, Knopf drücken, fertig — rund drei Sekunden.

Die App meldet sich per SSH an, prüft Python/systemd/Druckergerät, überträgt die vier Dateien aus deploy/bondrucker/ per SFTP nach /tmp, startet install.sh mit einem selbst erzeugten Token, räumt auf und prüft von außen nach. Danach übernimmt sie den Drucker selbst. Jeder Schritt steht mit Ergebnis im Protokoll.

Warum der Druckerzugang in der Datenbank liegt und nicht in der .env: Sonst wäre genau dieser Knopf sinnlos — die Werte müssten hinterher doch wieder von Hand auf dem Server eingetragen werden. Ein Druckerwechsel im Laden soll kein SSH-Zugang zum Timer-Server sein.

Zum Umgang mit den Zugangsdaten: Benutzername und Passwort stehen nur während des Vorgangs im Arbeitsspeicher. Sie werden nicht gespeichert, nicht ins Journal geschrieben und nicht an den Browser zurückgegeben; das erzeugte Drucker-Token wird vor der Ausgabe aus dem Protokoll entfernt. Dauerhaft bleibt allein dieses Token in der Datenbank.

Der Hostschlüssel des Pi wird beim Erstkontakt angenommen und im Protokoll ausgewiesen (SHA256:…) — im eigenen Netz vertretbar, aber es ist eben kein Schutz gegen einen Angreifer, der schon im Netz sitzt.

install.sh ist wiederholbar und startet den Dienst dabei neu. Ohne den Neustart liefe die Brücke mit dem alten Token weiter und würde jeden Bon mit HTTP 403 ablehnen — die Gegenprobe nach der Einrichtung prüft deshalb nicht nur die Erreichbarkeit, sondern auch, ob das neue Token angenommen wird.

Der Pi hängt per WLAN und DHCP im Netz. Wechselt seine Adresse, druckt die App nicht mehr, bis PRINTER_HOST angepasst ist — eine DHCP-Reservierung im Router erspart das.

Backup

Alles Wichtige steckt in einer Datei: data/timer.db.

# konsistente Sicherung im laufenden Betrieb (WAL-Modus ist aktiv!)
sqlite3 /opt/timer-app/data/timer.db ".backup '/backup/timer-$(date +%F).db'"

⚠️ Nicht einfach cp auf eine laufende Datenbank — im WAL-Modus kann eine so erzeugte Kopie unvollständig sein. Entweder .backup benutzen (wie oben) oder den Dienst vorher stoppen.

Die .env gehört ebenfalls ins Backup (enthält Secret und Passwort-Hash), aber getrennt und mit engeren Rechten.

---

7. Aufbau des Codes

timer-app/
├── DEPLOY.md                     ← dieses Dokument
├── README.md                     ← Kurzanleitung für Anwender
├── backend/
│   ├── server.js                 ← die gesamte Server-Logik
│   ├── escpos.js                 ← ESC/POS-Bausteine für den Bondrucker
│   ├── receipt.js                ← Layout des Bons
│   ├── printer.js                ← Aufruf der Brücke auf dem Pi
│   ├── provision.js              ← richtet einen Drucker-Pi per SSH ein
│   ├── package.json
│   ├── package-lock.json
│   ├── .env.example
│   └── tools/hash-password.js    ← Hilfsskript für den Passwort-Hash
├── frontend/
│   ├── index.html                ← Markup + komplettes CSS
│   ├── app.js                    ← Oberflächenlogik
│   ├── logo.png                  ← ⚠️ Firmenlogo, ggf. austauschen
│   └── favicon.jpg
└── deploy/
    ├── timer-app.service
    ├── Caddyfile.example
    ├── nginx.conf.example
    └── bondrucker/               ← Druckdienst für den Raspberry Pi
        ├── README.md             ← Einrichtung des Pi
        ├── print-server.py       ← der Dienst (nur Python-Standardbibliothek)
        ├── bondrucker.service
        └── install.sh

server.js ist in beschriftete Abschnitte gegliedert (Konfiguration, Datenbank, Tarif & Berechnung, Sitzungsspeicher, Auth, Timer, Einstellungen, Historie).

Datenmodell

-- Laufende Timer: eine Zeile pro Platz/Kunde
active_timers(
  id, customer_name, started_at, accumulated_ms, is_running, created_at
)
-- started_at:     ms-Zeitstempel des letzten Starts/Fortsetzens (NULL bei Pause)
-- accumulated_ms: vor der aktuellen Laufphase gesammelte Zeit
-- Vergangene Zeit = accumulated_ms + (jetzt - started_at), falls is_running

-- Abgeschlossene Vorgänge
sessions(
  id, session_id, start_time, end_time, duration, amount,
  customer_name, rate_amount, rate_interval, created_at
)
-- rate_amount/rate_interval halten fest, welcher Tarif beim Beenden galt,
-- damit eine spätere Tarifänderung alte Belege nicht rückwirkend verändert.
-- created_at ist in SEKUNDEN, alle anderen Zeiten in MILLISEKUNDEN (historisch).

settings(key, value)         -- rate_amount, rate_interval
user_sessions(sid, expires, data)  -- Anmelde-Sitzungen

Das Schema wird beim Start automatisch migriert (ALTER TABLE ADD COLUMN, nur falls Spalte fehlt). Eine Datenbank der Vorgängerversion kann direkt weiterverwendet werden; getestet mit 21 Altdatensätzen, die unverändert erhalten blieben und in der Oberfläche als „ohne Namen" erscheinen.

Die Abrechnungsregel ändern

Genau eine Funktion in server.js, plus die gleichnamige in app.js für die Anzeige:

function calcAmount(ms, rateAmount, rateInterval) {
    if (!ms || ms <= 0) return 0;
    const minutes = Math.ceil(ms / 60000);          // angefangene Minute
    const units = Math.ceil(minutes / rateInterval); // angefangene Einheit
    return Math.round(units * rateAmount * 100) / 100;
}

Für minutengenaue Abrechnung z. B.: return Math.round((ms / 60000) * (rateAmount / rateInterval) * 100) / 100;

---

8. API-Referenz

Alle Endpunkte außer /health, /api/login, /api/auth/status und /api/logout erfordern eine gültige Sitzung (sonst 401).

Methode	Pfad	Zweck
POST	/api/login	{password} → Sitzung
GET	/api/auth/status	{authenticated: bool}
POST	/api/logout	Sitzung beenden
GET	/api/timers	alle laufenden Timer + aktueller Tarif
POST	/api/timers	{customerName} → neuer Timer
PATCH	/api/timers/:id	{customerName} umbenennen
POST	/api/timers/:id/pause	anhalten
POST	/api/timers/:id/resume	fortsetzen
POST	/api/timers/:id/stop	beenden und in Historie speichern; druckt den Bon, sofern eingerichtet. Optional {print: bool} überstimmt die Einstellung
POST	/api/timers/:id/receipt	Zwischenbon drucken, Timer bleibt unangetastet
DELETE	/api/timers/:id	verwerfen, nichts speichern
GET	/api/settings	Tarif, Bon-Texte und Druckerzustand lesen
PUT	/api/settings	{rateAmount, rateInterval} sowie optional {receiptHeader, receiptFooter, printAutoOnStop}
GET	/api/printer/status	Erreichbarkeit und Zustand des Druckers
POST	/api/printer/test	Probedruck
POST	/api/printer/provision	{host, port, username, password} → richtet den Pi ein und übernimmt ihn. Antwort enthält das Schrittprotokoll, nie die Zugangsdaten
GET	/api/sessions	Historie; Parameter from, to, q, limit, offset
DELETE	/api/sessions/:id	Eintrag löschen
POST	/api/sessions/:id/receipt	Bon aus der Historie nachdrucken
GET	/api/sessions/export.csv	CSV; gleiche Filterparameter
GET	/health	Status, ohne Anmeldung

from/to sind Datumsangaben YYYY-MM-DD und werden in der Zeitzone des Servers ausgewertet. Wenn Server und Laden in verschiedenen Zeitzonen stehen, TZ=Europe/Berlin in der systemd-Unit setzen.

Die CSV ist für deutsches Excel vorbereitet: Semikolon als Trenner, UTF-8-BOM (damit Umlaute stimmen), Komma als Dezimaltrennzeichen.

---

9. Bekannte Grenzen — bewusst so gelassen

Diese Punkte sind keine Fehler, sondern Entscheidungen. Sie stehen hier, damit sie bei Bedarf eingeordnet werden können.

Thema	Aktueller Stand	Wenn die Firma mehr braucht
Ein gemeinsames Passwort	Alle teilen sich ein Passwort, keine Benutzerkonten, keine 2FA	Für „wer hat welchen Vorgang erfasst" wären echte Konten nötig. Der Sitzungsspeicher liegt bereits in der DB, eine users-Tabelle wäre der nächste Schritt.
Jeder sieht alles	Wer angemeldet ist, sieht alle Timer und die gesamte Historie	Im Ladenbetrieb gewollt (Kollege übernimmt die Schicht). Mandantentrennung wäre ein größerer Umbau.
Kein Audit-Log	Löschen eines Historien-Eintrags ist endgültig und wird nicht protokolliert	Falls die Erfassung abrechnungsrelevant wird, ist ein deleted_at statt echtem Löschen sinnvoll (GoBD-Thema — bitte fachlich klären).
Wanduhr-Verhalten	Ein laufender Timer zählt auch nachts weiter	Wenn stattdessen automatisch pausiert werden soll: eine Obergrenze in elapsedMs() einbauen oder einen nächtlichen Auto-Pause-Job.
Keine Mehrprozess-Fähigkeit	Ein Node-Prozess, SQLite	Für die erwartete Last (ein Laden, wenige Geräte) um Größenordnungen ausreichend. Bei mehreren Filialen: PostgreSQL und echte Benutzerverwaltung.
Logo	frontend/logo.png ist das Logo des bisherigen Einsatzorts, 654 KB	Austauschen und dabei gern verkleinern (~50 KB reichen). Ebenso favicon.jpg. Der Seitentitel steht in index.html (<title>).
Zeitzone	Server-Zeitzone bestimmt Tagesgrenzen im Filter	TZ in der Unit setzen

---

10. Fehlersuche

Symptom	Ursache	Lösung
Login akzeptiert, springt zurück zur Maske	COOKIE_SECURE=true ohne HTTPS	COOKIE_SECURE=false oder TLS davor
Von anderen Geräten nicht erreichbar	HOST=127.0.0.1 ohne Proxy	HOST=0.0.0.0
Error: invalid ELF header	fremdes node_modules	löschen, npm ci
node-gyp-Fehler bei npm ci	Build-Werkzeuge fehlen	apt install python3 make g++
FATAL: SESSION_SECRET ist nicht gesetzt	.env fehlt/unvollständig	Abschnitt 4, Schritt 3–5
SQLITE_CANTOPEN	data/ fehlt oder Rechte	mkdir -p data && chown
Zeiten wirken um Stunden verschoben	Server-Zeitzone	TZ=Europe/Berlin in der Unit
Alle ausgeloggt nach Neustart	sollte nicht passieren	prüfen, ob user_sessions in der DB existiert

Diagnose-Einstieg:

systemctl status timer-app
journalctl -u timer-app -n 50 --no-pager
curl -s http://127.0.0.1:3003/health
sqlite3 data/timer.db "select count(*) from sessions; select * from active_timers;"

---

11. Sicherheit — Stand und Empfehlungen

Vorhanden:

• Passwort als bcrypt-Hash (Kostenfaktor 12), nicht im Klartext im Code
• Sitzungs-ID wird beim Login neu vergeben (kein Session-Fixation)
• Cookie httpOnly, sameSite=lax, optional secure
• Ratenbegrenzung auf dem Login (20 Versuche / 15 Min, konfigurierbar)
• Alle SQL-Zugriffe mit gebundenen Parametern (keine String-Verkettung)
• Ausgabe im Frontend wird escaped (kein innerHTML mit Rohdaten aus der DB)
• Beträge werden serverseitig berechnet

Vor dem Produktivgang zu klären:

1. Erreichbarkeit. Muss die App aus dem Internet erreichbar sein oder reicht das Firmen-LAN/VPN? Ein gemeinsames Passwort ohne 2FA gehört nach Möglichkeit nicht offen ins Internet.
2. Passwort wechseln. Der Hash in dieser ZIP ist nicht gesetzt — .env.example enthält keinen. Neu erzeugen (Abschnitt 4).
3. TLS. Wenn öffentlich erreichbar: Reverse Proxy mit Zertifikat und COOKIE_SECURE=true.
4. Personenbezug. Sobald echte Kundennamen eingetippt werden, sind das personenbezogene Daten — Aufbewahrungsdauer und Löschkonzept mit der zuständigen Stelle klären. Ein Löschbefehl für alte Einträge:

   DELETE FROM sessions WHERE created_at < strftime('%s','now','-90 days');
   

---

12. Was beim letzten Umbau geändert wurde (03.08.2026)

Für den Fall, dass jemand die Vorgängerversion kennt:

• Timer laufen jetzt serverseitig statt im Browser — überleben Reload, Neustart und Gerätewechsel (vorher ging bei F5 die gesamte Zeit verloren)
• Mehrere Timer gleichzeitig, jeder mit eigenem Namen (vorher genau einer)
• Tarif serverseitig und geräteübergreifend (vorher localStorage, pro Browser unterschiedlich, und der Betrag kam vom Client)
• Historie mit Datums- und Namensfilter, Seitenweise-Nachladen, Löschen-Knopf, CSV-Export (vorher: fest 100 Einträge, kein Filter, Löschen nur über die DB)
• Anmeldung mit bcrypt statt Klartextvergleich; kein fest eingebautes Ersatzpasswort mehr im Quelltext
• Sitzungen überleben Neustarts
• HOST, COOKIE_SECURE, TRUST_PROXY, DB_PATH konfigurierbar
• Kein Google-Fonts-Abruf mehr — die Schrift kam vorher bei jedem Seitenaufruf von einem externen Server, was in Firmennetzen blockiert sein kann und datenschutzrechtlich unnötig Angriffsfläche bietet. Jetzt System-Schriften.
• Sauberes Herunterfahren bei SIGTERM, WAL-Modus, Index auf created_at

Getestet: 36 automatisierte Prüfungen (Anmeldung, Parallelbetrieb, Pause/Weiter, Neustart-Persistenz mit echtem Prozesswechsel, Speichern/Verwerfen, Tarifwechsel, CSV, Filter, Löschen, Abmelden) sowie ein Durchlauf im echten Browser.

---

13. Wenn etwas unklar ist

Die App ist klein genug, um sie vollständig zu lesen: server.js ~470 Zeilen, app.js ~460 Zeilen, beide durchgehend kommentiert und auf Deutsch beschriftet. Im Zweifel ist das Lesen der Quelle schneller als das Raten.

---

Automatischer Deploy per Gitea Actions

Jeder Push auf main in git.handy-insel.de/kerimatilgan/timer-app rollt den Stand selbsttaetig auf den Server aus. Der Workflow liegt in .gitea/workflows/deploy.yaml und laesst sich in der Gitea-Oberflaeche unter "Actions" auch von Hand starten.

Was der Workflow tut

1. Uebertraegt die versionierten Dateien als tar-Paket und entpackt sie ueber /opt/timer-app. Kein rsync: im Runner-Container verbietet der Docker-Host dessen pipe()-Aufruf, und auf dem Zielhost ist rsync nicht installiert. Nicht angefasst werden backend/.env, data/ und node_modules/ — sie liegen nicht im Repo und sind damit auch nicht im Paket. Im Repo geloeschte Dateien werden auf dem Server entfernt: die Liste kommt aus git diff gegen den zuletzt ausgerollten Commit, der als Merkzettel in /opt/timer-app/.deploy-commit liegt.
2. npm ci --omit=dev nur, wenn sich backend/package*.json geaendert hat. Das laeuft bewusst auf dem Zielhost: bcrypt und sqlite3 sind native Module und muessen zur dortigen Architektur passen.
3. Neustart des Dienstes nur, wenn sich etwas unter backend/ oder deploy/ geaendert hat. Reine Frontend-Aenderungen brauchen keinen.
4. Health-Check gegen /health (15 Versuche, 30 s). Antwortet der Dienst nicht, schlaegt der Lauf fehl und die letzten 40 Journal-Zeilen stehen im Protokoll.

Einmalige Einrichtung

Auf dem Zielhost einen Deploy-Benutzer anlegen, ihm das Verzeichnis geben und den Neustart des einen Dienstes erlauben:

useradd -r -m -s /bin/bash deploy
mkdir -p /home/deploy/.ssh && chmod 700 /home/deploy/.ssh
echo '<oeffentlicher Schluessel>' >> /home/deploy/.ssh/authorized_keys
chown -R deploy:deploy /home/deploy/.ssh && chmod 600 /home/deploy/.ssh/authorized_keys

# Der Code gehoert dem Deploy-Benutzer, der Dienst liest ihn nur.
chown -R deploy:timerapp /opt/timer-app && chmod -R g+rX /opt/timer-app

# WICHTIG: das Datenverzeichnis gehoert dem Dienst - sonst kann die
# Anwendung ihre Datenbank nicht mehr schreiben.
chown -R timerapp:timerapp /opt/timer-app/data && chmod 750 /opt/timer-app/data

# Genau die drei Befehle ohne Passwort - nicht mehr
cat > /etc/sudoers.d/deploy-timer-app <<'EOF'
deploy ALL=(root) NOPASSWD: /bin/systemctl restart timer-app, \
                            /bin/journalctl -u timer-app *
EOF
chmod 440 /etc/sudoers.d/deploy-timer-app
visudo -c

Im Repo unter Settings -> Actions hinterlegen:

Art	Name	Wert
Variable	DEPLOY_HOST	192.168.1.5
Variable	DEPLOY_USER	deploy
Variable	DEPLOY_PATH	/opt/timer-app
Variable	DEPLOY_SERVICE	timer-app
Variable	HEALTH_URL	http://127.0.0.1:3003/health
Secret	DEPLOY_SSH_KEY	privater Deploy-Schluessel (ganze Datei inkl. BEGIN/END-Zeilen)
Secret	DEPLOY_KNOWN_HOSTS	ssh-keyscan 192.168.1.5 — Zeile(n) fuer den Zielhost

Grenzen

• Die .env wird nie ausgerollt. Kommt eine neue Einstellung dazu, gehoert sie von Hand in die .env auf dem Server (Vorlage: backend/.env.example), sonst startet der Dienst nach dem Deploy womoeglich nicht.
• Es gibt keinen automatischen Rollback. Faellt der Health-Check durch, laeuft der Dienst weiter im Fehlerzustand — der Lauf ist rot und das Journal steht im Protokoll. Zurueck geht es mit einem Revert-Commit auf main.