Dokumentation

Anwendung

Datenbank

SicherheitErforderlich

Authentifizierung

Admin-Zugriffskontrolle

Passwortrichtlinie

Rate-Limiting

Internationalisierung

Arbeitszeit-Standardwerte

Wird beim ersten Start auf den Admin-Seed-Nutzer angewendet. Pro-Nutzer-Werte werden danach in der App verwaltet.

Schichtplanung

Die Schichtplanung selbst wird pro Firma in der App aktiviert (Admin → Companies), nicht über Umgebungsvariablen. Siehe Schichtplanung unten für den vollständigen Ablauf. Die einzige serverseitige Einstellung ist die Push-Erinnerung vor Schichtbeginn:

SMTP (E-Mail)

API & Erweiterungen

Klokk bietet eine schreibgeschützte öffentliche REST-API unter /api/v1/*(/status, /users,/clock/states, /time/entries,/companies). Anfragen werden mit einem API-Schlüssel authentifiziert und pro Scope autorisiert (z. B. read:users, read:time_entries) und auf 60 Anfragen pro Minute und IP begrenzt.

Super-Admins verwalten Integrationen unter API & Erweiterungen(/admin/extensions). Jede Integration bündelt einen API-Schlüssel, seine Scopes und einen Verbindungsmodus:

• Nur API — die Erweiterung ruft die obige REST-API mit ihrem Schlüssel auf.
• Webhooks — Klokk sendet bei Ein-/Ausstempeln und Abwesenheitsereignissen ausgehende HTTP-POSTs.
• WebSocket — die Erweiterung öffnet eine dauerhafte eingehende Verbindung unter GET /api/v1/extension/connect.

Mit EXTENSIONS_ENABLED=false wird das Erweiterungs-Subsystem auf Netzwerkebene abgeschaltet. Die oben aufgeführten schreibgeschützten REST-API-Endpunkte bleiben verfügbar; nur die Webhook-/WebSocket-Funktionen unten werden deaktiviert.

a. Schichten aktivieren

Ein Super-Admin aktiviert die Funktion pro Firma unter Admin → Companies:

• Schichtplanung — aktiviert Schichtvorlagen und Dienstpläne für die Firma.
• Ankündigungsfrist Dienstplan (Tage) — erforderliche Vorlaufzeit, bevor ein Dienstplan veröffentlicht werden darf (z. B. aus einem Tarif- oder Betriebsvereinbarung). 0 = keine. Der Planer sieht einen „Veröffentlichen bis"-Hinweis und eine Warnung, sobald die Frist abgelaufen ist.

Nach der Aktivierung erscheint für Admins und Manager ein Eintrag Schichten und für jeden Mitarbeitenden ein Eintrag Meine Schichten.

b. Arbeitszeitmodell

Die täglichen Sollstunden jedes Nutzers ergeben sich aus seinem Arbeitszeitmodell:

• Wöchentlich — feste/flexible Wochenstunden aus dem Arbeitszeitplan (Standard).
• Schichtbasiert — die Sollstunden werden statt aus Wochenstunden aus dem veröffentlichten Dienstplan abgeleitet.
• Erben — den Abteilungsstandard nutzen, dann auf wöchentlich zurückfallen.

Pro Nutzer unter Admin → Users einstellen oder als Abteilungsstandard unter Admin → Departments. Nur schichtbasierte Nutzer sind vom Dienstplan betroffen; wöchentliche Nutzer behalten ihren Plan.

c. Vorlagen & Dienstplan

Vorlagen sind wiederverwendbare Schichtdefinitionen (z. B. „Früh 06:00–14:00"), die unter Schichten angelegt werden. Jede hat einen Namen, Start- und Endzeit (liegt das Ende nicht nach dem Start, geht die Schicht über Mitternacht, z. B. 22:00–06:00), eine Pause in Minuten (wird vom Brutto abgezogen und ergibt die bezahlte Nettozeit), eine Farbe für das Raster und ein Aktiv-Kennzeichen. Schichten im gesetzlichen Nachtzeitfenster (23:00–06:00) werden für die ArbZG-Prüfungen automatisch erkannt.

Der Dienstplan ist ein Wochenraster aus Mitarbeitenden × Tagen. Weisen Sie pro Zelle eine Vorlage zu, fügen Sie eine optionale Notiz hinzu und nutzen Sie Vorwoche kopieren, um einen wiederkehrenden Plan zu übernehmen. Entwürfe sind für Mitarbeitende unsichtbar und beeinflussen die Sollstunden nicht. Wenn fertig, wählen Sie Veröffentlichen & benachrichtigen: Die Zuweisungen werden in Meine Schichten sichtbar, speisen die schichtbasierten Sollstunden, benachrichtigen betroffene Mitarbeitende (E-Mail und/oder Push, je nach Einstellung) und zeigen jedem Mitarbeitenden eine genaue Änderungsübersicht gegenüber der zuletzt veröffentlichten Version.

d. Tausch, offene Schichten & Verfügbarkeit

• Schichttausch (Abgabe). Aus Meine Schichten gibt ein Mitarbeitender eine veröffentlichte Schicht ab; ein Kollege übernimmt sie und ein Manager/Admin genehmigt die Neuzuweisung (offen → übernommen → genehmigt oder abgelehnt/zurückgezogen). Nur ein genehmigter Tausch verschiebt die Zuweisung.
• Offene Schichten. Ein Planer bietet einen nicht zugewiesenen Slot dem Pool an; Mitarbeitende bewerben sich und ein Manager genehmigt, wodurch er zu einer normalen Zuweisung wird (offen → übernommen → besetzt).
• Verfügbarkeit. Mitarbeitende markieren Tage als Nicht verfügbar oder Bevorzugt (kein Eintrag = keine Präferenz). Wird jemand an einem als nicht verfügbar markierten Tag eingeteilt, kennzeichnet der Dienstplan einen Konflikt.

e. Mitarbeiteransicht, Kalender & Erinnerungen

Meine Schichten zeigt dem Mitarbeitenden den eigenen veröffentlichten Dienstplan als Woche oder Monat; er kann den Plan bestätigen („Ich habe meine Schichten gesehen") und von hier aus Verfügbarkeiten, Tausch und Bewerbungen auf offene Schichten verwalten.

Kalender-Abo. Mitarbeitende können einen Kalender-Feed aktivieren und die erzeugte iCalendar-URL (/shifts/feed/<token>) in jeder Kalender-App abonnieren; er aktualisiert sich automatisch, und beim Deaktivieren wird der Link ungültig.

Erinnerungen vor Schichtbeginn. Setzen Sie SHIFT_REMINDER_HOURS (siehe Schichtplanung unter den Umgebungsvariablen), um so viele Stunden vor Schichtbeginn eine Erinnerung zu senden — einmal pro Schicht, an Mitarbeitende, die die Push-Benachrichtigung „Schichtplan veröffentlicht oder geändert" aktiviert haben.

ArbZG-Audit. Klokk prüft Dienstpläne gegen das Arbeitszeitgesetz — Tages-/Wochenhöchstgrenzen, die 11-stündige Ruhezeit und Nachtarbeitsregeln — und die Ansicht Jährliches ArbZG-Audit bietet eine Compliance-Übersicht pro Mitarbeitenden über das ganze Jahr.

Erweiterungen sind externe Dienste, die über das API- & Erweiterungssystem von Klokk angebunden werden: eine scope-basierte, schreibgeschützte REST-API, ausgehende Webhooks und eingehende WebSocket-Verbindungen. Die Konfigurationsvariablen finden sich unterAPI & Erweiterungen oben; dieser Abschnitt behandelt den Ablauf in der App und die hauseigenen Erweiterungen.

a. Nutzung in der App

Ein Super-Admin verwaltet Integrationen unter Admin → API & Erweiterungen (/admin/extensions). Jede Integration bündelt einenAPI-Schlüssel (nur einmal angezeigt — sicher aufbewahren), die nutzbaren Scopes und einen Verbindungsmodus:

• Nur API — die Erweiterung fragt die REST-API mit ihrem Schlüssel ab (/api/v1/status, /users, /clock/states, /time/entries, /shifts/events, /companies); begrenzt auf 60/min pro IP.
• Webhooks — Klokk sendet bei Ein-/Ausstempeln und Abwesenheitsereignissen ausgehende HTTP-POSTs.
• WebSocket — die Erweiterung öffnet eine dauerhafte eingehende Verbindung unter GET /api/v1/extension/connect.

Scopes (z. B. read:users, read:time_entries, read:companies) autorisieren jeden Schlüssel; vergeben Sie nur, was eine Erweiterung benötigt. Die öffentliche API ist schreibgeschützt. EXTENSIONS_ENABLED=false entfernt die Admin-Routen, den WebSocket-Endpunkt und alle Webhooks (die einfache REST-API bleibt verfügbar).

b. Klokk Anchor

Klokk Anchor ist ein Begleitdienst, der täglich einen manipulationssicheren Nachweis Ihrer Zeiterfassungsdaten in dieIOTA-Rebased-(Starfish-)Blockchain schreibt. Jedes Ereignis wird auf ein einseitiges SHA-256-Commitment reduziert und in einem Merkle-Baum zusammengefasst; nur die tägliche Merkle-Wurzel wird verankert, sodass keine personenbezogenen Daten in Richtung Chain gelangen. Optional wird ein vertrauenswürdiger Zeitstempel nach RFC 3161 ergänzt.

Voraussetzungen: ein laufendes Klokk mit EXTENSIONS_ENABLED=true; ein Klokk-API-Schlüssel mit den Scopes read:time_entries und read:companies; sowie zwei 32-Byte-Hex-Geheimnisse (eines für die Verschlüsselung im Ruhezustand, eines für das Hashing der Firmen-Token). Für das Mainnet eine finanzierte IOTA-Wallet (in der Anchor-Oberfläche erstellt); der Anchor-Smart-Contract von Klokk ist als Standard eingebaut.

Image: klokkme/anchor / ghcr.io/klokk-me/anchor (Tags stable, latest). PostgreSQL wird über DATABASE_URL unterstützt.

services:
  klokk-anchor:
    image: klokkme/anchor:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:9090:9090"
    volumes:
      - anchor-data:/app/data
    environment:
      KLOKK_BASE_URL: "https://klokk.example.com"
      KLOKK_API_KEY: "klokk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      DATABASE_URL: "sqlite:/app/data/klokk-anchor.db"
      ENCRYPTION_KEY: "change-me-openssl-rand-hex-32"
      COMPANY_TOKEN_PEPPER: "change-me-openssl-rand-hex-32"
      IOTA_NETWORK: "testnet"
      TZ: "Europe/Berlin"
      TIMEZONE: "Europe/Berlin"

volumes:
  anchor-data:

services:
  klokk-anchor:
    image: klokkme/anchor:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:9090:9090"
    environment:
      KLOKK_BASE_URL: "https://klokk.example.com"
      KLOKK_API_KEY: "klokk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      DATABASE_URL: "postgresql://klokk:klokk@postgres:5432/klokk_anchor"
      ENCRYPTION_KEY: "change-me-openssl-rand-hex-32"
      COMPANY_TOKEN_PEPPER: "change-me-openssl-rand-hex-32"
      IOTA_NETWORK: "testnet"
      TZ: "Europe/Berlin"
      TIMEZONE: "Europe/Berlin"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: klokk_anchor
      POSTGRES_USER: klokk
      POSTGRES_PASSWORD: klokk
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U klokk -d klokk_anchor"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

Umgebungsvariablen

c. Klokk Ledger

Klokk Ledger ist ein unabhängiger Indexer- und Verifizierungsdienst. Er liest Klokk-Anchor-Nachweise aus dem öffentlichen IOTA-Ledger zurück, speichert sie und stellt eine schreibgeschützte Verifizierungs-API bereit — sodass jeder einen Nachweis prüfen kann, ohne dem Betreiber zu vertrauen, und selbst dann, wenn der Ledger-Knoten alte Transaktionen später entfernt. Er benötigt keinen API-Schlüssel und keine Geheimnisse; er liest nur öffentliche Daten und füllt beim ersten Lauf die vollständige Package-Historie automatisch nach.

Image: klokkme/ledger / ghcr.io/klokk-me/ledger (Tags stable, latest). SQLite ist reines Go (kein CGO); PostgreSQL optional.

services:
  klokk-ledger:
    image: klokkme/ledger:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ledger-data:/app/data
    environment:
      IOTA_NETWORK: "mainnet"
      IOTA_ANCHOR_PACKAGE: "0x..."   # dasselbe Package, in das dein Anchor schreibt
      DB_DRIVER: "sqlite"
      DB_DSN: "data/klokk-ledger.db"
      POLL_INTERVAL: "60s"

volumes:
  ledger-data:

services:
  klokk-ledger:
    image: klokkme/ledger:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      IOTA_NETWORK: "mainnet"
      IOTA_ANCHOR_PACKAGE: "0x..."   # dasselbe Package, in das dein Anchor schreibt
      DB_DRIVER: "postgres"
      DB_DSN: "postgres://klokk:klokk@postgres:5432/klokk_ledger?sslmode=disable"
      POLL_INTERVAL: "60s"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: klokk_ledger
      POSTGRES_USER: klokk
      POSTGRES_PASSWORD: klokk
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U klokk -d klokk_ledger"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

Umgebungsvariablen

Verifizierungs-API

Alle Endpunkte sind offen verfügbar. GET /api/v1/verify/{tx}?root=<expected> liefert den unabhängig indexierten Nachweis und ob er der erwarteten Merkle-Wurzel entspricht — dieselbe Gegenprüfung, die Klokk Anchor über LEDGER_URLS durchführt.

a. Aktivieren — Firma & Abteilungen

Zwei Schalter müssen zusammenpassen, bevor ein Nutzer die Projektzeiterfassung sieht:

• Firma (Hauptschalter). Ein Super-Admin aktiviert Projektzeiterfassung pro Firma unter Admin → Firmen. Ist er aus, existieren keine Projekt-Oberflächen, -Routen oder -Stempelfunktionen.
• Abteilung (Opt-in). Bei aktivem Firmenschalter wird jede Abteilung einzeln unter Admin → Abteilungen freigeschaltet (Projektzeit für diese Abteilung). Opt-in: eine neue Abteilung ist aus, bis sie freigeschaltet wird. Ein Nutzer mit Abteilung benötigt deren Freischaltung; Nutzer ohne Abteilung folgen dem Firmenschalter.

Sobald ein Nutzer qualifiziert ist, erscheint der Eintrag Projekte und das Stempel-Widget erhält Projekt-Bedienelemente. Upgrades bleiben funktionsfähig: Eine einmalige Migration schaltet die bestehenden Abteilungen jeder Firma frei, die Projekte bereits aktiviert hatte.

b. Berechtigung für private Projekte

Neben firmenweiten Projekten können Nutzer eigene private Projekte führen. Ob sie diese anlegen dürfen, steuert ein firmenweiter Standard (Admin → Firmen → Private Projekte standardmäßig erlauben), der pro Nutzer überschrieben werden kann (Admin → Nutzer: Firmenstandard / Erlauben / Sperren). Ist es gesperrt, wird das Formular „Neues privates Projekt" ausgeblendet und das Anlegen abgewiesen; bestehende private Projekte bleiben nutzbar.

c. Projekte & Sichtbarkeit

Admins verwalten Projekte unter Admin → Projekte (/admin/projects). Jedes Projekt hat einen Namen, optional Nummer und Kunde, eine Abteilung, ein Aktiv-Kennzeichen und eine Sichtbarkeit von Firma (für alle buchbar) oder Persönlich. Archivierte Projekte bleiben an historischen Einträgen, sind aber nicht mehr buchbar. Eigene private Projekte verwalten Nutzer unter Projekte (/projects).

d. Buchen, Umbuchen & Auswertung

Über das Stempel-Widget (oder die Projekte-Seite im eingestempelten Zustand) kann ein Mitarbeiter ein Projekt starten, zu einem anderen wechseln (das laufende Segment schließt, das nächste öffnet) oder die Projektarbeit stoppen und dabei eingestempelt bleiben. So entsteht eine Kette von Segmenten, die den Arbeitstag exakt ausfüllt; gestempelte, aber nicht zugeordnete Zeit erscheint unter Nicht zugewiesene Projektzeiten zur späteren Zuordnung.

Da ein Projektsegment nur Metadaten auf bereits genehmigter Arbeitszeit ist, löst das Umbuchen eines Segments auf ein anderes Projekt keine neue Genehmigung aus — die Stunden waren bereits gezählt. Admins erhalten eine projektbezogene Auswertung (/admin/projects/report, CSV-Export) mit Summen nach Projekt, Kunde und Zeitraum. Die öffentliche Erweiterungs-API liefert dieselben segmentierten Einträge über read:time_entries, und Klokk Anchor bindet jedes Segment in seinen täglichen Nachweis ein — so ist auch die Projektaufteilung manipulationssicher verankert.