When you roll out a container orchestrator on a real production Linux server, you rarely start with an empty machine. Most teams face the classic brownfield reality:
- Containers have already been running for months.
- Some were launched with
docker compose, others manually withdocker run. - Nobody remembers where the original
docker-compose.ymllives—or it doesn't exist at all. - And rule #1 of production still applies: you cannot stop or restart live workloads just because you installed an orchestrator.
In Gubernator v4.0, we tackled this exact problem head-on with a native Unmanaged Container Discovery & Zero-Downtime Stack Adoption engine powered by docker inspect reverse-engineering.
🧭 The Goal: Govern Live Workloads Without Breaking Them
Most orchestrators assume a greenfield world: "redeploy everything from scratch using my manifests." In practice, migrating running services usually means scheduling maintenance windows, recreating containers by hand, or painfully reconstructing YAML files line by line from raw docker inspect JSON.
In Gubernator v4.0, brownfield adoption follows a safe, two-phase workflow:
Production Docker Hosts (Manager + Workers) │ ▼ 1. Non-Intrusive Scan (Zero-Touch) ┌──────────────────────────────────────────────────────────┐ │ Unmanaged / Discovered (Cluster-Wide) │ │ • Auto-grouped by com.docker.compose.project │ │ • Detects standalone containers (docker run) │ │ • Day-1 actions: status, start, stop, restart │ └─────────────────────┬────────────────────────────────────┘ │ ▼ 2. Reverse-Engineering (docker inspect) ┌──────────────────────────────────────────────────────────┐ │ docker-compose.yml Generator + Interactive YAML │ │ • Extracts image, ports, volumes, networks, env, limits │ │ • Filters image-default env vars via docker image inspect│ │ • Optional toggle to read original host compose file │ └─────────────────────┬────────────────────────────────────┘ │ ┌─────────────┴─────────────┐ ▼ ▼ Adopt (Zero-Downtime) Adopt & Redeploy Registers Stack & Tasks Adopts and redeploys under without restarting anything Gubernator DNS / Load Balancing 🔎 Step 1: Multi-Node Automatic Discovery (Unmanaged / Discovered)
With Gubernator v4.0's new 3-level collapsible sidebar, Cluster → Legions [Stacks] now provides two dedicated subsections:
- Managed Stacks: your standard Gubernator-orchestrated stacks.
- Unmanaged / Discovered: a cluster-wide radar that scans both the Manager (locally) and all Worker Centurions (over SSH) for any running or stopped container not tracked by Gubernator and not belonging to internal system infrastructure (
CORE-GBNT, monitoring, etc.).
Smart Automatic Grouping
Instead of dumping a flat, noisy list of containers, Gubernator inspects Docker's native metadata:
- Docker Compose Projects (
COMPOSE PROJECT): containers created withdocker composealready carrycom.docker.compose.project,com.docker.compose.service, andcom.docker.compose.project.config_files. Gubernator automatically groups them into a single project card showing the detected host YAML path. - Standalone Containers (
DOCKER RUN): manually started containers appear under Standalone with multi-select checkboxes, letting you adopt a single container or bundle multiple standalone containers into a brand-new Stack.
🛠️ Step 2: Reverse-Engineering docker-compose.yml from docker inspect
Clicking Adopt Project as Stack (or Adopt Selected) runs docker inspect on the target host and synthesizes a clean, production-ready docker-compose.yml:
- Runtime identity:
image,container_name, andrestart(RestartPolicy). - Networking & ports: deduplicated
ports(hostIP:hostPort:containerPort) and custom Docker networks automatically declared asexternal: true. - Persistent storage:
bind mounts(preserving:roflags) and named volumes declared asexternal: trueso existing data is never lost. - Smart
environmentcleanup: a common pain point with naivedocker inspectgenerators is dumping dozens of boilerplate image variables (PATH,GOSU_VERSION, etc.). Gubernator cross-referencesdocker image inspectand strips out image-default variables, keeping only real user-configured environment variables. - Operations & limits: overridden
command,working_dir,user,healthcheck, and CPU/Memory limits (deploy.resources.limits). - Bonus — Original Host Compose File: if
com.docker.compose.project.config_filespoints to a readable file on the host, the adoption dialog exposes a one-click toggle to switch between thedocker inspectreconstruction and the original hostdocker-compose.yml.
⚡ Step 3: Two Adoption Modes (You Choose When to Restart)
Inside the interactive adoption modal, you can review or tweak the generated YAML (for example, adding depends_on or Load Balancing ingress labels) and choose how to adopt:
- Adopt (Zero-Downtime): saves the
Stack,RawComposeFile,Services, andTasksinto Gubernator's SQLite state, binding them directly to the live running containers. Zero restarts, zero downtime. The stack immediately appears in Managed Stacks under full Gubernator lifecycle control. - Adopt & Redeploy: registers the stack and immediately triggers a managed Gubernator Redeploy to recreate it with CoreDNS records, Load Balancing routes, or updated configuration.
🧪 Live Test: Adopting a 3-Container App (web + api + cache)
On a 2-node cluster (gbnt-manager + gbnt-worker1), we spun up a standalone 3-tier docker compose application completely outside Gubernator:
-
legacy-demo-web(nginx:alpine, port8095:80, read-onlynginx.confbind mount) -
legacy-demo-api(hashicorp/http-echo:latest, connected over private networklegacy-net) -
legacy-demo-cache(redis:7-alpine, named volumelegacy_redis_data+healthcheck)
Opening Cluster → Legions [Stacks] → Unmanaged / Discovered hits GET /api/unmanaged and immediately detects:
{ "total_containers": 3, "total_groups": 1, "groups": [ { "group_key": "node-local-manager::legacy-demo", "group_name": "legacy-demo", "node_id": "node-local-manager", "source_type": "compose", "compose_config_files": "/home/ubuntu/legacy-demo/docker-compose.yml", "running_count": 3, "total_count": 3 } ] } With one click on Adopt Project as Stack → Adopt (Zero-Downtime), all three interconnected containers become a versioned, editable Gubernator Stack—without dropping a single request.
🏛️ REST API Endpoints
For automation and CI/CD pipelines, the entire workflow is exposed behind Gubernator's RBAC layer:
| Endpoint | Method | Description |
|---|---|---|
/api/unmanaged | GET | Scans Manager and Workers for external containers, grouped by Compose project or standalone. |
/api/unmanaged/generate-compose | POST | Reconstructs docker-compose.yml from docker inspect (or loads the original host Compose file). |
/api/unmanaged/adopt | POST | Registers the Stack, Services, and Tasks with Zero-Downtime without restarting live containers. |
/api/unmanaged/action | POST | Day-1 lifecycle actions (start, stop, restart, rm) on unmanaged containers. |
🚀 Wrapping Up
With unmanaged discovery and zero-downtime adoption, installing Gubernator on existing Docker servers stops being a risky migration and becomes a smooth, incremental transition:
- Install Gubernator without touching running workloads.
- Discover every Compose project and
docker runcontainer across your nodes. - Reconstruct & review clean
docker-compose.ymlmanifests automatically. - Adopt services into managed stacks with zero downtime.
Have you ever had to reconstruct a lost docker-compose.yml in production from raw docker inspect output? Drop your war stories in the comments!


