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. Für diese Pflicht eignet sich Kimai als selbst gehostetes Werkzeug: Das deutsche Open-Source-Projekt (AGPL-3.0, seit 2006, Version 2.67.0 im September 2026) bietet Zeiterfassung für mehrere Benutzer, Projektverwaltung, Rechnungen und Auswertungen und läuft auf Synology-Modellen mit Intel-, AMD- oder ARM64-CPU in Docker. Diese Anleitung zeigt den Weg über den Container Manager mit einem abgesicherten Compose-Projekt.

Voraussetzungen

Synology NAS mit Intel-/AMD-CPU (x86_64) oder ARM64-CPU
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

Hardware für diese Anleitung

Enthält Werbelinks

Synology mit Container Manager	Container laufen nur auf Modellen mit Container Manager, vor allem der Plus-Serie. Vor dem Kauf die Kompatibilitätsliste von Synology prüfen. Bei uns läuft eine DS920+.	Synology bei Amazon (Werbelink)
NAS-Festplatten	Für den Dauerbetrieb Platten mit CMR-Technik wählen, für RAID 1 zwei gleich große.	NAS-Platten bei Amazon (Werbelink)
RAM-Erweiterung	Mehrere Container gleichzeitig brauchen Speicher. Viele Plus-Modelle lassen sich aufrüsten, das passende Modul steht im Datenblatt.	Bei Amazon ansehen (Werbelink)

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: Ordnerstruktur anlegen

Öffnen Sie die File Station und legen Sie 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}

Getrennte Ordner für Anwendungsdaten, Plugins und Datenbank erleichtern gezielte Backups und Rollbacks nach fehlgeschlagenen Migrationen.

Verifizieren: In der File Station sind die drei Ordner data, plugins und db unter /volume1/docker/kimai sichtbar. 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 Sitzungen würden ungültig). Erzeugen Sie einen 64-stelligen Hex-String per SSH auf dem NAS oder einem anderen Linux-System:

openssl rand -hex 32

Die Ausgabe sieht beispielsweise so aus:

a3f8c2d1e9b047563a2e1f8d4c7b0e92f1a5d3c8e2b047a69f1c3d5e8b2a4f70

Kopieren Sie diesen Wert für den nächsten Schritt. Ohne SSH-Zugang erzeugen Sie ihn unter Linux oder macOS im Terminal, unter Windows per 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 "IHR_STRING" | wc -c muss 64 ausgeben.

Schritt 3: Compose-Projekt im Container Manager anlegen

Öffnen Sie den Container Manager, wechseln Sie zu Projekt und klicken Sie auf Erstellen. Wählen Sie als Pfad /volume1/docker/kimai und als Projektnamen kimai. Details: Container Manager auf dem Synology NAS: Docker-Compose-Projekt anlegen, starten und aktualisieren.

Fügen Sie folgenden Inhalt als compose.yaml ein. Ersetzen Sie dabei alle Passwörter, APP_SECRET und ADMINMAIL durch eigene Werte:

Parameter	Wert / Hinweis
Image (Kimai)	`kimai/kimai2:2.71.0` (Stable-Tag, amd64 und arm64)
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:2.71.0
    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. Verwenden Sie Buchstaben, Ziffern und Bindestriche.
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 alle Datenbankmigrationen automatisch aus. Prüfen Sie per SSH, ob sie erfolgreich waren:

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, prüfen Sie das vollständige Log (docker logs kimai 2>&1 | tail -50) – häufigste Ursache ist ein falscher serverVersion-Wert (siehe Troubleshooting).

Öffnen Sie anschließend http://NAS-IP:9805 und melden Sie sich mit ADMINMAIL und ADMINPASS aus der Compose-Datei an.

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

Schritt 5: Ersten Mandanten, Kunden und Projekt anlegen

Nach dem Login richten Sie die Grundstruktur ein:

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

Starten Sie eine erste Zeitmessung: Start-Button oben rechts, Projekt und Tätigkeit wählen, nach einigen Sekunden stoppen. 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.

Schritt 6: Firewall-Port freigeben

Ist die DSM-Firewall aktiv, geben Sie Port 9805 frei. Details: DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben.

Öffnen Sie Systemsteuerung → Sicherheit → Firewall und fügen Sie eine Regel hinzu:

Protokoll: TCP
Port: 9805
Quelle: lokales Subnetz
Aktion: Zulassen

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

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

Für den produktiven Einsatz, besonders bei Zugriff aus dem Internet, richten Sie in DSM einen Reverse Proxy mit Zertifikat ein. Kimai unterstützt keinen Betrieb unter einem Unterpfad (z. B. https://nas.example.com/kimai); Sie benötigen eine eigene (Sub-)Domain, z. B. kimai.example.com.

Öffnen Sie Systemsteuerung → Anmeldungsportal → Erweitert → Reverse Proxy und erstellen Sie einen Eintrag:

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

Weisen Sie der Subdomain unter Systemsteuerung → Sicherheit → Zertifikat ein Let's-Encrypt-Zertifikat zu. 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. Alternative mit Nginx Proxy Manager: 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. Zugangsdaten sollten trotzdem nicht dauerhaft im Klartext in der Compose-Datei stehen.

Öffnen Sie die Compose-Datei im Container Manager und entfernen Sie die beiden Zeilen (oder kommentieren Sie sie aus):

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

Starten Sie 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üfen Sie die Version mit docker exec kimai-db mariadb --version und tragen Sie 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üfen Sie, 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 /opt/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 Datenbankmigration 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:2.71.0 bringt PHP 8.2 (oder neuer) mit allen erforderlichen Erweiterungen – darunter mbstring, gd, intl, json, pdo, tokenizer, xml und zip – bereits vorinstalliert mit. Eine eigene PHP-Konfiguration ist nicht nötig.

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

Ja, sofern das Modell eine ARM64-CPU hat. Das offizielle Image kimai/kimai2:2.71.0 wird für amd64 und arm64 gebaut, die Compose-Datei bleibt gleich. Modelle mit 32-Bit-ARM-CPU (z. B. ältere j-Serie) unterstützen den Container Manager nicht.

Was passiert bei einem Kimai-Update?

Beim Neustart nach einem Image-Update führt Kimai ausstehende Datenbankmigrationen automatisch durch. Erstellen Sie vor jedem Update ein Backup der Volumes (/volume1/docker/kimai/data und /volume1/docker/kimai/db). Prüfen Sie 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 /opt/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?

Kimai erfasst Beginn, Ende, Pausen und Gesamtdauer je Mitarbeiter und Projekt, bietet auditierbare Auswertungen und ermöglicht den Export als Nachweis. Der Koalitionsvertrag 2025 kündigt eine gesetzliche Pflicht zur elektronischen Erfassung mit Übergangsregeln für kleine und mittlere Unternehmen an. Prüfen Sie den aktuellen Gesetzesstand. Die grundsätzliche Erfassungspflicht nach BAG gilt bereits für alle Arbeitgeber.

Wie setze ich das Admin-Passwort zurück?

Ist kein SMTP konfiguriert, funktioniert „Passwort vergessen“ nicht. Setzen Sie das Passwort dann per CLI:

docker exec -it kimai /opt/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 läuft mit dem Container Manager und einem sauberen Compose-Projekt stabil auf dem Synology NAS. Entscheidend sind die Details: der korrekte serverVersion-String mit -MariaDB-Suffix, der Healthcheck am Datenbankcontainer, utf8mb4 statt utf8 und das Entfernen von ADMINMAIL/ADMINPASS nach der Initialisierung. Damit betreiben Sie eine updatefähige Zeiterfassung unter eigener Kontrolle, ohne Cloud-Abhängigkeit.

Kimai erscheint etwa alle paar Wochen in neuer Version (2.67.0 im September 2026). Plugins erweitern den Funktionsumfang, SAML und LDAP binden bestehende Verzeichnisse an. Passende Ergänzungen auf dem NAS sind Cal.com für Terminbuchung und OpenProject für Projektmanagement.

Update auf 2.70.0: Sichern Sie Datenbank, Datenordner, Plugins und APP_SECRET vor dem Image-Wechsel. Die Images mit dem Kanal stable werden weitergeschrieben; pinnen Sie für nachvollziehbare Updates den geprüften Tag. Ab 2.68 sind Passwortzurücksetzungen ohne konfiguriertes TRUSTED_HOSTS deaktiviert. Tragen Sie die tatsächlich verwendeten Hostnamen entsprechend der Kimai-Dokumentation ein, bevor Sie diese Funktion benötigen. Kurze ganzzahlige Dauereingaben unter 10 werden als Stunden, Werte ab 10 als Minuten interpretiert; prüfen Sie bestehende Eingabegewohnheiten. Bei eigenen API-Anbindungen ist das Rechnungs-Zahlungsdatum jetzt ein Datum statt eines Zeitstempels.

Version 2.70.0 ist laut Release Notes vor allem ein Sicherheitsupdate: Interne Benutzereinstellungen lassen sich nicht mehr per API ändern, angemeldet gebliebene Benutzer können den Assistenten zur Passwortänderung nicht überspringen, ein Zurücksetzen des Passworts beendet alle aktiven Sitzungen, und nur der angemeldete Benutzer selbst kann seine Zwei-Faktor-Anmeldung aktivieren. Neu ist eine konfigurierbare Mindeststärke für Passwörter. Unterstützt werden PHP 8.2 bis 8.5. Im Test am 20.10.2026 mit der Compose-Datei aus Schritt 3 (Pfade auf einen lokalen Ordner angepasst) lief das Update von 2.69.0 auf 2.70.0 ohne neue Datenbankmigration (Already at the latest version), kimai:version meldete 2.70.0, Administrator und ein vorher angelegter Benutzer waren vorhanden, die Anmeldung mit dem richtigen Passwort gelang, ein falsches Passwort führte zurück zur Anmeldeseite.

Update auf 2.71.0: 2.70.1 und 2.70.2 bauen die Images mit korrigierten PHP-Versionen neu. 2.71.0 deaktiviert laut Release Notes die alten API-Passwörter und entfernt sie aus dem Benutzerprofil. Eigene Skripte und Integrationen, die sich noch mit API-Passwort anmelden, stellen Sie vor dem Update auf API-Tokens um. Außerdem prüft die API jetzt die Berechtigung zum Setzen von Startzeiten, und die Benutzerrollen werden in der Datenbank von einem veralteten Array-Typ auf JSON umgestellt. Im Test am 26.10.2026 mit derselben Compose-Datei lief beim Update von 2.70.0 auf 2.71.0 genau eine Migration (Version20261025120000), kimai:version meldete 2.71.0, Administrator und vorher angelegter Benutzer behielten ihre Rollen, beide konnten sich anmelden, und ein falsches Passwort führte zurück zur Anmeldeseite.

Die CLI-Befehle rufen Sie mit vollem Pfad /opt/kimai/bin/console auf. Das Arbeitsverzeichnis des Images ist /var/www/html, ein kurzes bin/console endet deshalb mit stat bin/console: no such file or directory.

Weiterführende Anleitungen und Quellen

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