Configuration reference#

All guides · Installation · Glossary

Use this page to look up a specific setting. You do not need to configure every option to get started.

Where to make changes: use the dashboard for day-to-day deployment, alert, and supported network settings. Startup flags and environment changes need a manager restart. With Compose, use your .env and the service configuration; with systemd, use the protected environment file or a service override. Preserve credentials across restarts.

Network settings: console-managed mesh settings survive restarts. Explicit networking flags or nonempty networking environment values override saved console settings at startup. Omitting all those options preserves console-managed settings; an explicitly empty --cluster-network disables the mesh. Coordinate changes across every HA manager.

The tables below list configurable options and built-in limits.

• Control plane flags
• Control plane environment
• Data directory
• Worker agent
• zela
• Alert rules
• Built-in timings and limits
• Test-only variables

Control plane flags#

zela-server [flags]. Run zela-server --help for the authoritative list for your build.

Control plane environment#

Generate secrets with:

openssl rand -hex 32      # admin token, worker token, database password
openssl rand -base64 32   # vault key

Data directory#

--data is created with private permissions and locked with <data>/.lock, so two processes can't share it.

With PostgreSQL, the three JSON documents live in the zela.state table instead. Leftover JSON files are ignored once the database is initialized.

Worker agent#

zela-worker [flags], normally run by systemd.

SSH-provisioned workers use /etc/zela/worker.env (mode 0640, root:docker) and zela-worker.service, listening on 127.0.0.1:<agent-port> (default 9091). Change flags with systemctl edit zela-worker. Monitoring → Update agent preserves existing service flags.

In HA clusters, the agent rejects requests carrying a leadership epoch lower than the highest it has seen (HTTP 409). See HA fencing.

zela#

zela mcp serve [--read-only] runs an MCP server over stdio using the same connection settings. stdout carries protocol frames and diagnostics go to stderr, so --token-file - is rejected there. Create the token with zela tokens create --scope mcp_read|mcp_manage.

Precedence: flags, then environment, then profile. Tokens are only sent over HTTPS, or plain HTTP to loopback. See the CLI guide.

Deployment ports#

Each entry in a deployment's ports has these fields:

Deployments also accept routes for the edge proxy: [{"host": "shop.example.com", "path": "/", "port": 8080}]. Replace them later with PUT /api/deployments/{id}/routes.

Workers also accept an optional networkEndpoint (zela … --network-endpoint), the address cluster-network peers use instead of the SSH or agent host.

Alert rules#

Cluster-wide, set in Alerts → Configure thresholds, zela monitoring set-rules --file rules.json, or POST /api/monitoring/rules:

{
  "cpuPercent": 90,
  "memoryPercent": 90,
  "diskPercent": 85,
  "resourceForSeconds": 60,
  "offlineForSeconds": 30,
  "healthForSeconds": 30
}

Fixed alerts:

Built-in timings and limits#

These are compiled-in defaults, listed so you can reason about behavior. They are not configurable at runtime.

Test-only variables#

These are used by optional integration tests; production never reads them. See CONTRIBUTING.