Héberger Kaneo sur un VPS : gestion de projets open-source épurée

Les outils SaaS de gestion de projets ont tendance à s'alourdir : chaque mise à jour ajoute une vue, un rapport, un module IA qui noie les fonctionnalités essentielles. Kaneo part de l'hypothèse inverse : la plupart des équipes n'ont besoin que d'un Kanban et d'un lien avec leur dépôt de code. En l'auto-hébergeant, vous récupérez la maîtrise totale — vos tâches dans une base PostgreSQL sur votre VPS, exportables en SQL à tout moment, sans plan premium pour débloquer les webhook ou l'historique sans quota imposé.

Un VPS ServOrbit avec Ubuntu 24.04 et au moins 1 Go de RAM suffit pour une petite équipe. Kaneo est léger : l'API Hono (Node.js) et la SPA Vue.js consomment ensemble moins de 200 Mo au repos ; PostgreSQL 16 en ajoute environ 300 Mo. Docker et Docker Compose sont provisionnés automatiquement par AWX lors du déploiement. Aucun nom de domaine n'est obligatoire — Kaneo fonctionne derrière l'URL assignée par ServOrbit — mais un sous-domaine dédié (ex. projects.votre-domaine.com) simplifie le partage.

Kaneo supporte plusieurs espaces de travail sur une même instance. Chaque workspace dispose de ses propres projets, membres et webhooks — pratique pour cloisonner des clients ou des équipes sur un seul VPS sans multiplier les déploiements.

Pour créer un second espace de travail, cliquez sur le sélecteur en haut à gauche de l'interface et choisissez « Nouvel espace de travail ». Les membres d'un workspace n'ont pas accès aux autres : l'isolation est applicative, pas seulement visuelle. Vous pouvez ainsi héberger les projets d'un client A et d'un client B sur le même serveur, chacun avec ses propres tableaux et intégrations GitHub distinctes.

Si vous avez besoin de champs personnalisés sur les tâches, consultez la documentation officielle de Kaneo avant d'en dépendre : les custom fields font partie de la roadmap, mais leur disponibilité peut varier selon la version déployée. Vérifiez les release notes de votre version en cours sur le dépôt GitHub de Kaneo avant de concevoir un workflow qui en dépend.

Les webhooks Kaneo sont l'un de ses atouts les plus directs pour les équipes de développement. À chaque changement d'état d'une tâche — déplacement de colonne, assignation, commentaire — Kaneo envoie un POST JSON vers l'URL de votre choix.

Cas d'usage courants :

- Notification Slack : ajoutez l'URL Incoming Webhook de votre canal pour recevoir une alerte dès qu'une tâche passe en « En cours » ou « Terminé ».
- Déclenchement d'un pipeline CI : envoyez l'événement vers votre système de CI (GitHub Actions, Gitea Actions, Jenkins) pour lancer automatiquement un build ou un déploiement quand une tâche atteint une colonne cible.
- Synchronisation avec un système externe : l'endpoint peut pointer vers n'importe quelle API REST — outil de reporting, base de données de tickets, webhook n8n pour orchestrer des flux complexes.

La structure du payload Kaneo est documentée dans le dépôt officiel. Testez vos endpoints avec un service comme webhook.site avant de les câbler en production, pour vérifier que le format correspond à ce que votre CI attend.

Kaneo stocke toutes ses données dans PostgreSQL 16. Un backup régulier est indispensable : sans lui, une mise à jour ratée ou une corruption de volume vous ferait perdre l'historique de vos tâches.

Automatiser les sauvegardes avec cron et rclone

Voici une procédure en deux étapes — dump quotidien local, puis copie vers un stockage objet distant :

# /etc/cron.d/kaneo-backup
0 3 * * * root docker exec kaneo-db pg_dump -U kaneo kaneo | gzip > /var/backups/kaneo/$(date +\%Y\%m\%d).sql.gz
5 3 * * * root rclone copy /var/backups/kaneo/ s3:mon-bucket/kaneo/ --max-age 30d

Adaptez kaneo-db au nom réel de votre conteneur PostgreSQL (docker ps pour le vérifier) et kaneo aux identifiants configurés lors du déploiement.

Restaurer une sauvegarde

# Arrêter l'application avant la restauration
docker stop kaneo-app
# Restaurer le dump dans le conteneur PostgreSQL
gunzip -c /var/backups/kaneo/20260901.sql.gz | docker exec -i kaneo-db psql -U kaneo kaneo
# Redémarrer
docker start kaneo-app

Conservez au moins 7 dumps locaux et 30 jours de copies distantes. Testez la restauration sur un environnement de test avant d'en avoir besoin — un dump non restaurable ne vaut pas mieux qu'une absence de backup.

Kaneo publie ses releases sur GitHub (hcengineering/huly-selfhost pour le self-hosting, ou le dépôt officiel de Kaneo selon votre installation). La procédure de mise à jour est standard pour un déploiement Docker Compose :

# Récupérer l'image mise à jour
docker compose pull
# Redémarrer les conteneurs avec la nouvelle image
docker compose up -d
# Vérifier que les conteneurs sont bien en cours d'exécution
docker compose ps

Avant toute mise à jour, effectuez un backup complet (voir la section précédente). Consultez les release notes de la nouvelle version sur GitHub : certaines mises à jour incluent des migrations de base de données qui s'appliquent automatiquement au démarrage du conteneur. Si une migration échoue, les logs du conteneur applicatif (docker logs kaneo-app) en donneront le détail.

Si vous avez déployé via la marketplace ServOrbit, une mise à jour de la fiche applicative dans le panneau de contrôle peut déclencher un redéploiement avec la version suivante — consultez la documentation de votre plan.

Par défaut, Kaneo ne requiert pas de serveur SMTP : l'inscription se fait par email et mot de passe, sans lien de vérification. Cela simplifie le déploiement initial, mais limite les notifications par email (réinitialisation de mot de passe, alertes de tâche).

Si votre version de Kaneo supporte la configuration SMTP, les paramètres se trouvent dans les variables d'environnement du docker-compose.yml déployé :

SMTP_HOST=smtp.votre-domaine.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=votre-mot-de-passe
[email protected]

Si votre instance ServOrbit inclut un plan e-mail professionnel, utilisez les paramètres SMTP de votre boîte sortante. Après modification des variables, redémarrez les conteneurs avec docker compose up -d pour que les nouveaux paramètres soient pris en compte. Testez l'envoi depuis l'interface d'administration avant de fermer l'inscription publique.

Le conteneur redémarre en boucle au premier démarrage

Cause la plus courante : un secret manquant ou mal formaté dans le fichier d'environnement. Vérifiez les logs du conteneur applicatif (docker logs kaneo-app) — l'erreur indique généralement la variable absente. Les secrets sont générés automatiquement lors du déploiement marketplace ; sur une installation manuelle, assurez-vous que JWT_SECRET, DATABASE_URL et COOKIE_SECRET sont définis.

L'interface se charge mais la connexion échoue avec « Invalid credentials »

Le premier compte créé est l'administrateur. Si vous avez relancé le conteneur sans supprimer le volume PostgreSQL, le compte existe déjà en base : tentez la connexion avec les identifiants saisis à la première inscription. Si le volume a été supprimé, créez un nouveau compte depuis l'interface.

Les webhooks ne se déclenchent pas

Vérifiez que l'URL de destination est joignable depuis le conteneur Kaneo (pas localhost du VPS hôte — utilisez l'IP externe ou un nom de domaine). Testez avec curl -X POST https://votre-endpoint.com/webhook -d '{}' depuis le conteneur pour confirmer la connectivité.

La synchronisation GitHub s'arrête après quelques heures

La GitHub App nécessite que l'URL de callback soit accessible en HTTPS depuis l'extérieur. Vérifiez que votre certificat SSL est valide (certbot renew --dry-run) et que le port 443 est ouvert sur votre VPS.

Performances dégradées avec de nombreuses tâches

Sur un VPS à 1 Go de RAM, PostgreSQL peut devenir le goulot d'étranglement si le volume de données grossit. Augmentez shared_buffers dans la configuration PostgreSQL ou passez à un plan avec 2 Go de RAM. Kaneo n'est pas conçu pour des milliers de tâches actives simultanées : c'est son choix de conception, pas un défaut.