Seit dem EuGH-Urteil C-55/18 (Mai 2019) und dem BAG-Beschluss 1 ABR 22/21 (September 2022) steht fest: Arbeitgeber in Deutschland sind verpflichtet, Arbeitszeiten ihrer Mitarbeiter objektiv und verlässlich zu erfassen. Der Koalitionsvertrag 2025 von CDU/CSU-SPD sieht zudem eine gesetzliche Verankerung dieser Pflicht vor. Wer dieser Anforderung mit einem selbstgehosteten, DSGVO-konformen Werkzeug nachkommen will, trifft mit Kimai eine ausgezeichnete Wahl: Das deutsche Open-Source-Projekt (AGPL-3.0, aktiv seit 2006, Version 2.60.0 im Juni 2026) liefert Multi-User-Zeiterfassung, Projektverwaltung, Rechnungsstellung und Auswertungen – und läuft auf jedem Synology NAS mit Intel- oder AMD-CPU sauber in Docker. Diese Anleitung zeigt den vollständigen Weg über den Container Manager mit einem sorgfältig abgesicherten Compose-Projekt.

Voraussetzungen

Synology NAS mit Intel- oder AMD-CPU (x86_64) – ARM-NAS: siehe FAQ
DSM 7.2 oder neuer mit installiertem Container Manager
Mindestens 2 GB freier RAM (Kimai + MariaDB) und 2 GB Speicherplatz
Internetzugang auf dem NAS (für den Image-Download)
Optional: eigene Domain oder Synology-DDNS für HTTPS per Reverse Proxy
Optional: SMTP-Zugangsdaten für E-Mail-Benachrichtigungen

Schritt 1: Ordnerstruktur anlegen

Öffne die File Station in DSM und lege unter /volume1/docker den Ordner kimai mit drei Unterordnern an:

/volume1/docker/kimai/
├── data/       ← persistente Kimai-Daten (Dokumente, Exporte, Anhänge)
├── plugins/    ← installierte Plugins
└── db/         ← MariaDB-Datenbankdateien

Alternativ per SSH (Details: SSH auf dem Synology NAS aktivieren und verbinden):

mkdir -p /volume1/docker/kimai/{data,plugins,db}

Warum drei getrennte Volumes? Die Trennung von Anwendungsdaten, Plugins und Datenbankdateien ermöglicht selektive Backups und sauberere Updates. Kimai-Daten und Datenbankdateien in einem einzigen Volume zu mischen wäre bei Migrations-Rollbacks problematisch.

Verifizieren: In der File Station müssen die drei Ordner data, plugins und db unter /volume1/docker/kimai sichtbar sein. Per SSH: ls /volume1/docker/kimai/ zeigt alle drei Verzeichnisse.

Schritt 2: APP_SECRET generieren

Kimai benötigt zwingend ein kryptografisch starkes APP_SECRET – ein Symfony-Verschlüsselungsschlüssel, der nach dem Erststart nicht mehr geändert werden darf (alle Sessions würden invalidiert). Generiere einen 64-Zeichen-Hex-String per SSH auf dem NAS oder einem anderen Linux-System:

openssl rand -hex 32

Die Ausgabe sieht beispielsweise so aus:

a3f8c2d1e9b047563a2e1f8d4c7b0e92f1a5d3c8e2b047a69f1c3d5e8b2a4f7

Kopiere diesen Wert – du benötigst ihn im nächsten Schritt. Wer keinen SSH-Zugang hat, kann den String auch unter Linux oder macOS in einem Terminal generieren; Windows-Nutzer verwenden PowerShell: [System.BitConverter]::ToString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).Replace("-","").ToLower().

Verifizieren: Der generierte String muss genau 64 Hexadezimal-Zeichen (0–9, a–f) enthalten. echo -n "DEIN_STRING" | wc -c muss 64 ausgeben.

Schritt 3: Compose-Projekt im Container Manager anlegen

Öffne im DSM den Container Manager, wechsle zu Projekt und klicke auf Erstellen. Wähle als Pfad /volume1/docker/kimai und gib dem Projekt den Namen kimai. Eine ausführliche Erklärung zum Anlegen von Compose-Projekten findest du hier: Container Manager auf dem Synology NAS: Docker-Compose-Projekt anlegen, starten und aktualisieren.

Füge folgenden Inhalt als compose.yaml ein. Ersetze dabei drei Werte mit deinen eigenen (markiert mit Kommentaren):

Parameter	Wert / Hinweis
Image (Kimai)	`kimai/kimai2:stable` (aktueller Stable-Tag, amd64 only)
Image (DB)	`mariadb:10.11` (LTS, Synology-kompatibel)
Port	`9805:8001` (extern 9805, intern 8001)
APP_SECRET	64-Zeichen-Hex-String aus Schritt 2
DATABASE_URL	serverVersion muss `-MariaDB`-Suffix enthalten
ADMINMAIL / ADMINPASS	Nur beim Erststart wirksam; danach entfernen

services:
  kimai-db:
    image: mariadb:10.11
    container_name: kimai-db
    hostname: kimai-db
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s
    environment:
      - TZ=Europe/Berlin
      - MYSQL_ROOT_PASSWORD=KimaiRootPass2024
      - MYSQL_DATABASE=kimai
      - MYSQL_USER=kimaiuser
      - MYSQL_PASSWORD=KimaiDbPass2024
    volumes:
      - /volume1/docker/kimai/db:/var/lib/mysql
    restart: unless-stopped

  kimai:
    image: kimai/kimai2:stable
    container_name: kimai
    depends_on:
      kimai-db:
        condition: service_healthy
        restart: true
    volumes:
      - /volume1/docker/kimai/data:/opt/kimai/var/data
      - /volume1/docker/kimai/plugins:/opt/kimai/var/plugins
    ports:
      - 9805:8001
    environment:
      - TZ=Europe/Berlin
      - APP_SECRET=HIER_DEN_64_ZEICHEN_STRING_AUS_SCHRITT_2_EINTRAGEN
      - DATABASE_URL=mysql://kimaiuser:KimaiDbPass2024@kimai-db/kimai?charset=utf8mb4&serverVersion=10.11.4-MariaDB
      - ADMINMAIL=admin@example.com
      - ADMINPASS=AdminPasswort2024
      - MAILER_FROM=kimai@example.com
      - MAILER_URL=null://localhost
      - TRUSTED_PROXIES=nginx,localhost,127.0.0.1
    restart: unless-stopped

Wichtige Hinweise zur Konfiguration:

DB-Passwörter ohne Sonderzeichen: Das Passwort in DATABASE_URL darf keine URL-kodierungspflichtigen Zeichen (@, #, %, &) enthalten – sonst schlägt das URL-Parsing fehl. Bleibe bei alphanumerischen Zeichen und Bindestrichen.
serverVersion: Der Suffix -MariaDB im Versions-String ist Pflicht. Ohne ihn meldet Symfony eine falsche Datenbankversion und bricht mit Integritätsfehler ab.
charset=utf8mb4: Gegenüber dem veralteten utf8 ermöglicht utf8mb4 den vollen Unicode-Umfang (inklusive Emojis in Projektnamen) und verhindert Datenbankfehler bei bestimmten Zeichen.
depends_on mit condition: service_healthy: Kimai startet erst, wenn MariaDB den Healthcheck besteht. Ohne diese Absicherung würde Kimai beim Start mit „Connection refused“ scheitern.

Verifizieren: Der Container Manager zeigt das Projekt kimai mit zwei Diensten (kimai-db und kimai). Beide müssen den Status Wird ausgeführt erreichen – kimai startet erst, nachdem kimai-db gesund ist. Das dauert beim ersten Start 2–3 Minuten (Image-Download + DB-Initialisierung).

Nach dem Start führt Kimai automatisch alle Datenbankmigrationen durch. Überprüfe per SSH, ob sie erfolgreich abgeschlossen wurden:

docker logs kimai 2>&1 | grep -i 'migrat'

Eine erfolgreiche Ausgabe enthält Zeilen wie:

Migrations: 0 skipped, 42 executed, 0 failed
All database migrations have been applied!

Tauchen failed-Einträge auf, schau dir das vollständige Log an (docker logs kimai 2>&1 | tail -50) – häufigste Ursache ist ein falscher serverVersion-Wert (siehe Troubleshooting).

Öffne anschließend im Browser http://NAS-IP:9805 und melde dich mit der im Compose-File eingetragenen ADMINMAIL und ADMINPASS an. Das Kimai-Dashboard sollte erscheinen.

Verifizieren: Das Kimai-Dashboard ist im Browser sichtbar. Unter Administration → Benutzer existiert der Admin-Account mit der eingetragenen E-Mail-Adresse. Falls der Login fehlschlägt, prüfe docker logs kimai 2>&1 | grep -i 'admin' auf Hinweise zur Admin-Erstellung.

Schritt 5: Ersten Mandanten, Kunden und Projekt anlegen

Nach dem Login richtest du die Grundstruktur für deine Zeiterfassung ein:

Kunden anlegen: Administration → Kunden → Neu. Trage Kundenname, Währung (EUR) und Zeitzone (Europe/Berlin) ein.
Projekt anlegen: Administration → Projekte → Neu. Wähle den soeben angelegten Kunden, vergib einen Projektnamen und trage optional ein Budget ein.
Tätigkeit anlegen: Administration → Tätigkeiten → Neu. Beispiel: „Beratung“, „Entwicklung“ oder „Support“ – jeweils mit einem Stundensatz.

Starte jetzt eine erste Zeitmessung: Klicke auf den Start-Button oben rechts, wähle Projekt und Tätigkeit und stoppe die Uhr nach einigen Sekunden. Kimai protokolliert den Eintrag mit Start- und Endzeit sowie berechneter Dauer.

Verifizieren: Unter Meine Zeiten erscheint der Zeiterfassungseintrag mit korrekter Dauer und zugeordnetem Projekt. Unter Administration → Auswertungen ist der Eintrag ebenfalls sichtbar. Damit ist die End-to-End-Funktion bestätigt.

Schritt 6: Firewall-Port freigeben

Damit Kimai aus dem lokalen Netzwerk erreichbar ist, musst du Port 9805 in der DSM-Firewall freigeben. Eine detaillierte Anleitung: DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben.

Öffne DSM → Systemsteuerung → Sicherheit → Firewall und füge eine Regel hinzu:

Protokoll: TCP
Port: 9805
Quelle: nach Bedarf (lokales Subnetz oder „Alle“)
Aktion: Zulassen

Verifizieren: Kimai ist von einem anderen Gerät im Netzwerk unter http://NAS-IP:9805 erreichbar. Wenn die Verbindung abgelehnt wird, prüfe die Firewall-Reihenfolge (Regeln werden von oben nach unten abgearbeitet).

Schritt 7: HTTPS per Reverse Proxy einrichten (optional, empfohlen)

Für den produktiven Einsatz – besonders wenn Kimai über das Internet erreichbar sein soll – richtest du in DSM einen Reverse Proxy mit SSL-Zertifikat ein. Kimai unterstützt keinen Unterpfad-Betrieb (z. B. https://nas.example.com/kimai); du benötigst eine eigene (Sub-)Domain, z. B. kimai.example.com.

Öffne DSM → Systemsteuerung → Anmeldungsportal → Erweitert → Reverse Proxy und erstelle einen neuen Eintrag:

Einstellung	Wert
Quellprotokoll	HTTPS
Quelldomain	kimai.example.com
Quellport	443
Zielprotokoll	HTTP
Ziel-Host	localhost
Zielport	9805

Aktiviere im selben Dialog ein Let's-Encrypt-Zertifikat für die Subdomain. Die Variable TRUSTED_PROXIES=nginx,localhost,127.0.0.1 ist bereits im Compose-File gesetzt und sorgt dafür, dass Kimai dem Reverse Proxy vertraut. Wer lieber den Nginx Proxy Manager einsetzt, findet hier eine Schritt-für-Schritt-Anleitung: Nginx Proxy Manager auf der Synology mit Container Manager einrichten.

Verifizieren: https://kimai.example.com öffnet die Kimai-Anmeldeseite mit gültigem SSL-Zertifikat (grünes Schloss im Browser). Keine Mixed-Content-Warnungen in der Browserkonsole.

Schritt 8: ADMINMAIL und ADMINPASS absichern

ADMINMAIL und ADMINPASS werden von Kimai nur beim allerersten Start ausgewertet – wenn noch kein Admin-Benutzer in der Datenbank existiert. Danach haben sie keinen Effekt mehr. Es ist dennoch schlechte Praxis, Zugangsdaten dauerhaft im Klartext im Compose-File zu belassen.

Öffne das Compose-File im Container Manager und entferne die beiden Zeilen (oder kommentiere sie aus):

      # - ADMINMAIL=admin@example.com   # nach Erststart entfernt
      # - ADMINPASS=AdminPasswort2024   # nach Erststart entfernt

Starte das Projekt danach neu (Projekt → Aktion → Stoppen, dann Starten). Die Konfiguration wird ohne diese Variablen geladen; der bestehende Admin-Account bleibt erhalten.

Verifizieren: docker logs kimai 2>&1 | grep -i 'admin' zeigt nach dem Neustart keine Zeile mehr, die auf eine Admin-Erstellung hinweist. Der Login mit dem bestehenden Account funktioniert weiterhin.

Troubleshooting / Typische Fehler

„Unknown database version“ oder Integritätsfehler beim Start: Der serverVersion-Wert in DATABASE_URL stimmt nicht exakt mit der laufenden MariaDB-Version überein. Prüfe die Version mit docker exec kimai-db mysql --version und trage den exakten String (mit -MariaDB-Suffix) ein, z. B. 10.11.4-MariaDB.
Kimai crasht sofort mit „Connection refused“: MariaDB war noch nicht bereit. Ursache: fehlendes oder falsch konfiguriertes healthcheck am DB-Container. Prüfe, ob der Healthcheck-Block vollständig ist und depends_on mit condition: service_healthy gesetzt ist.
Kein Admin-Account nach dem Erststart: ADMINMAIL/ADMINPASS wurden erst gesetzt, nachdem die Volumes bereits initialisiert waren. Lösung: Volumes leeren (rm -rf /volume1/docker/kimai/db/* /volume1/docker/kimai/data/*) und Projekt neu starten. Alternativ: docker exec kimai bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN Passwort
URL-Parse-Fehler bei DATABASE_URL: Das DB-Passwort enthält Sonderzeichen wie @, #, % oder &. Diese durch alphanumerische Zeichen ersetzen.
Kimai nach Update nicht mehr erreichbar (Migrations-Fehler): Nach einem Image-Update schlägt eine Datenbankm migration fehl. Volume-Backup einspielen und auf die vorherige Image-Version zurückgehen.
Port 9805 nicht erreichbar: DSM-Firewall blockiert den Port. Firewall-Regel gemäß Schritt 6 prüfen; sicherstellen, dass die Regel oberhalb einer „Alles blockieren“-Regel steht.
Kimai unter Subdirectory nicht erreichbar: Kimai unterstützt keinen Unterpfad-Betrieb. Der Reverse Proxy muss auf eine eigene (Sub-)Domain zeigen.
APP_SECRET geändert, alle Nutzer ausgesperrt: Nach einer APP_SECRET-Änderung werden alle Sessions invalidiert. Den ursprünglichen Wert wiederherstellen, falls das nicht gewollt war.

Häufige Fragen

Welche PHP-Version ist im offiziellen Kimai-Docker-Image enthalten?

Das Image kimai/kimai2:stable bringt PHP 8.2 (oder neuer) mit allen erforderlichen Erweiterungen – darunter mbstring, gd, intl, json, pdo, tokenizer, xml und zip – bereits vorinstalliert mit. Du musst keine manuelle PHP-Konfiguration vornehmen; das Image ist produktionsreif ausgeliefert.

Kann ich Kimai auf einem Synology ARM-NAS (z. B. DS220j) betreiben?

Das offizielle Image kimai/kimai2:stable unterstützt nur amd64 (Intel/AMD). Für ARM64-NAS-Modelle empfiehlt sich das Multi-Arch-Image lscr.io/linuxserver/kimai:latest, das sowohl amd64 als auch arm64 unterstützt. Die Konfiguration ist weitgehend identisch; lediglich einige Umgebungsvariablen-Namen unterscheiden sich geringfügig – die LinuxServer-Dokumentation hält die Abweichungen aktuell.

Was passiert bei einem Kimai-Update?

Beim Neustart nach einem Image-Update führt Kimai ausstehende Datenbankmigrationen automatisch durch. Erstelle vor jedem Update ein Backup der Volumes (/volume1/docker/kimai/data und /volume1/docker/kimai/db). Prüfe nach dem Update mit docker logs kimai 2>&1 | grep -i 'migrat', ob alle Migrationen ohne Fehler durchgelaufen sind.

Wie lege ich weitere Benutzer an?

Entweder im Web-Interface unter Administration → Benutzer → Neu oder per CLI:

docker exec kimai bin/console kimai:user:create benutzername user@example.com ROLE_USER Passwort

Für Team-Leads eignet sich ROLE_TEAMLEAD, für Administratoren ROLE_SUPER_ADMIN.

Erfüllt Kimai die deutsche Pflicht zur Arbeitszeiterfassung?

Ja – Kimai erfasst Beginn, Ende, Pausen und Gesamtdauer je Mitarbeiter und Projekt, bietet auditierbare Auswertungen und ermöglicht den Export als Nachweis. Laut Koalitionsvertrag 2025 sind Kleinbetriebe mit bis zu 10 Mitarbeitern von der Pflicht zur elektronischen Erfassung ausgenommen; die grundsätzliche Erfassungspflicht besteht jedoch für alle Arbeitgeber.

Wie setze ich das Admin-Passwort zurück?

Wenn kein SMTP konfiguriert ist und damit „Passwort vergessen“ nicht funktioniert, setze das Passwort per CLI:

docker exec -it kimai bin/console kimai:user:password admin

Das Tool fragt das neue Passwort interaktiv ab. Alternativ direkt als Parameter: ... kimai:user:password admin NeuesPasswort.

Fazit

Kimai auf dem Synology NAS zu betreiben ist mit dem Container Manager und einem sauber aufgebauten Compose-Projekt unkomplizierter als erwartet. Der entscheidende Qualitätsunterschied liegt in den Details: der korrekte serverVersion-String mit -MariaDB-Suffix, der Healthcheck am Datenbankcontainer, utf8mb4 statt utf8 und das Entfernen von ADMINMAIL/ADMINPASS nach der Initialisierung. Wer diese Punkte beachtet, betreibt eine stabile, updatefähige Zeiterfassung, die die Anforderungen aus EuGH-Urteil und BAG-Beschluss erfüllt – vollständig unter eigener Kontrolle, ohne Cloud-Abhängigkeit und ohne monatliche Abogebühren.

Als deutsches Projekt mit aktiver Entwicklung (Version 2.60.0 im Juni 2026, neue Releases alle paar Wochen) und einer gewachsenen Community ist Kimai eine der reifsten Open-Source-Lösungen im Bereich Zeiterfassung. Das Plugin-System erlaubt Erweiterungen für spezifische Anforderungen; SAML- und LDAP-Integration ermöglicht die Einbindung in bestehende Unternehmensverzeichnisse. Wer seinen Self-Hosting-Stack auf dem Synology NAS weiter ausbauen möchte, findet in der gleichen Charge weitere Business-Tools: Cal.com als selbstgehostete Calendly-Alternative und OpenProject für Projektmanagement mit Gantt-Diagrammen.

Weiterführende Anleitungen und Quellen

Quellen: Kimai offizielle Docker-Dokumentation · Kimai Docker Compose Dokumentation · Kimai GitHub Repository · LinuxServer Kimai Image