Kimai Zeiterfassung auf vServer/VPS installieren

0. Überblick

Verwendetes System: Debian 11 64 bit
Genutzter User: Ich nehme alles als „root“ vor
Zeitdauer: ca. 10 Minuten
Schwierigkeit: Einfach. Nur Code kopieren 😉
Besonderheiten:
- Grundlage ist folgende Anleitung: https://www.dogado.de/vps/vserver-anwendungsfaelle/traefik-reverseproxy-auf-vserver-installieren. Diese Anleitung muss zuerst ausgeführt werden.
- Die Installation von Docker / Docker Compose wird hier vorausgesetzt.

1. Kimai installieren

1.1 Einleitung

Kimai ist eine open source Zeiterfassungssoftware. Kimai ermöglicht es Zeiten für Projekte abzurechnen und stellt diese noch grafisch dar. Kimai kann mit Hilfe von Plugins noch um einige Funktionen erweitert werden.

1.2 Infos zu yml Dateien

Bei yml Dateien ist es sehr wichtig, dass die Zeilen alle richtig eingerückt sind. Die Zeilen MÜSSEN immer mit der Leertaste eingerückt werden. Es dürfen KEINE Tabs enthalten sein. Ihr könnt den nachfolgenden Code immer online „überprüfen“ lassen. Die meisten Fehler entstehen nämlich durch die falsche Formatierung. Ein Dienst zum Überprüfen ist zum Beispiel: https://codebeautify.org/yaml-validator

1.3 Vorbereitung

Diese Anleitung basiert auf dem aktuellen Debian 10 Betriebssystem. Kimai werden wir unter Docker realisieren. Dies ermöglicht uns später sehr schnelle Updates und eine schnelle Installation.

Um Kimai neben anderen Diensten auf unserem Server betreiben zu können, nutzen wir hier den Reverse Proxy Traefik. Die Anleitung dazu finden Sie hier: https://www.dogado.de/vps/vserver-anwendungsfaelle/traefik-reverseproxy-auf-vserver-installieren

1.3.1 Verzeichnis erstellen

Wir erstellen uns ein neues Verzeichnis, in welchem wir später alle Daten von Kimai abspeichen. Dazu geben wir folgendes in der Konsole ein:

mkdir -p /opt/containers/kimai/{var,mysql,plugins}

Anschließend müssen wir noch die Rechte eines Ordners anpassen. Gebt dazu folgendes ein:

chown -R www-data:www-data /opt/containers/kimai/var/

Ihr könnt hier auch ein anderes Verzeichnis verwenden. Müsst dann aber die gesamte Anleitung entsprechend anpassen.

1.3.2 docker-compose.yml erstellen

Nun können wir mit der eigentlichen „Installation“ von Kimai beginnen. Dazu öffnet ihr folgende Datei:

nano /opt/containers/kimai/docker-compose.yml

Nun kopiert ihr folgenden Code in die Datei. Dieser Code ist unser Bauplan für unseren Kimai Container.

version: '3.5' 

services: 

  kimai-sql: 

    image: mysql:5.7 

    container_name: kimai-sql 

    environment: 

      - MYSQL_DATABASE=kimai 

      - MYSQL_USER=kimaiuser 

      - MYSQL_PASSWORD=kimaipassword 

      - MYSQL_ROOT_PASSWORD=changemeplease 

    volumes: 

      - ./mysql:/var/lib/mysql 

    command: --default-storage-engine innodb 

    restart: unless-stopped 

    networks: 

      - default 

 

  kimai: 

    image: kimai/kimai2:apache 

    environment: 

      - ADMINMAIL=admin@euredomain.de 

      - ADMINPASS=changemepleasess 

      - DATABASE_URL=mysql://kimaiuser:kimaipassword@kimai-sql/kimai 

      - TRUSTED_HOSTS=traefik,nginx,localhost,127.0.0.1,kimai 

      - APP_ENV=prod 

      # - MAILER_URL= 

      #- MAILER_FROM=kimai@euredomain.de 

    container_name: kimai 

    volumes: 

      - public:/opt/kimai/public 

      - ./var:/opt/kimai/var 

      - ./plugins:/opt/kimai/var/plugins 

    restart: unless-stopped 

    networks: 

      - default 

      - proxy 

    labels: 

      - "traefik.enable=true" 

      - "traefik.http.routers.kimai.entrypoints=http" 

      - "traefik.http.routers.kimai.rule=Host(`kimai.euredomaind.de`)"   # Hier eure URL eingeben # 

      - "traefik.http.middlewares.kimai-https-redirect.redirectscheme.scheme=https" 

      - "traefik.http.routers.kimai.middlewares=kimai-https-redirect" 

      - "traefik.http.routers.kimai-secure.entrypoints=https" 

      - "traefik.http.routers.kimai-secure.rule=Host(`kimai.euredomain.de`)"    # Hier eure URL eingeben # 

      - "traefik.http.routers.kimai-secure.tls=true" 

      - "traefik.http.routers.kimai-secure.tls.certresolver=http" 

      - "traefik.http.routers.kimai-secure.service=kimai" 

      - "traefik.http.services.kimai.loadbalancer.server.port=8001" 

      - "traefik.docker.network=proxy" 

      - "traefik.http.routers.kimai-secure.middlewares=secHeaders@file" 

 

volumes: 

    public: 

 

networks: 

  proxy: 

    external: true

Nun müssen wir noch einiges anpassen.

1.3.3 Hostname anpassen

Nun müsst ihr noch den Hostnamen anpassen, über welchen später Kimai erreichbar sein soll.

Diese beiden Zeilen müsst ihr anpassen.

    - "traefik.http.routers.kimai.rule=Host(`kimai.euredomain.de `)" 

    - "traefik.http.routers.kimai-secure.rule=Host(`kimai.euredomain.de`)"

In meinem Fall also:

    - "traefik.http.routers.kimai.rule=Host(`kimai.testbereich.net`)" 

    - "traefik.http.routers.kimai-secure.rule=Host(`kimai.testbereich.net`)"

Wenn ihr Kimai direkt auf eurer „Hauptdomain“ betreiben wollt, dann ändert ihr es folgendermaßen ab:

"traefik.http.routers.kimai.rule=Host(`www.euredomain.de`,`euredomain.de`)" 

"traefik.http.routers.kimai-secure.rule=Host(`www.euredomain.de`,`euredomain.de`)"

Egal wie ihr euch entscheidet, diese Anpassung müsst ihr noch vornehmen.

      - TRUSTED_HOSTS=traefik,nginx,localhost,127.0.0.1,kimai

Hier fügt ihr am Ende eure Domain hinzu. Bei mir sieht es dann so aus:

      - TRUSTED_HOSTS=traefik,nginx,localhost,127.0.0.1,kimai,testbereich.net

1.3.4 Datenbank Passwort anpassen

Nachdem ihr den Hostnamen angepasst habt, müsst ihr noch das Datenbank Passwort anpassen. Vergebt ihr ein langes, sicheres Kennwort.

Folgende Zeilen müsst ihr ändern:

      - MYSQL_PASSWORD=kimaipassword 

      - MYSQL_ROOT_PASSWORD=changemeplease

Bei mir sieht es dann so aus:

      - MYSQL_PASSWORD=Adas324!dna3 

      - MYSQL_ROOT_PASSWORD=ghj47ASdnbg234

Anschließend müsst ihr noch folgende Zeile anpassen, damit Kimai später auf die Datenbank zugreifen kann.

      - DATABASE_URL=mysql://kimaiuser:kimaipassword@kimai-sql/kimai

Hier müsst ihr euer MYSQL Kennwort eingeben. Diese Zeile sieht dann bei mir so aus:

      - DATABASE_URL=mysql://kimaiuser:Adas324!dna3@kimai-sql/kimai

1.3.5 Administrator Account anpassen

Nun ändern wir noch die Zugangsdaten zu unserem Administrator Account ab. Dazu passt ihr folgende Zeilen an:

      - ADMINMAIL=admin@euredomain.de 

      - ADMINPASS=changemepleasess

Bei mir sieht es dann beispielsweise so aus:

      - ADMINMAIL=admin@dogado.de 

      - ADMINPASS=ASdnjad234aFas

1.3.6 E-Mail aktivieren

Um die E-Mail-Funktionen zu aktivieren (z.B. das Zurücksetzen des Kennworts per E-Mail) müsst ihr die Konfiguration anpassen. Der Hersteller veröffentlicht hier auch eine Anleitung, falls ihr Probleme habt: https://www.kimai.org/documentation/emails.html

Das wichtigste ist, dass wenn ihr eine E-Mail Login oder Passwort mit Sonderzeichen habt, dann müsst ihr diese „URL Encoden“. Dies könnt ihr beispielsweise auf dieser Webseite machen: URL Encode Online | URLEncoder

Hier ein konkretes Beispiel:

Mein E-Mail Login ist: admin@dogado.de

Mein Passwort: ASdn324!2&§da

Dann muss ich beide Zeilen anpassen, da jeweils mindestens ein Sonderzeichen enthalten ist. Die Webseite gibt mir also folgende Werte zurück:

admin%40dogado.de 

ASdn324%212%26%C2%A7da

Dies bekommt ihr hier nochmals genauer erklärt: https://symfony.com/doc/current/mailer.html

In der Konfiguration sind bereits folgende Zeilen enthalten:

      # - MAILER_URL= 

      # - MAILER_FROM=kimai@euredomain.de

Diese müsst ihr dann entsprechend anpassen und die „#“ zu Beginn entfernen.

- MAILER_URL=smtp://admin%40dogado.de: ASdn324%212%26%C2%A7da@mail.dogado.de:587?encryption=tls&auth_mode=plain 

- MAILER_FROM=admin@dogado.de

2. Kimai starten

Gebt nun folgendes ein, um euren Kimai Container zu starten:

docker compose -f /opt/containers/kimai/docker-compose.yml up -d

Beim ersten Start des Containers wird Kimai initialisiert. Dies bedeutet, dass die Datenbank eingerichtet, eure Einstellungen übernommen werden und vieles mehr. Daher dauert es einige Minuten, bis der Container dann über die Webseite (z.B kimai.euredomain.de) erreichbar ist. Bei mir hat es ca. 1 Minute gedauert.

Nun solltet ihr folgendes sehen:

Nachdem ihr euch nun eingeloggt habt mit eurem Administrator, seht ihr folgendes:

2.1 Sprache ändern

Um die Sprache des Benutzers zu ändern, müsst ihr links auf „Users“ klicken.

Klickt anschließend hinter eurem Benutzer auf den „Pfeil“ und wählt „Preferences“ aus.

Hier könnt ihr nun die Sprache und vieles mehr anpassen.

Vergesst nicht am Schluss ganz unten auf der Webseite auf „Save“ zu klicken.

Anschließend sollte sofort die Webseite in eurer gewünschten Sprache sein.

2.2 Plugins installieren

Kimai bietet einen Marktplatz, wo ihr kostenlose und kostenpflichte Erweiterungen erwerben könnt: https://www.kimai.org/store/

Ich zeige euch hier an einem Beispiel, wie ihr diese Erweiterungen in Kimai integrieren könnt. Auf der Webseite suche ich mir also beispielhaft das „Easy Backup“ Programm aus.

Oben rechts gibt es einen Button mit „Download“.

Klickt mit der rechten Maustaste auf diesen Button und wählt „Adresse des Links kopieren“ aus.

Auf eurem Server geht ihr nun in euer Plugin Verzeichnis. Gebt dazu folgendes ein:

cd /opt/containers/kimai/plugins

Gibt nun “wget” in die Konsole ein und gebt die Adresse zum Download ein, welche ihr eben kopiert habt.

Bei mir ist dies

wget https://github.com/mxgross/EasyBackupBundle/archive/master.zip

Anschließend entpackt ihr die Datei mit folgendem Befehl:

unzip master.zip

Nun löschen wir die ZIP Datei wieder. Dazu gebt ihr folgendes ein:

rm master.zip

Wenn ihr nun „ls“ eingebt, solltet ihr einen neuen Ordner im Verzeichnis sehen:

Diesen Ordner müssen wir jetzt noch umbenennen, da das Plugin sonst nicht erkannt wird. Gebt dazu folgendes ein:

mv EasyBackupBundle-master/ EasyBackupBundle

Nun müssen wir die Dateirechte für das Verzeichnis noch anpassen. Gebt dazu folgendes ein:

chown -R www-data:www-data /opt/containers/kimai/plugins/

Zum Schluss müssen wir Kimai alle Daten neu einlesen lassen. Dazu gebt ihr folgenden Befehl ein. Wichtig ist, dass Kimai dazu gestartet sein muss.

docker exec kimai /bin/bash -c "/opt/kimai/bin/console kimai:reload --env=prod"

Nun solltet ihr folgendes sehen:

Wenn ihr alles richtig gemacht habt, dann solltet ihr nun unter dem Reiter „Erweiterungen“ unsere Erweiterung „EasyBackup“ sehen.