Kontrol — Docker Orchestration Platform

Plateforme d'orchestration Docker multi-hotes, ecrite integralement en Go.

Architecture

kontrol-server   →  API REST + WebSocket + Orchestrateur (reconciler, scheduler, healthcheck)
kontrol-agent    →  Agent Docker sur chaque hote (conteneur privilegie)
kontrol-compose  →  CLI de deploiement
kontrol-ui       →  SPA React/TypeScript (dashboard, gestion stacks/services/containers)
PostgreSQL       →  Base de donnees principale
Redis            →  Cache + pub/sub + leader election

Prerequis

• Go 1.23+
• Node.js 22+ (pour le frontend)
• Docker 24+ et Docker Compose v2
• PostgreSQL 17 (fourni via docker-compose)

Demarrage rapide (< 5 min)

1. Lancer la stack complete (dev)

# Clone le repo
cd kontrol

# Lancer toute l'infra via Docker Compose
make dev

Cela demarre : server (port 8080), UI (port 3000), PostgreSQL, Redis, DNS.

Acceder a l'interface : http://localhost:3000

2. Build local (sans Docker)

# Installer les dependances Go
go mod tidy

# Build tous les binaires
make build

# Les binaires sont dans bin/
ls bin/
# kontrol-server  kontrol-agent  kontrol-compose

3. Lancer le serveur manuellement

# Demarrer PostgreSQL + Redis (si pas deja via docker-compose)
docker compose -f deployments/docker-compose.yml up -d postgres redis

# Variables d'environnement requises
export KONTROL_DB_URL="postgres://kontrol:kontrol@localhost:5432/kontrol?sslmode=disable"
export KONTROL_SECRET_KEY="change-me-in-production"
export KONTROL_HTTP_PORT=8080
export KONTROL_LOG_LEVEL=debug

# Lancer le serveur
./bin/kontrol-server

Le serveur :

• Execute les migrations automatiquement au demarrage
• Ecoute sur le port 8080 (API REST + WebSocket)
• Demarre le reconciler (boucle toutes les 5s)
• Demarre le healthchecker (boucle toutes les 10s)

4. Lancer le frontend (dev)

cd web
npm install
npm run dev

Le frontend demarre sur http://localhost:5173 avec proxy vers le serveur sur :8080.

5. Enregistrer un hote (agent)

# Depuis le serveur, creer un hote via l'API pour obtenir un token
curl -X POST http://localhost:8080/v1/environments/<ENV_ID>/hosts \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "host-01", "ip": "192.168.1.10"}'

# Reponse contient le registration_token

# Sur la machine hote, lancer l'agent
docker run -d --privileged \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/kontrol:/var/lib/kontrol \
  -e KONTROL_AGENT_IP=192.168.1.10 \
  kontrol/agent:latest \
  http://KONTROL_SERVER:8080/v1/register/<REGISTRATION_TOKEN>

6. Deployer une stack via CLI

# Dans un repertoire avec docker-compose.yml et kontrol-compose.yml
kontrol-compose \
  --url http://server:8080 \
  --access-key <key> --secret-key <secret> \
  --env Production \
  --stack MyApp \
  up -d

# Scaler un service
kontrol-compose --stack MyApp scale web=3

# Voir les logs
kontrol-compose --stack MyApp logs -f web

# Lister les conteneurs
kontrol-compose --stack MyApp ps

# Upgrader (rolling)
kontrol-compose --stack MyApp up --upgrade

# Confirmer ou rollback
kontrol-compose --stack MyApp up --confirm-upgrade
kontrol-compose --stack MyApp up --rollback

# Stopper / supprimer
kontrol-compose --stack MyApp stop
kontrol-compose --stack MyApp rm

Commandes Make

Commande	Description
make build	Build les 3 binaires (server, agent, cli)
make build-server	Build uniquement le serveur
make build-agent	Build uniquement l'agent
make build-cli	Build uniquement le CLI
make test	Lancer les tests
make test-coverage	Tests avec rapport de couverture
make dev	Lancer la stack Docker Compose de dev
make docker-build	Build les images Docker
make lint	Lancer le linter (golangci-lint)
make fmt	Formater le code
make clean	Nettoyer les binaires

Configuration (variables d'environnement)

Variable	Default	Description
KONTROL_DB_URL	—	URL PostgreSQL (requis)
KONTROL_SECRET_KEY	—	Cle secrete JWT (requis)
KONTROL_HTTP_PORT	8080	Port HTTP du serveur
KONTROL_OVERLAY_SUBNET	10.42.0.0/16	Subnet du reseau overlay
KONTROL_CATALOG_URL	—	URL du catalogue Git
KONTROL_REGISTRATION_TOKEN	—	Token bootstrap pour l'enregistrement agent
KONTROL_LOG_LEVEL	info	Niveau de log (debug, info, warn, error)
KONTROL_REDIS_URL	—	URL Redis

API

L'API REST est disponible sur /v1/. Endpoints principaux :

• Auth : POST /v1/auth/login, GET /v1/auth/me
• Environments : CRUD sur /v1/environments
• Hosts : /v1/environments/:envId/hosts
• Stacks : /v1/environments/:envId/stacks + start/stop/export
• Services : CRUD + scale/upgrade/rollback
• Containers : CRUD + start/stop/restart + logs + exec
• Volumes, Networks, Secrets, Registries : CRUD standard
• Catalog : list/get/sync/deploy
• WebSocket : /v1/connectbackend (agents), /v1/subscribe (UI live updates)

Structure du projet

kontrol/
├── cmd/
│   ├── server/          # Entrypoint serveur
│   ├── agent/           # Entrypoint agent
│   └── cli/             # CLI kontrol-compose (cobra)
├── internal/
│   ├── api/             # REST API (chi) + middleware + WebSocket hub
│   ├── orchestrator/    # Reconciler, scheduler, healthcheck, upgrader
│   ├── agent/           # Agent Docker (WS, docker ops, healthprobe, metadata)
│   ├── network/         # Overlay WireGuard, IPAM, DNS, HAProxy LB
│   ├── store/           # Interfaces + PostgreSQL (pgx)
│   ├── events/          # Event bus pub/sub
│   ├── auth/            # JWT + local auth (bcrypt)
│   ├── compose/         # Parser docker-compose + kontrol-compose
│   ├── config/          # Configuration (viper)
│   └── models/          # Entites + erreurs
├── web/                 # Frontend React/TypeScript (Vite + Tailwind + shadcn)
├── migrations/          # Migrations SQL (golang-migrate)
├── deployments/         # Docker Compose (dev + prod) + nginx
├── Dockerfile.server    # Image serveur (distroless)
├── Dockerfile.agent     # Image agent (alpine + wireguard)
├── Dockerfile.ui        # Image UI (nginx)
└── Makefile

Production

# Build des images
make docker-build VERSION=1.0.0

# Deployer avec le fichier prod
docker compose \
  -f deployments/docker-compose.yml \
  -f deployments/docker-compose.prod.yml \
  up -d

Variables a definir en prod :

• KONTROL_DB_URL — PostgreSQL externe
• KONTROL_SECRET_KEY — Cle secrete forte (32+ caracteres)
• POSTGRES_PASSWORD — Mot de passe PostgreSQL
• REDIS_PASSWORD — Mot de passe Redis
• KONTROL_VERSION — Version des images