No description
  • TypeScript 47.7%
  • Go 47.4%
  • CSS 3.9%
  • JavaScript 0.4%
  • Go Template 0.3%
  • Other 0.3%
Find a file
Jonas Leder 0e1fdd8f8b fix(deploy): give the frontend pod the writable paths nginx needs
nginx failed at start with mkdir() /var/lib/nginx/tmp/client_body (13: Permission
denied) because the root file system is read-only. Mount emptyDirs on
/var/lib/nginx/tmp, /run (the pid file; /var/run is only a symlink to it) and /tmp,
drop the unused /var/cache/nginx mount, and make CI and make lint-chart fail if one
of them goes missing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qu4xuNCkFLDByYWUrjanny
2026-11-04 15:28:58 +00:00
backend test(backend): cover locations and overtime level in the HTTP smoke test 2026-11-04 15:00:47 +00:00
deploy/helm/timetracker fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00
docs/plan feat(deploy): split non-secret chart config into ConfigMap and password into Secret 2026-11-04 14:27:09 +00:00
frontend fix(frontend): keep the session when the app starts offline 2026-11-04 14:57:03 +00:00
.gitignore ci: add gitlab pipeline for tests, images and helm chart; document deployment 2026-11-04 14:25:26 +00:00
.gitlab-ci.yml fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00
docker-compose.yml feat(deploy): split non-secret chart config into ConfigMap and password into Secret 2026-11-04 14:27:09 +00:00
Makefile fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00
README.md fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00

Zeiterfassung

Zeiterfassung nach deutschen Standards: Timer (Start/Stopp), manuelle Einträge, Urlaub, Überstundensaldo und Export als CSV oder PDF.

  • Backend: Go, Gin, Gin-Logrus, swaggo, GORM, godotenv
  • Frontend: React, Vite, TypeScript
  • Datenbanken: SQLite (Standard), MariaDB, PostgreSQL

Die Planung liegt unter docs/plan.

Funktionen

  • Öffentliche Registrierung mit Benutzername und Passwort
  • Timer mit Start/Stopp und manuelle Einträge mit Von/Bis (Überlappungen werden abgelehnt)
  • Ort pro Eintrag (Auswahl vor dem Start, z. B. Büro, Homeoffice, Dienstreise); die Orte pflegt jede:r selbst in den Einstellungen
  • Verlauf pro Monat mit Blättern durch alle Monate, Tagessummen und Nachtragen von Lücken
  • Sollzeit pro Arbeitstag einstellbar (Standard 8 h, Wochenziel 40 h, Mo–Fr)
  • Urlaub als ganze Tage, Kontingent pro Jahr (Standard 30), Wochenenden nicht buchbar
  • Überstundensaldo mit optionalem Startsaldo, Wochen- und Monatssummen
  • Warnstufen für den Überstundensaldo, pro Benutzer einstellbar: erst Gelb, dann Rot (0 schaltet eine Stufe aus)
  • Mobil nutzbar und installierbar (PWA); Zeiten lassen sich auch ohne Netz erfassen und werden später gesendet
  • Export als CSV (Semikolon, UTF-8 mit BOM, Dezimalkomma) und PDF
  • Hinweise nach dem Arbeitszeitgesetz (ArbZG): Pausenhinweis ab 8 h, Warnung über 10 h

Feiertage werden nicht berücksichtigt. Pausen werden nicht erfasst, Einträge sind Arbeitszeit.

Offline-Erfassung

Die Oberfläche funktioniert auf dem Handy auch ohne Verbindung, sobald sie einmal geladen wurde:

  • Timer starten und stoppen sowie manuelle Einträge werden in einer Warteschlange auf dem Gerät gespeichert, mit den echten Zeiten.
  • Sobald wieder eine Verbindung besteht, werden sie der Reihe nach gesendet (auch beim Öffnen der App und alle 15 Sekunden, solange etwas wartet).
  • Ein offline gestarteter und gestoppter Timer wird zu einem einzelnen Eintrag. Ein vom Server abgelehnter Eintrag (z. B. wegen einer Überschneidung) wird mit Begründung angezeigt und blockiert die übrigen nicht.
  • Bestehende Einträge bearbeiten oder löschen, Urlaub, Einstellungen und Export brauchen eine Verbindung.
  • Gesendet wird nur, solange die App geöffnet ist; ein Hintergrund-Sync gibt es nicht. Beim Abmelden mit wartenden Einträgen fragt die App nach.

Schnellstart mit Docker

cp backend/.env.example .env   # APP_JWT_SECRET setzen
docker compose up --build

Frontend: http://localhost:8080 · Swagger UI: http://localhost:8080/swagger/index.html

Die Images werden aus ihrem Unterverzeichnis gebaut (backend/Dockerfile, frontend/Dockerfile), das ist auch der Build-Kontext in der CI. Das Frontend-Image schreibt den Commit aus der Datei frontend/GIT_SHA in die Anzeige; lokal steht dort dev.

Kubernetes mit Helm

Das Chart liegt unter deploy/helm/timetracker. Es startet ein Backend-Pod und ein Frontend-Pod. Das Frontend leitet /api an den Service backend weiter, daher gilt: ein Release pro Namespace.

helm install timetracker deploy/helm/timetracker \
  --set image.backend.repository=registry.example.com/timetracker/backend \
  --set image.backend.tag=<tag> \
  --set image.frontend.repository=registry.example.com/timetracker/frontend \
  --set image.frontend.tag=<tag> \
  --set secrets.inline.jwtSecret="$(openssl rand -hex 32)" \
  --set ingress.enabled=true --set 'ingress.hosts={timetracker.example.com}'
  • SQLite (Standard): eine Datei in einem PersistentVolumeClaim unter /data. Nur ein Replica möglich, das Chart verweigert mehr.
  • PostgreSQL / MariaDB: config.database.driver, config.database.host, config.database.user, config.database.name setzen und secrets.inline.dbPassword übergeben. Nicht geheime Werte liegen in einer ConfigMap, Passwort und JWT-Secret in einem Secret. Für Produktion besser secrets.existingSecret mit den Schlüsseln APP_JWT_SECRET und DB_PASSWORD verwenden.
  • Sicherheit: Beide Pods laufen als Nutzer 65532 ohne Root-Rechte, mit read-only Root-Dateisystem (nginx schreibt nur nach /tmp, /run und /var/lib/nginx/tmp, jeweils ein emptyDir), ohne Capabilities, ohne Privilege Escalation, mit RuntimeDefault-Seccomp und ohne ServiceAccount-Token. NetworkPolicies lassen nur Frontend-Pods zum Backend. Die Abschnitte securityContext in values.yaml bzw. den Templates sind die Stelle für Anpassungen.

CI

.gitlab-ci.yml führt Go- und Frontend-Tests aus, baut beide Images (build-image), rendert und prüft das Chart (helm lint --strict, helm template) und veröffentlicht es als OCI-Chart. Der Chart-Tag ist die Pipeline-IID als Patch-Version; Image-Tags und Registry-Pfad werden in der Pipeline in values.yaml eingesetzt.

Lokale Entwicklung

Voraussetzungen: Go (siehe backend/go.mod), Node.js mit pnpm.

# Backend
cd backend
cp .env.example .env          # APP_JWT_SECRET setzen
go run ./cmd/server           # läuft auf :8080

# Frontend (zweites Terminal)
cd frontend
pnpm install
pnpm dev                      # Vite leitet /api an :8080 weiter

Konfiguration

Variable Standard Bedeutung
APP_PORT 8080 HTTP-Port
APP_JWT_SECRET – (Pflicht) Schlüssel für JWT-Tokens
APP_JWT_TTL_HOURS 24 Gültigkeit des Tokens
APP_LOG_LEVEL info debug, info, warn oder error
DB_DRIVER sqlite sqlite, mariadb oder postgres
DB_NAME timetracker.db (sqlite) / timetracker sqlite: Dateipfad; mariadb/postgres: Datenbankname
DB_HOST – Host für mariadb und postgres (Pflicht dort)
DB_PORT 3306 / 5432 Port; leer = Standard des Treibers
DB_USER timetracker Benutzer für mariadb und postgres
DB_PASSWORD – Passwort für mariadb und postgres (Geheimnis)
DB_SSLMODE disable nur postgres

Die Verbindung wird aus diesen Feldern zusammengesetzt, es gibt keinen Verbindungsstring mehr. Beispiele stehen in backend/.env.example. Für MariaDB und PostgreSQL in Docker: docker compose --profile postgres up bzw. --profile mariadb, danach DB_DRIVER, DB_HOST, DB_USER und DB_PASSWORD entsprechend setzen.

Tests

make test            # Go- und Frontend-Tests
make lint-chart      # Helm-Chart prüfen
make swagger         # Swagger-Dateien neu erzeugen

API

Alle Endpunkte liegen unter /api/v1. Die vollständige Beschreibung steht in der Swagger UI unter /swagger/index.html. Geschützte Endpunkte erwarten Authorization: Bearer <token>.

Hinweise

  • Der Export ist auf 366 Tage pro Datei begrenzt.
  • Die Zeitzone für Tage, Exporte und Anzeige ist Europe/Berlin.