Kimai Zeiterfassung auf 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: /de/vps/anwendungen/traefik-reverseproxy-auf-vps-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. Du kannst 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: /de/vps/anwendungen/traefik-reverseproxy-auf-vps-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:

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

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

Du kannst hier auch ein anderes Verzeichnis verwenden. Musst 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 öffnest du folgende Datei:

Nun kopierst du 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 musst du noch den Hostnamen anpassen, über welchen später Kimai erreichbar sein soll.

Diese beiden Zeilen musst du anpassen.

In meinem Fall also:

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

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

Wenn du Kimai direkt auf deiner „Hauptdomain“ betreiben willst, dann änderst du es folgendermaßen ab:

Egal wie du dich entscheidest, diese Anpassung musst du noch vornehmen.

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

Hier fügst du am Ende deine Domain hinzu. Bei mir sieht es dann so aus:

1.3.4 Datenbank Passwort anpassen

Nachdem du den Hostnamen angepasst hast, musst du noch das Datenbank Passwort anpassen. Vergib ein langes, sicheres Kennwort.

Folgende Zeilen musst du ändern:

      - MYSQL_PASSWORD=kimaipassword

      - MYSQL_ROOT_PASSWORD=changemeplease 

Bei mir sieht es dann so aus:

Anschließend musst du noch folgende Zeile anpassen, damit Kimai später auf die Datenbank zugreifen kann.

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

Hier musst du dein MYSQL Kennwort eingeben. Diese Zeile sieht dann bei mir so aus:

1.3.5 Administrator Account anpassen

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

      - ADMINMAIL=admin@euredomain.de

      - ADMINPASS=changemepleasess 

Bei mir sieht es dann beispielsweise so aus:

1.3.6 E-Mail aktivieren

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

Das wichtigste ist, dass wenn du eine E-Mail Login oder Passwort mit Sonderzeichen hast, dann musst du diese „URL Encoden“. Dies kannst du beispielsweise auf dieser Webseite machen: URL Encode Online | URLEncoder

Hier ein konkretes Beispiel:

Mein E-Mail Login ist: admin@easyname.at

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%40easyname.at

ASdn324%212%26%C2%A7da 

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

In der Konfiguration sind bereits folgende Zeilen enthalten:

Diese musst du dann entsprechend anpassen und die „#“ zu Beginn entfernen.

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

- MAILER_FROM=admin@easyname.at 

2. Kimai starten

Gib nun folgendes ein, um deinen Kimai Container zu starten:

Beim ersten Start des Containers wird Kimai initialisiert. Dies bedeutet, dass die Datenbank eingerichtet, deine 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 solltest du folgendes sehen: 

Nachdem du dich nun eingeloggt hast mit deinem Administrator, siehst du folgendes: 

2.1 Sprache ändern

Um die Sprache des Benutzers zu ändern, musst du links auf „Users“ klicken. 

Klicke anschließend hinter deinem Benutzer auf den „Pfeil“ und wähle „Preferences“ aus. 

Hier kannst du nun die Sprache und vieles mehr anpassen. 

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

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

2.2 Plugins installieren

Kimai bietet einen Marktplatz, wo du kostenlose und kostenpflichte Erweiterungen erwerben kannst: https://www.kimai.org/store/

Ich zeige dir hier an einem Beispiel, wie du diese Erweiterungen in Kimai integrieren kannst. Auf der Webseite suche ich mir also beispielhaft das „Easy Backup“ Programm aus.

Oben rechts gibt es einen Button mit „Download“. 

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

Auf deinem Server gehst du nun in dein Plugin Verzeichnis. Gib dazu folgendes ein:

cd /opt/containers/kimai/plugins 

Gib nun “wget” in die Konsole ein und gib die Adresse zum Download ein, welche du eben kopiert hast.

Bei mir ist dies

Anschließend entpackst du die Datei mit folgendem Befehl:

unzip master.zip 

Nun löschen wir die ZIP Datei wieder. Dazu gibst du folgendes ein:

Wenn du nun „ls“ eingibst, solltest du einen neuen Ordner im Verzeichnis sehen:

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

mv EasyBackupBundle-master/ EasyBackupBundle 

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

Zum Schluss müssen wir Kimai alle Daten neu einlesen lassen. Dazu gibst du 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 solltest du folgendes sehen:

Wenn du alles richtig gemacht hast, dann solltest du nun unter dem Reiter „Erweiterungen“ unsere Erweiterung „EasyBackup“ sehen. 

Zu unseren VPS Paketen