Usage
How to invoke zisk-coordinator, the cluster orchestrator that accepts proof requests and fans work out to workers. Covers its three configuration sources and override precedence, the operationally relevant defaults, signal handling, and worked examples.
zisk-coordinator is the cluster orchestrator.
It accepts proof requests from clients, fans work out to
registered workers, and serves /metrics and /health. CPU and
memory needs are modest; what matters is network headroom.
zisk-coordinator [OPTIONS]
Configuration
zisk-coordinator reads its settings from three sources, plus
built-in defaults for anything you don't set:
- TOML config file passed via
--config <PATH>. The canonical home for long-lived settings: ports, bind addresses, logging, metrics, coordinator-core tuning. The full schema is documented on Configuration. - Environment variables with the
ZISK_COORDINATOR_*prefix, plus the standardRUST_LOG. Use these for values that come from the deployment substrate rather than the application. Full mapping on CLI & environment. - Command-line flags for ports, log level, and the config path
itself. The narrowest layer; use for one-off testing,
container entrypoints, or the systemd unit's
ExecStart. Full flag list on CLI & environment.
Override precedence
Settings are resolved in four layers, with later sources winning:
- Built-in defaults.
- TOML config file.
- Environment variables.
- Command-line flags.
Example: a TOML with [server].port = 7000 is shifted to 7001
by ZISK_COORDINATOR_API_PORT=7001, and to 8000 by
--api-port 8000 as CLI wins over env, env wins over TOML.
Defaults
If you start zisk-coordinator with no flags and no config file,
the built-in defaults take over. The full schema is on
Configuration; the most operationally relevant
defaults are:
| Setting | Default | Override |
|---|---|---|
| Client-facing gRPC port | 7000 | [server].port / --api-port |
| Worker-facing gRPC port | 50051 | [coordinator].port / --cluster-port |
Metrics + /health port | 9090 | [metrics].port / --metrics-port |
| Bind address (all three servers) | 0.0.0.0 | [server].host, [metrics].host |
| Log level | info | [logging].level / --log-level / RUST_LOG |
| Log format | pretty | [logging].format |
| Shutdown drain window | 30s | [server].shutdown_timeout_seconds |
| Environment label | development | [service].environment |
Signals
| Signal | Effect |
|---|---|
SIGTERM / SIGINT | Graceful shutdown. The coordinator stops accepting new jobs and waits up to [server].shutdown_timeout_seconds for in-flight jobs to drain. Jobs still running at the deadline are abandoned and surface as Failed from the client's view. |
SIGKILL | Forced exit. In-flight jobs are abandoned with no notification to workers; workers detect the disconnect via heartbeat timeout and clear their assignments. |
The coordinator does not persist job state across restarts; restarting drops every in-flight job. Plan capacity and restart windows accordingly.
Examples
Run with the canonical config installed by the deploy script:
zisk-coordinator --config /etc/zisk/coordinator.toml
Override ports — useful when running alongside another coordinator on the same host (Docker Compose's default for the supplied example) or behind a reverse proxy:
zisk-coordinator --config /etc/zisk/coordinator.toml \
--api-port 7001 --cluster-port 50052 --metrics-port 9091
Bump log verbosity for one-off debugging without touching the TOML:
zisk-coordinator --config /etc/zisk/coordinator.toml --log-level debug