Install a cluster

Stand up a 4-node Samoza cluster — one cloud control plane, three edge workers — in under an hour.

A Samoza cluster is one or more zhosts networked together by zmesh. One zhost runs the control plane and acts as the super node; the rest run workloads. This guide walks you through deploying a 4-node cluster: 1 cloud node and 3 edge nodes.

Architecture at a glance

                    ┌─────────────────────────────────┐
                    │         CLOUD NODE              │
                    │   (Control Plane + Super Node)  │
                    │  zbase · zmesh-controlplane     │
                    │  zmesh (super) · zrms (super)   │
                    └───────────────┬─────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
       ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
       │ EDGE NODE 1 │      │ EDGE NODE 2 │      │ EDGE NODE 3 │
       │ zmesh · zrun│      │ zmesh · zrun│      │ zmesh · zrun│
       └─────────────┘      └─────────────┘      └─────────────┘

What each node runs:

Prerequisites

On every node:

# Build the binaries
cd /path/to/samoza
go build -o bin/zbase ./components/zbase/cmd/zbase
go build -o bin/zmesh ./components/zmesh/cmd/zmesh
go build -o bin/zmesh-controlplane ./components/zmesh/cmd/zmesh-controlplane
go build -o bin/zrms ./components/zrms/cmd/zrmsd
go build -o bin/zrun ./components/zrun/cmd/zrun
go build -o bin/startz ./core/cmd/startz

On the cloud node only: a PostgreSQL database, a public IP or DNS name reachable by edge nodes, and ports 7071, 9000, 9200, 7331 open.

On edge nodes only: network access to the cloud node’s control plane (port 9000), and port 8080 open for the local zrun.

Step 1 · Start the cloud node

The cloud node is the control plane — start it first.

export ZMESH_REGION="cloud-central"
export ZMESH_NETWORK="samoza-prod"
export ZBASE_DB_URL="postgres://user:password@localhost:5432/samoza"

./bin/startz -config configs/samoza_cloud.yaml

startz brings up zbase, zmesh-controlplane, zmesh (super mode), and zrms in the right order. If you’d rather start them by hand, see the stack overview.

Verify the cloud node:

curl http://127.0.0.1:7071/healthz       # zbase: ok
curl http://127.0.0.1:9000/v1/zhosts     # control plane: empty array
curl http://127.0.0.1:9200/v1/status     # zmesh: mode "super"
curl http://127.0.0.1:7331/v1/health     # zrms: status "healthy"

Step 2 · Start the first edge node

Replace cloud.example.com with your cloud node’s actual address.

export ZMESH_CONTROLPLANE="ws://cloud.example.com:9000/ws"
export ZMESH_REGION="edge-site-1"
export ZMESH_CLUSTER="edge-cluster"
export ZMESH_ZHOST_ID="edge-node-1"

./bin/startz -config configs/samoza_edge.yaml

Verify on the edge node:

curl http://127.0.0.1:9200/v1/status     # mode "local", connected: true
curl http://127.0.0.1:8080/v0/health     # zrun: status "ok"

And on the cloud node, the edge should now appear:

curl http://127.0.0.1:9000/v1/zhosts | jq .

Step 3 · Add more edge nodes

Same pattern with different ZMESH_ZHOST_ID and ZMESH_REGION per node:

export ZMESH_ZHOST_ID="edge-node-2"
export ZMESH_REGION="edge-site-2"
./bin/startz -config configs/samoza_edge.yaml

Repeat for as many edges as you want.

Step 4 · Verify the cluster

From the cloud node:

curl -s http://127.0.0.1:9000/v1/zhosts | jq .
# Expected: array of all super + local nodes

curl -s http://127.0.0.1:7331/v1/cluster/status | jq .

Or use zshell:

./bin/zshell

zshell[0] >> status
zshell[1] >> mesh peers
zshell[2] >> cluster zhosts

Environment variables

Ports

Shutting down

If you started with startz, Ctrl+C gracefully stops everything in reverse order. By hand: stop edge nodes first (zrun → zmesh → zbase), then the cloud node (zrms → zmesh → zmesh-controlplane → zbase).

Next

Your cluster is up. Time to deploy something on it — see your first topology, or dive into the zshell tour to learn the operator’s interface.