Quick Start

The quickest way to run Klokk is a single container with SQLite — no separate database server. All data lives in one volume. For larger installations Klokk also runs on PostgreSQL.

What you need

• A server or computer with Docker (or Docker Compose).
• Outbound HTTPS to licensing.klokk.me: Klokk checks its licence on start-up and once a day. If the server cannot be reached, Klokk keeps running on the last confirmed status for up to 14 days. What is transmitted is listed in the privacy policy.
• For use beyond a test: a domain and a reverse proxy with HTTPS.

Start Klokk

1. Create the secrets. Three random values, generated once and kept safe:

   cat > klokk.env <<END
   ACCEPT_TERMS=true
   SESSION_SECRET=$(openssl rand -hex 32)
   CSRF_KEY=$(openssl rand -hex 32)
   DATA_KEY=$(openssl rand -hex 32)
   END
   chmod 600 klokk.env

   ACCEPT_TERMS=true accepts the terms of use; without it Klokk does not start and logs the link instead.

2. Start the container.

   docker run

   docker run -d \
     --name klokk \
     -p 8080:8080 \
     -v klokk-data:/app/data \
     --env-file klokk.env \
     -e BASE_URL=http://localhost:8080 \
     -e SESSION_SECURE_COOKIE=false \
     --read-only --tmpfs /tmp \
     --cap-drop ALL --security-opt no-new-privileges \
     klokkme/klokk:stable

   Docker Compose

   docker-compose.yml

   services:
     klokk:
       image: klokkme/klokk:stable
       restart: unless-stopped
       read_only: true
       tmpfs:
         - /tmp
       cap_drop: [ALL]
       security_opt:
         - no-new-privileges:true
       pids_limit: 200
       ports:
         - "8080:8080"
       volumes:
         - klokk-data:/app/data
       env_file: klokk.env
       environment:
         BASE_URL: "http://localhost:8080"
         SESSION_SECURE_COOKIE: "false"
   
   volumes:
     klokk-data:

   docker compose up -d

   SESSION_SECURE_COOKIE=false is only for trying Klokk over plain HTTP. Behind a reverse proxy with HTTPS, leave it out and set BASE_URL to the public address (for example https://time.example.com).

3. Read the one-time password. On the very first start Klokk creates the account admin and prints a one-time password once in its log:

   docker logs klokk 2>&1 | grep -A1 "one-time password"

   If you prefer to choose it, set DEFAULT_ADMIN_PASSWORD before the first start.

4. Sign in at http://localhost:8080 with the username admin (or admin@localhost) and that password. Klokk then asks for:

   • a personal password, and
   • two-factor authentication — mandatory for admins: scan the QR code with an authenticator app and keep the recovery codes.

Never change or lose DATA_KEY

DATA_KEY encrypts the database. Without it the database cannot be opened any more — not even from a backup. Keep it apart from the backups, for example in a password manager. Never use example values from guides — they are public. More in Encryption.

First steps in Klokk

As super admin (admin) you set up the installation:

1. Create the company under Admin → Companies: name, country and state (for public holidays), weekly hours, vacation rules and the absence types it uses.

2. Add people under Admin → Users — one by one or imported from a CSV file. Each gets a role: user, manager, admin (of the company) or auditor.

3. Hand over HR settings to the company’s admins: they manage requests, month-end closing, the company calendar and more for their company.

4. Set up e-mail (SMTP) so people receive invitations, password resets and notifications.

Updating

Klokk updates by pulling the new image and recreating the container; the database is migrated on start-up.

docker pull klokkme/klokk:stable
docker rm -f klokk   # the data stays in the volume
# then start it again as above

With Compose: docker compose pull && docker compose up -d. Before every update, read the release notes — in Klokk behind the version in the page footer (“What’s new”) or on klokk.me/changelog. They say when something must be done before updating.

Next steps

• Docker images: tags and update notices.
• Reverse proxy: HTTPS with nginx or Caddy.
• Environment variables: everything that can be configured.