- TypeScript 47.7%
- Go 47.4%
- CSS 3.9%
- JavaScript 0.4%
- Go Template 0.3%
- Other 0.3%
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 |
||
|---|---|---|
| backend | ||
| deploy/helm/timetracker | ||
| docs/plan | ||
| frontend | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| docker-compose.yml | ||
| Makefile | ||
| README.md | ||
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.namesetzen undsecrets.inline.dbPasswordübergeben. Nicht geheime Werte liegen in einer ConfigMap, Passwort und JWT-Secret in einem Secret. Für Produktion bessersecrets.existingSecretmit den SchlüsselnAPP_JWT_SECRETundDB_PASSWORDverwenden. - Sicherheit: Beide Pods laufen als Nutzer 65532 ohne Root-Rechte, mit read-only Root-Dateisystem (nginx schreibt nur nach
/tmp,/runund/var/lib/nginx/tmp, jeweils einemptyDir), ohne Capabilities, ohne Privilege Escalation, mitRuntimeDefault-Seccomp und ohne ServiceAccount-Token. NetworkPolicies lassen nur Frontend-Pods zum Backend. Die AbschnittesecurityContextinvalues.yamlbzw. 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.