Skip to content

Gubernator Icon Gubernator (gbnt)

Gubernator is a "Goldilocks" container orchestrator built in Go — combining the simplicity of Docker Swarm (native Compose support, easy cluster joining) with the flexibility of Nomad (task-based logic, hardware/AI targeting via labels).

Themed around the Roman Empire, Gubernator manages containers across a fleet of nodes ("Centurions") from a central API ("The Senate"), now with a built-in local executor so a single node can run a complete cluster out of the box.

Key Features

Feature Description
Single binary gbnt runs as Manager and Worker
Docker Compose native Deploy any docker-compose.yml directly
Single-node mode No workers needed — the Manager runs containers locally
Built-in executor Passes ports, environment, volumes, and command to Docker
Flutter Web UI Live Material Design 3 dashboard with compose editor, clickable port links, dark/light themes, and user settings
Universal Worker Onboarding 3-tab onboarding suite (AddNodeDialog): Quick Join (1-liner), Remote SSH Provision with multi-auth & Live Terminal Console, and Cloud-Init YAML
Enterprise AD / LDAP & RBAC Single Sign-On with Active Directory, OpenLDAP, JWT HMAC-SHA256 sessions, and 3-tier RBAC (admin, operator, readonly)
Compliance & Hardening Suite Continuous automated auditing for CIS Docker Benchmark v1.6.0, ISO/IEC 27001:2022, European NIS 2 Directive, and Spanish ENS (100% ALTO)
Image Security & Gatekeeper Automated CVE scanning, CycloneDX/SPDX SBOMs, Cosign digital signatures, and pre-deployment admission control
Autoscaling & GPU Affinity Declarative horizontal autoscaling on GPU (NVIDIA DCGM) & CPU metrics with hardware affinity and single-host vs multi-host containment
Ingress + DNS Auto-configures CoreDNS and Caddy as containers start
Secure API Bearer token auth on port 4000, JWT / Session Auth on Web UI
Observability Prometheus metrics, Swagger, and health on port 4002
SRE Monitor One-command deploy: cAdvisor + Node Exporter + Prometheus + Grafana + Loki + Promtail + Jaeger

Port Architecture

Port Service Auth
:4000 REST API (CLI endpoint) Authorization: Bearer <GBNT_API_TOKEN>
:4001 Web UI Dashboard & SSO Active Directory / LDAP / JWT Cookie / Basic Auth
:4002 Telemetry, Swagger, Health Public (internal monitoring only)

Quickstart — Single Node

# 1. Clone and compile
git clone https://github.com/mario-ezquerro/gubernator.git
cd gubernator
go build -o gbnt ./cmd/gbnt

# 2. Start the Manager (with Web UI)
GBNT_API_TOKEN=admin \
GBNT_WEB=true \
GBNT_WEB_USER=admin \
GBNT_WEB_PASSWORD=admin \
./gbnt serve

# 3. In a second terminal — register the local node as worker
export GBNT_API_TOKEN=admin
./gbnt legion init
./gbnt legion join --token <TOKEN> --manager 127.0.0.1:4000

# 4. In a third terminal — deploy a stack (WordPress + MySQL)
./gbnt stack deploy -c examples/example-wordpress/docker-compose.yml

# 5. Verify
curl http://localhost:8080          # WordPress setup page
./gbnt task ls                      # See the running tasks

Open http://localhost:4001 (admin/admin) to see the live dashboard.

Quickstart — Docker

docker run -d \
  --name gbnt-manager \
  -p 4000:4000 -p 4001:4001 -p 4002:4002 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GBNT_API_TOKEN=admin \
  -e GBNT_WEB=true \
  -e GBNT_WEB_USER=admin \
  -e GBNT_WEB_PASSWORD=admin \
  -e GBNT_DNS_FORWARDERS="8.8.8.8 1.1.1.1" \
  cloudresources/gubernator:latest serve

How Deployment Works

gbnt stack deploy -c compose.yml
         │
         ▼
   API (port 4000)
         │
         ▼
   Parse YAML ──► Store Stack + Services + Tasks in SQLite
         │
         ▼
   Scheduler ──► Assigns Tasks to active Nodes
         │
         ├──► Local Executor (Manager, built-in)
         │         └──► docker pull + docker run -p -e -v
         │
         └──► Remote Worker (legion join)
                   └──► polls /v1/node/tasks → docker run
         │
         ▼
   Aqueducts ──► Update CoreDNS hosts + Caddyfile

New in v1.3.27: The Manager now includes a built-in local executor — containers are started automatically on the manager node without needing an external worker.

Web Dashboard

The Web UI at :4001 provides full lifecycle management:

  • View all stacks, services, nodes, and running containers (auto-refreshes every 5s)
  • Clickable port links — each container's mapped ports appear as clickable chips that open the service in your browser
  • Edit the compose YAML directly in the browser (syntax-highlighted editor)
  • Save & Redeploy — stops old containers and launches new ones in one click
  • Stop individual containers from the tasks table
  • Delete stacks with automatic container cleanup

🛡️ Compliance & Security Governance

Gubernator features a continuous multi-standard compliance engine accessible via Web UI (Security & Directory ➔ Compliance & Regulatory Suite) and CLI (gbnt cis, gbnt nis2, gbnt iso27001, gbnt security ens):

  • ISO/IEC 27001:2022 (Annex A): 24 Technological and Organizational container & DevOps controls across Theme A.5 and A.8 with Posture Grade (A+ to D) and Statement of Applicability (SoA) audit export.
  • CIS Docker Benchmark v1.6.0: 35 prescriptive hardening recommendations across Host, Daemon, Files, Images, Runtime, and Ops with Level 1 & 2 profiles and Posture Grade (A).
  • European NIS 2 Directive (EU 2022/2555): Automated risk-management assessment across all 10 Article 21(2) mandatory domains with CSIRT reporting (HIGH Readiness).
  • Esquema Nacional de Seguridad (ENS RD 311/2022): 100% ALTO certification with tamper-evident SHA-256 chained audit logs, real-time SIEM event forwarding, mandatory TOTP MFA, and AES-256-GCM encrypted backup schedules.
  • Active Directory, LDAP & RBAC: Enterprise directory integration with 4-tier RBAC (admin, operator, auditor, readonly) and emergency local access.
  • Image Security, SBOM & Gatekeeper: Pre-deployment admission control, CycloneDX/SPDX SBOM analysis, and Cosign cryptographic container signing.

(See the Compliance Hub Overview for the complete multi-framework matrix).

SRE Monitoring Stack

Deploy a full observability stack with one command:

./gbnt monitor init      # Deploy Prometheus, Grafana, Loki, cAdvisor, Promtail, Node Exporter, Jaeger
./gbnt monitor status    # Check health of monitoring containers
./gbnt monitor stop      # Tear down the stack
Service Port Purpose
cAdvisor :8081 Container resource metrics
Node Exporter :9100 Host hardware and OS metrics
Prometheus :9090 Metrics collection
Grafana :3000 Dashboards (admin/admin)
Loki :3100 Log aggregation
Promtail — Log shipping
Jaeger :4317, :4318, :16686 Distributed tracing OTLP (gRPC/HTTP) & UI /jaeger/

API Documentation

While ./gbnt serve is running, access:

Documentation

Core Guides

Orchestration, Compose & Networking

  • Compose & Smart Studio Reference — Exhaustive Docker Compose reference, auto-naming, dynamic variables, Studio IDE, and master labels cheat sheet
  • Multi-Host Placement & Scheduling — Distributed replica anti-affinity (spread: node.id), GPU/node affinity, and Caddy multi-upstream load balancing
  • Caddy Ingress Suite — Dynamic reverse proxy, Let's Encrypt / ZeroSSL automatic HTTPS, internal CA trust, WAF (Coraza), and active health checks
  • CoreDNS Discovery — Embedded DNS cluster resolver, auto-updating container records, and upstream forwarders
  • Declarative Autoscaling — Horizontal scaling engine driven by CPU and NVIDIA GPU metrics with cluster vs host scopes
  • Sloth SRE SLO Engine — Google SRE multi-burn-rate alerts, error budgets, and Prometheus recording rules
  • Persistent Storage & Backups — Shared Granaries (/var/contenedores/), Docker Named Volumes, /etc/fstab auto-mount, and compressed point-in-time backups
  • GlusterFS Distributed Storage — 3-way mirrored replica pools, peer discovery, and self-healing storage

Compliance & Security Suite

Current Development State

Gubernator v2.93.1 — Production-grade multi-host container orchestration with built-in SRE Observability Stack, Enterprise Directory, and Multi-Standard Compliance Suite.

View the complete Roadmap