Environment variables

Klokk is configured through environment variables at start-up. Everything that belongs to day-to-day operation — companies, people, rules, retention — is set in Klokk itself under Admin, not here.

Required

Without these Klokk does not start:

Variable	Purpose
ACCEPT_TERMS Required	true accepts the terms of use.
SESSION_SECRET Required	Signs sessions and links (at least 32 characters, random).
CSRF_KEY Required	Protects forms against cross-site requests (at least 32 characters, random).
DATA_KEY Required	Encrypts the database — never change or lose it.

Generate each once with openssl rand -hex 32, as in the quick start.

Setting variables

With Docker Compose, put them in an env_file or under environment:; with docker run, use --env-file or -e. Changes take effect when the container is recreated (docker compose up -d).

Secrets from files

Every variable can also come from a file — for example a Docker secret. <NAME>_FILE names the file; its content (without surrounding white space) is the value:

docker-compose.yml (excerpt)

services:
  klokk:
    environment:
      DATA_KEY_FILE: /run/secrets/klokk_data_key
      SMTP_PASS_FILE: /run/secrets/smtp_pass
    secrets: [klokk_data_key, smtp_pass]

secrets:
  klokk_data_key:
    file: ./secrets/data_key
  smtp_pass:
    file: ./secrets/smtp_pass

Setting both NAME and NAME_FILE, or a file Klokk cannot read, stops the start — so a typo never goes unnoticed.

Hardened containers

The images contain nothing but the program — no shell, no tools — and run read-only. Start them with read_only, a /tmp tmpfs, cap_drop: [ALL] and no-new-privileges, as in the examples.

All settings by topic

ApplicationPort, address, logging, licence, legal links, error reports.

DatabaseSQLite or PostgreSQL and the connection pool.

SecuritySessions, two-factor, passkeys, IP allow-lists, proxies.

Languages & defaultsLanguages, weekly hours and vacation days for new people, shift reminders.

SMTP (Email)Sending e-mail through your mail server.