Héberger Kimai sur un VPS : time tracking open source

Un outil de suivi du temps concentre des données sensibles : qui travaille pour quel client, combien d'heures, à quel taux. Sur un service SaaS, ces informations vivent chez l'éditeur et le coût augmente avec le nombre de comptes. En hébergeant Kimai sur votre propre VPS, vous gardez la base de données sous la main, vous ajoutez des utilisateurs sans frais de licence et vous choisissez vous-même le rythme des mises à jour.

Kimai est une application PHP construite sur le framework Symfony. La version 2 s'appuie sur MySQL ou MariaDB ; SQLite n'est plus pris en charge. L'image officielle kimai/kimai2 existe en deux variantes : apache (serveur web intégré, écoute sur le port 8001) et fpm (à placer derrière votre propre Nginx). Le template ServOrbit utilise kimai/kimai2:apache-latest avec MySQL 8.0, ce qui ramène la pile à deux conteneurs.

Le Marketplace ServOrbit provisionne la pile complète sur Ubuntu 24.04 : Docker, MySQL 8.0, le conteneur Kimai, les trois volumes et un mot de passe administrateur généré. Aucun nom de domaine n'est nécessaire pour commencer.

Si vous préférez installer Kimai vous-même sur un VPS existant, voici un docker-compose.yml équivalent au template, avec un volume de plus pour les plugins. Placez-le dans un dossier dédié, par exemple /opt/kimai.

services:
  db:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - kimai_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      retries: 12

  kimai:
    image: kimai/kimai2:apache-latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8001:8001"
    environment:
      DATABASE_URL: "mysql://kimai:${DB_PASSWORD}@db/kimai?charset=utf8mb4&serverVersion=8.0.34"
      APP_SECRET: ${APP_SECRET}
      ADMINMAIL: [email protected]
      ADMINPASS: ${ADMIN_PASSWORD}
      TRUSTED_HOSTS: "localhost,127.0.0.1,kimai.votre-domaine.com"
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
      - kimai_public:/opt/kimai/public/avatars

volumes:
  kimai_db:
  kimai_data:
  kimai_plugins:
  kimai_public:

Générez ensuite les secrets dans un fichier .env lu automatiquement par Compose, puis démarrez la pile. Au premier lancement, le conteneur crée le schéma de base et le compte administrateur défini par ADMINMAIL et ADMINPASS.

cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
DB_ROOT_PASSWORD=$(openssl rand -hex 16)
APP_SECRET=$(openssl rand -hex 32)
ADMIN_PASSWORD=$(openssl rand -hex 12)
EOF
chmod 600 .env
docker compose up -d
docker compose logs -f kimai

L'interface suffit pour gérer les comptes au quotidien, mais la console Symfony de Kimai est précieuse pour automatiser un onboarding ou récupérer un accès. La commande kimai:user:create prend un identifiant, une adresse e-mail et un rôle, puis demande le mot de passe :

docker compose exec kimai /opt/kimai/bin/console kimai:user:create alice [email protected] ROLE_TEAMLEAD

La même console expose kimai:reload pour reconstruire le cache après un changement de configuration, et kimai:update pour appliquer les migrations de base lors d'une installation hors Docker. Tapez bin/console list kimai dans le conteneur pour voir les commandes disponibles sur votre version.

Kimai organise le temps sur trois niveaux. Un client porte la devise, le fuseau horaire et les coordonnées de facturation. Un projet appartient à un client et peut avoir des dates de début et de fin, un numéro de commande et un budget. Une activité décrit la nature du travail (développement, réunion, support) ; elle peut être rattachée à un projet ou être globale, donc utilisable partout. Chaque entrée de feuille de temps relie un utilisateur, un projet, une activité, une plage horaire et, si besoin, une description et des étiquettes. Bien concevoir cette hiérarchie au départ évite de longues corrections : un client par entité facturée, un projet par mission ou contrat, des activités globales pour les tâches transverses.

Kimai distingue des rôles hiérarchiques, et l'écran Rôles et permissions permet d'ajuster finement ce que chacun voit et modifie. Les équipes complètent ce dispositif : un client, un projet ou une activité réservé à une équipe n'apparaît qu'à ses membres, et le chef d'équipe voit et valide les heures de son équipe sans accéder au reste de l'entreprise. Pour un intervenant externe, créez un compte utilisateur limité à une équipe dédiée.

Le module de facturation transforme une sélection d'heures en document. Depuis le menu Factures, vous choisissez un client, une période, éventuellement un projet, puis un modèle. Kimai calcule les montants à partir des taux, affiche un aperçu et enregistre la facture avec un statut (en attente, payée, annulée). Les entrées facturées peuvent être marquées comme exportées, ce qui évite de les facturer deux fois et les protège contre une modification ultérieure.

Kimai expose une API REST couvrant clients, projets, activités, feuilles de temps et utilisateurs. Sa documentation interactive est servie par votre propre instance à l'adresse /api/doc, à jour avec la version installée. Pour authentifier un script, créez un jeton d'API depuis votre profil utilisateur, puis passez-le en en-tête :

curl -s -H "Authorization: Bearer VOTRE_JETON" \
  https://kimai.votre-domaine.com/api/timesheets

Un jeton hérite des permissions de son utilisateur : créez un compte de service avec le rôle minimal nécessaire plutôt que d'utiliser le super-administrateur. L'API permet par exemple de démarrer un chronomètre depuis un raccourci, de remonter les heures dans un tableau de bord ou de synchroniser les projets avec votre outil de tickets.

Kimai dispose d'une boutique de plugins sur son site officiel, avec des extensions gratuites et payantes : notes de frais, champs personnalisés, circuits de validation des feuilles de temps, imports depuis d'autres outils. Un plugin est un dossier placé dans var/plugins/. Dans Docker, montez ce dossier sur un volume, sinon il disparaît à la recréation du conteneur — c'est le rôle de kimai_plugins dans le compose ci-dessus. Installation type :

docker compose cp NomDuPluginBundle kimai:/opt/kimai/var/plugins/
docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod

Certains plugins ajoutent des tables et fournissent une commande d'installation dédiée ; suivez la fiche du plugin et vérifiez sa compatibilité avec votre version de Kimai avant chaque mise à jour.

L'essentiel tient dans la base MySQL ; les volumes kimai_data et kimai_public complètent la sauvegarde. Un dump logique est plus portable qu'une copie à chaud des fichiers MySQL :

docker compose exec -T db sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > kimai-$(date +%F).sql
docker run --rm -v kimai_kimai_data:/data -v "$PWD":/backup alpine tar czf /backup/kimai_data-$(date +%F).tgz -C /data .

Le nom réel du volume est préfixé par le nom du projet Compose : vérifiez-le avec docker volume ls. Pour restaurer, démarrez une pile vide avec le même .env, puis réinjectez le dump :

docker compose exec -T db sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < kimai-AAAA-MM-JJ.sql

Planifiez le dump chaque nuit via cron, copiez-le hors du VPS (Restic, BorgBackup ou stockage objet) et testez une restauration au moins une fois : une sauvegarde jamais restaurée n'est qu'une hypothèse.

La plupart des incidents Kimai en Docker se rattachent à quelques causes connues. Commencez toujours par docker compose logs kimai et docker compose ps.

Kimai est sobre : la charge vient surtout de MySQL et de la génération de rapports sur de longues périodes. Pour un freelance ou une petite équipe, 1 vCPU et 1 à 2 Go de RAM suffisent. Au-delà d'une vingtaine d'utilisateurs actifs, ou si vous produisez régulièrement des rapports annuels et des exports volumineux, prévoyez 2 vCPU et 4 Go, ce qui laisse de la marge au cache InnoDB de MySQL. L'espace disque reste modeste : quelques gigaoctets couvrent des années de feuilles de temps, mais gardez de la place pour les dumps locaux avant leur envoi hors serveur.