Documentation

Application

Database

Security Required

Authentication

Admin Access Control

Password Policy

Rate Limiting

Internationalisation

Working Time Defaults

Applied to the admin seed user on first startup. Per-user values are managed in the app afterwards.

Shift Planning

Shift planning itself is enabled per company in the app (Admin → Companies), not via environment variables. See Shift Planning below for the full workflow. The one server-level setting is the pre-shift push reminder:

SMTP (Email)

API & Extensions

Klokk ships a read-only public REST API under /api/v1/* (/status, /users, /clock/states, /time/entries, /companies). Requests are authenticated with an API key and authorised per scope (e.g. read:users, read:time_entries), and rate-limited to 60 requests per minute per IP.

Super-admins manage integrations under API & Extensions (/admin/extensions). Each integration bundles an API key, its scopes, and one connection mode:

• API only — the extension calls the REST API above using its key.
• Webhooks — Klokk sends outbound HTTP POSTs on clock-in, clock-out, and leave events.
• WebSocket — the extension opens a persistent inbound connection at GET /api/v1/extension/connect.

Set EXTENSIONS_ENABLED=false to switch off the extension subsystem at the network level. The read-only REST API endpoints listed above remain available; only the webhook/WebSocket extension features below are disabled.

a. Enabling shifts

A super-admin turns the feature on per company under Admin → Companies:

• Shift planning — enables shift templates and rosters for the company.
• Roster notice period (days) — advance notice required before a roster may be published (e.g. from a collective or works agreement). 0 = none. The planner sees a "publish by" hint and a warning once the period has passed.

Once enabled, a Shifts entry appears for admins and managers, and a My shifts entry for every employee.

b. Work-time model

Each user's daily target hours come from their work-time model:

• Weekly — fixed/flexible weekly hours from the work schedule (the default).
• Shift-based — target hours are derived from the published roster instead of weekly hours.
• Inherit — use the department default, then fall back to weekly.

Set it per user under Admin → Users, or as a department default under Admin → Departments. Only shift-based users are affected by the roster; weekly users keep their schedule.

c. Templates & roster

Templates are reusable shift definitions (e.g. "Früh 06:00–14:00") created under Shifts. Each has a name, start and end time (if the end is not after the start, the shift crosses midnight, e.g. 22:00–06:00), a break in minutes (subtracted from the gross to give paid net time), a colour for the grid, and an active flag. Shifts in the statutory night window (23:00–06:00) are detected automatically for the ArbZG checks.

The roster is a weekly grid of employees × days. Assign a template per cell, add an optional note, and use Copy previous week to carry a recurring plan forward. Drafts are invisible to employees and do not affect target hours. When ready, choose Publish & notify: assignments become visible in My shifts, feed shift-based target hours, notify affected employees (email and/or push, per their preferences), and show each employee a precise change diff versus the last published version.

d. Swaps, open shifts & availability

• Shift swaps (give-away). From My shifts an employee gives away a published shift; a colleague takes it over and a manager/admin approves the reassignment (open → claimed → approved, or rejected/withdrawn). Only an approved swap moves the assignment.
• Open shifts. A planner offers an unassigned slot to the pool; employees apply and a manager approves, turning it into a normal assignment (open → claimed → filled).
• Availability. Employees mark days Unavailable or Preferred (no entry = no preference). Assigning someone on a day they marked unavailable flags a conflict on the roster.

e. Employee view, calendar & reminders

My shifts shows the employee's own published roster as a week or month; they can acknowledge the plan ("I have seen my shifts") and manage availability, swaps and open-shift applications from here.

Calendar subscription. Employees can enable a calendar feed and subscribe to the generated iCalendar URL (/shifts/feed/<token>) from any calendar app; it auto-updates, and disabling it revokes the link.

Pre-shift reminders. Set SHIFT_REMINDER_HOURS (see Shift Planning under environment variables) to push a reminder that many hours before a shift starts — once per shift, to employees who enabled the "Shift plan published or changed" push notification.

ArbZG audit. Klokk checks rosters against the German Working Time Act — daily/weekly maximums, the 11-hour rest period, and night-work rules — and the Yearly ArbZG audit view gives a per-employee, full-year compliance overview.

Extensions are external services that integrate with Klokk through its API & extension system: a scoped, read-only REST API, outbound webhooks, and inbound WebSocket connections. The configuration variables live in API & Extensions above; this section covers the in-app workflow and the first-party extensions.

a. In-app usage

A super-admin manages integrations under Admin → API & Extensions (/admin/extensions). Each integration bundles an API key (shown once — store it securely), the scopes it may use, and one connection mode:

• API only — the extension polls the REST API using its key (/api/v1/status, /users, /clock/states, /time/entries, /shifts/events, /companies); rate-limited to 60/min per IP.
• Webhooks — Klokk sends outbound HTTP POSTs on clock-in, clock-out and leave events.
• WebSocket — the extension opens a persistent inbound connection at GET /api/v1/extension/connect.

Scopes (e.g. read:users, read:time_entries, read:companies) authorise each key; grant only what an extension needs. The public API is read-only. Setting EXTENSIONS_ENABLED=false removes the admin routes, the WebSocket endpoint and all webhooks (the plain REST API stays available).

b. Klokk Anchor

Klokk Anchor is a companion service that writes a daily, tamper-evident proof of your time-tracking data to the IOTA Rebased (Starfish) blockchain. Each event is reduced to a one-way SHA-256 commitment combined into a Merkle tree; only the daily Merkle root is anchored, so no personal data ever leaves toward the chain. Optionally adds an RFC 3161 trusted timestamp.

Prerequisites: a running Klokk with EXTENSIONS_ENABLED=true; a Klokk API key with the read:time_entries and read:companies scopes; and two 32-byte hex secrets (one for at-rest encryption, one for company-token hashing). For mainnet, a funded IOTA wallet (created in the anchor UI); Klokk's anchor smart contract is the built-in default.

Image: klokkme/anchor / ghcr.io/klokk-me/anchor (tags stable, latest). PostgreSQL is supported via DATABASE_URL.

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:

Environment variables

c. Klokk Ledger

Klokk Ledger is an independent indexer and verification service. It reads Klokk Anchor proofs back off the public IOTA ledger, stores them, and serves a read-only verification API — so anyone can verify a proof without trusting the operator, and even if the ledger node later prunes old transactions. It needs no API key and no secrets; it only reads public data, and on first run backfills the full package history automatically.

Image: klokkme/ledger / ghcr.io/klokk-me/ledger (tags stable, latest). SQLite is pure-Go (no 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..."   # same package your anchor writes to
      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..."   # same package your anchor writes to
      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:

Environment variables

Verification API

All endpoints are served openly. GET /api/v1/verify/{tx}?root=<expected> returns the independently-indexed proof and whether it matches the expected Merkle root — the same cross-check Klokk Anchor performs via LEDGER_URLS.