How Zela fits together#

All guides · Glossary

The plain-language version#

You use the dashboard to ask the manager to run an application. The manager chooses a suitable worker, and Docker on that worker runs the application container. The manager saves settings and checks workers regularly.

You → Zela dashboard → Manager → Worker servers → Your applications
                          ↓
                 Saved settings and history

The manager coordinates work; your applications run on the workers. Restarting the manager normally leaves those application processes running, but management and monitoring pause. A manager backup also does not back up application files on the workers.

Technical connection map#

     Browser console / zela / Docker CLI & SDKs / AI clients (MCP)
                                     │  HTTPS :8080, Bearer token
                                     ▼
                ┌──────────────── control plane ─────────────────┐
                │ REST API · web console · Docker gateway         │
  (HA only)     │ scheduler · inventory poller · monitoring       │
  load balancer │ SSH provisioner · encrypted SSH-key vault       │
  ──/api/ready─►└───────┬───────────────────────┬────────────────┘
                        │ state                  │ worker traffic
                        ▼                        ▼
        PostgreSQL (or JSON files      ┌─────────────┬─────────────┐
        in --data for one manager)     │ HTTPS :9091 │ SSH tunnel  │  (one per worker)
                                       ▼             ▼
                                  zela-worker  →  /var/run/docker.sock  →  containers

Control plane#

A single Go binary (cmd/zela-server) that serves:

• Web console: static assets embedded in the binary, with no CDN and no frontend build step.
• REST API: /api/..., the endpoints the console, zela and integrations use.
• MCP server: /mcp (Streamable HTTP) exposes a fixed catalog of 19 named tools to AI clients, plus OAuth endpoints (/oauth/*, /.well-known/*) when ZELA_MCP_PUBLIC_URL is set. Every tool call re-enters the normal REST API in-process, so the usual authentication, scope checks, admission, operation gate and HA fencing all apply. zela mcp serve offers the same catalog over stdio for local assistants. See AI cluster management.
• Docker gateway: Docker Engine API paths (/version, /containers/..., /v1.51/...) that are routed to the right worker, so the whole cluster looks like one Docker endpoint.
• Background work:
  • Inventory poller: checks every worker every 10 seconds.
  • Operations runner: one cluster mutation at a time.
  • Failover: replaces replicas lost on dead workers.
  • Monitoring: alerts and notifications.

Mutations (deploy, scale, move, provision, and so on) run as operations. The API returns 202 with an operation ID and you poll for the result. Only one operation runs at a time; a second gets 409 until the first finishes.

Workers#

A worker is a Docker host. The control plane reaches it in one of three ways:

zela-worker authenticates every request with its token. It exposes a small allow-list of management routes, /zela/metrics, and the full Docker Engine API under /docker/ for the gateway. Treat its token as Docker-administrator, effectively root, access to that host.

State#

The --data directory is always needed, even with PostgreSQL. It holds the generated admin token, the vault master key (unless ZELA_VAULT_KEY is set) and temporary SSH identity files. See Configuration → Data directory.

A single PostgreSQL session holds an advisory lock. Exactly one manager writes at a time; a second standalone manager is refused.

Availability model#

Workers. The poller marks a worker offline after 3 consecutive failed probes, about 20–30 seconds. Once a worker has not been seen for 60 seconds, the control plane:

1. starts a Recover operation for every running deployment with replicas on that worker;
2. recreates those replicas on healthy workers;
3. remembers the old replicas. When the worker returns, they are re-adopted if the deployment is short of replicas, or removed otherwise, so a returning host never runs duplicates.

Failover recreates containers from their image and configuration. It does not move volumes, filesystem changes or in-memory state. Use it for stateless workloads.

Managers (optional HA). Several managers share one PostgreSQL database. The leader holds the advisory lock and checks it every 2 seconds; standbys answer 503 on /api/ready until they win the lock. Each new leader takes a higher leadership epoch and sends it on every worker request, and workers reject requests that carry a lower epoch. This fences off a stalled former leader. See High availability.

Networking. By default, replicas publish host ports on their worker. The opt-in cluster network (--cluster-network) adds an encrypted WireGuard mesh with a routed container subnet per worker, so containers reach each other across hosts by IP, service names (web.zela) answered by a resolver on every worker, a stable load-balanced virtual IP per deployment, and an optional edge proxy on every worker for external HTTP(S). See Networking.

Not provided: shared application storage, volume replication, or database replication. Automatic website certificates are available only when ACME is configured; they are not enabled merely by starting Zela. Docker restart policies handle restarts on a single host.

Trust boundaries#

See Security for hardening guidance.

Ports#