Pourquoi Komodo plutôt que Portainer ou Dockge ?
Portainer et Dockge sont des interfaces mono-serveur : elles lisent le socket Docker local et vous donnent une vue de ce qui tourne sur cette machine. Dès que vous avez deux serveurs ou plus, vous devez ouvrir deux onglets, vous souvenir de quel service tourne où, et répliquer chaque changement à la main. Komodo brise ce plafond avec son architecture Core/Periphery : le Core est un serveur central qui pilote des agents Periphery légers sur chaque machine. Vous déployez, redémarrez ou mettez à jour n'importe quelle stack depuis une interface unique, avec un historique complet de qui a fait quoi et quand.
Ce que Komodo apporte au-delà de la gestion de conteneurs
- GitOps natif — liez un dépôt Git, définissez une Procedure de déploiement, et déclenchez-la automatiquement sur chaque
git pushvia webhook HMAC. - Procedures réutilisables — enchaînez pull d'image, migration de base, restart de stack et notification Slack en un seul workflow versionnable.
- Docker Swarm — gérez services Swarm, réplicas et rolling updates depuis la même interface que vos stacks Compose.
- Alertes natives Slack/Discord — configurez des canaux d'alerte pour les échecs de déploiement, les conteneurs arrêtés et les ressources critiques.
- RBAC multi-utilisateurs — accordez des accès granulaires par rôle (viewer, builder, deployer) sans partager le compte admin.
- API REST complète — automatisez vos déploiements depuis votre CI/CD (GitHub Actions, Woodpecker, Forgejo) sans passer par l'interface web.
Architecture Core/Periphery en pratique
Le Core est le cerveau : il stocke la configuration dans FerretDB (une couche MongoDB-compatible), expose l'interface web sur le port 9120 et reçoit les webhooks. Les agents Periphery sont les bras : chacun tourne sur un serveur cible, expose le socket Docker de la machine au Core via un canal chiffré, et exécute les commandes que le Core lui envoie. La clé asymétrique générée à l'initialisation garantit que seul votre Core peut commander vos agents — aucun secret supplémentaire à gérer. Sur un VPS ServOrbit, le Periphery local est déployé dans le même stack Docker Compose que le Core, ce qui signifie que le serveur d'hébergement est lui-même géré dès le premier démarrage.
Déployer Komodo sur votre VPS ServOrbit
Commandez le VPS
Un VPS 1 vCPU / 1 Go RAM sur Ubuntu 24.04 LTS est suffisant pour le plan de contrôle Komodo (Core + FerretDB). Le Core Rust idle sous 256 Mo. Si vous prévoyez de faire tourner d'autres services sur le même VPS, optez pour 2 Go de RAM.
Déployez depuis le marketplace ServOrbit
Dans votre espace client ServOrbit, accédez à Marketplace → Déploiement Applicatif & DevOps → Komodo et cliquez sur Déployer. Indiquez votre domaine ou sous-domaine — requis pour
KOMODO_HOST. Le playbook génère automatiquement les secrets JWT, le keypair Core/Periphery et le mot de passe admin, puis démarre les services. Le tableau de bord Komodo est disponible sur le port 9120 en HTTPS.Connectez-vous et vérifiez l'agent local
Ouvrez
https://votre-domaine.com:9120et connectez-vous avec le loginadminet le mot de passe affiché dans votre espace client. Dans le menu Servers, vous devriez voir un serveur « Local » déjà enregistré — c'est l'agent Periphery du VPS d'hébergement qui s'est auto-connecté au démarrage. Changez votre mot de passe depuis les paramètres du compte dès cette première connexion.Connectez un serveur distant via Periphery
Sur chaque VPS supplémentaire à gérer, installez l'agent Periphery :
docker run -d --restart=unless-stopped --network host -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/moghtech/komodo-periphery:latest. Puis dans Komodo, allez dans Servers → Add Server, entrez l'adresse IP et le port 8120 de l'agent. Le Core valide la connexion avec la clé publique Periphery générée à l'initialisation. Votre flotte de serveurs apparaît immédiatement dans le tableau de bord.Créez votre première stack depuis le marketplace
Dans Komodo, allez dans Stacks → New Stack. Choisissez le serveur cible dans la liste déroulante (Local ou tout agent ajouté), collez votre Docker Compose YAML ou pointez vers un chemin de dépôt Git, et cliquez Deploy. Komodo écrit le fichier sur le serveur distant, lance
docker compose up -det affiche les logs en temps réel dans l'interface.Configurez les alertes Slack ou e-mail
Dans Komodo, allez dans Alerters → New Alerter. Choisissez le type (Slack, Discord, e-mail) et collez le webhook ou l'adresse de destination. Puis associez l'alerter à vos ressources (Stacks, Builds, Servers) via la section Alerts de chaque ressource. Vous recevez une notification immédiate en cas d'échec de déploiement ou de conteneur arrêté.
Configurez un pipeline GitOps
Dans votre dépôt GitHub, ajoutez un webhook vers
https://votre-domaine.com/api/webhook/komodoavec le secret HMAC défini dans Komodo. Créez une Procedure nommée « Deploy App » : pull image, restart stack, notification. Liez le webhook à cette Procedure. Chaquegit pushdéclenche maintenant le pipeline — la signature HMAC est vérifiée côté Komodo avant exécution.Intégrez votre CI/CD via l'API REST
Komodo expose une API REST complète sur
/api. Depuis GitHub Actions, déclenchez un déploiement avec un appelPOST /api/execute/procedure/<nom>et le token API de votre service account. Cette intégration vous permet d'enchaîner tests, build d'image et déploiement dans un seul workflow CI sans accès direct à la machine.
GitOps avec webhooks : déployer sur chaque push
Le cycle GitOps de Komodo repose sur trois composants : un dépôt Git, un webhook HTTP, et une Procedure. Côté GitHub, créez un webhook dans Settings → Webhooks, pointez vers https://votre-domaine.com/api/webhook/komodo, choisissez le type de contenu application/json et définissez un secret. Côté Komodo, dans la section Webhooks d'une Stack ou d'une Procedure, collez ce même secret — Komodo calcule le HMAC SHA-256 de chaque payload entrant et rejette les requêtes dont la signature ne correspond pas.
La Procedure de déploiement typique enchaîne trois actions : PullImage (télécharge la dernière image depuis votre registry), DeployStack (lance ou recrée les conteneurs), puis SendAlert (notifie votre canal Slack). Si une étape échoue, Komodo stoppe la Procedure et envoie l'erreur complète à votre alerter — vous n'obtenez jamais un déploiement silencieusement à moitié appliqué.
Une subtilité à connaître : Komodo valide la branche du push contre la branche configurée dans la Stack avant de déclencher. Un push sur une branche de feature ne déclenchera pas un déploiement de production, même si le webhook cible la même URL. Configurez une Stack par environnement (staging sur la branche dev, production sur main) et vous obtenez un pipeline de promotion entièrement automatisé.
Créer une Procedure Komodo : pull, migration, redémarrage
Créez la Procedure
Dans Komodo, allez dans Procedures → New Procedure. Donnez-lui un nom (
deploy-app) et sélectionnez le serveur cible. Une Procedure est une liste ordonnée d'étapes — chaque étape dispose d'un type (PullImage, DeployStack, RunCommand, SendAlert) et de paramètres.Ajoutez l'étape PullImage
Cliquez Add Step → PullImage. Entrez le nom de l'image (ex.
ghcr.io/monorg/monapp:latest) et le serveur sur lequel la tirer. Si votre image est dans un registry privé, ajoutez les credentials dans Settings → Registries avant cette étape — Komodo les injecte automatiquement lors du pull.Ajoutez une commande de migration
Cliquez Add Step → RunCommand. Dans le champ Command, entrez la commande de migration à exécuter dans le conteneur (ex.
docker exec app php artisan migrate --force). Activez l'option « Stop on error » : si la migration échoue, la Procedure s'arrête avant de redémarrer le service, ce qui évite de laisser une application avec un schéma incohérent.Ajoutez le redémarrage de stack
Cliquez Add Step → DeployStack et sélectionnez la Stack cible. Komodo lance
docker compose up -d --pull never(l'image a déjà été tirée à l'étape précédente) et reconstruit les conteneurs modifiés. Les variables d'environnement définies dans la Stack sont passées automatiquement.Ajoutez une notification de fin
Cliquez Add Step → SendAlert et sélectionnez votre Alerter Slack ou Discord. Vous pouvez inclure des variables de contexte dans le message (
{{ procedure.name }},{{ server.name }}) pour identifier d'un coup d'œil quelle Procedure sur quel serveur vient de s'exécuter.
Komodo vs Portainer vs Dockge
Faites défiler le tableau
| Fonctionnalité | Komodo | Portainer CE | Dockge |
|---|---|---|---|
| Multi-serveurs natif | ✅ Core/Periphery (multi-nœuds) | ⚠️ Edge agents (version payante) | ❌ Un seul hôte |
| GitOps / webhooks | ✅ Natif, HMAC validé | ❌ Non natif | ❌ Non natif |
| Procedures / automatisation | ✅ Moteur intégré | ⚠️ Limité CE | ❌ Non |
| API REST | ✅ Complète | ✅ Complète | ❌ Non |
| Alertes natives | ✅ Slack, Discord, e-mail | ⚠️ Partiel CE | ❌ Non |
| Audit log | ✅ Toutes actions | ⚠️ Partiel CE | ❌ Non |
| Licence / prix | GPL-3.0, gratuit | Zlib (CE gratuit) / Business payant | MIT, gratuit |
Dépannage : erreurs fréquentes et solutions
Periphery agent unreachable. L'erreur la plus courante lors de l'ajout d'un nouveau serveur. Vérifiez d'abord que le pare-feu du serveur distant autorise les connexions entrantes sur le port 8120 depuis l'IP de votre Core. Ensuite, vérifiez que la variable KOMODO_HOST de l'agent Periphery correspond bien à l'IP ou au domaine que le Core utilise pour le joindre — une mauvaise valeur laisse l'agent démarrer sans erreur mais le rend injoignable.
Failed to pull image. Komodo retourne cette erreur quand le registry privé n'est pas accessible ou que les credentials sont manquants. Ajoutez vos credentials dans Settings → Registries (Docker Hub, GHCR, registry privé) avant de déclencher un pull. Si l'image est publique et que l'erreur persiste, vérifiez que le serveur cible a bien accès à Internet sur le port 443.
Webhook not triggered. Deux causes principales : le secret HMAC configuré dans Komodo ne correspond pas à celui saisi dans GitHub, ou l'URL de votre Core n'est pas accessible depuis les serveurs GitHub (derrière un pare-feu ou un VPN). Vérifiez l'onglet « Recent Deliveries » dans GitHub pour voir le code HTTP retourné — un 401 indique un secret incorrect, un timeout indique un problème réseau. Vérifiez aussi que la branche du push correspond à celle configurée dans votre Stack ou Procedure.
Délai au premier démarrage (FerretDB). FerretDB effectue une initialisation de sa base interne au premier lancement, ce qui peut prendre 30 à 60 secondes avant que l'interface Komodo réponde. Si vous voyez une erreur de connexion immédiatement après le déploiement, attendez une minute et rechargez la page avant de diagnostiquer un problème d'installation.
Komodo + Dockge : deux outils complémentaires
Komodo et Dockge ne s'excluent pas. Dockge est parfait pour l'édition interactive de fichiers Compose sur une seule machine (interface YAML avec coloration syntaxique). Komodo gère la coordination multi-serveurs, les déploiements Git et les workflows. Déployez Dockge via Komodo sur vos machines de développement, et utilisez Komodo pour orchestrer les déploiements de production.
