Create a cluster

Applies to: current development build. This example creates a new cluster; it does not convert an existing standalone directory. Quorum authority is absent from public APT 0.1.0-2.

Define ownership and networking

Use three hosts with private connectivity. The examples use 10.0.0.11, 10.0.0.12, and 10.0.0.13; replace them with your own addresses. Every client, operator, and dashboard backend must reach the advertised endpoints.

A small learning map uses three partitions and RF2. Choose an appropriate fixed partition count before real ingestion; you cannot increase it later by adding nodes. Download the example map and authority peers.

{
  "cluster": "example-smkv", "epoch": 1,
  "nodes": [
    {"id":"n1","client":"10.0.0.11:7379","replication":"10.0.0.11:7380","admin":"10.0.0.11:7381"},
    {"id":"n2","client":"10.0.0.12:7379","replication":"10.0.0.12:7380","admin":"10.0.0.12:7381"},
    {"id":"n3","client":"10.0.0.13:7379","replication":"10.0.0.13:7380","admin":"10.0.0.13:7381"}
  ],
  "partitions": [
    {"primary":"n1","replica":"n2"},
    {"primary":"n2","replica":"n3"},
    {"primary":"n3","replica":"n1"}
  ]
}

Copy the same map to every node. Keep node IDs stable. Never use the same data directory for different nodes. This example uses identical entry/log budgets on all three nodes.

Choose the coordination mode before startup

Explicit ownership: omit authority seeds. The map defines owners and no automatic promotion occurs when a primary fails. This is a simpler evaluation setup.

Quorum ownership: add all three authority seeds to every data node at initial startup and run three persistent voters. This enables fenced promotion and controlled resizing, with an extra ownership-confirmation cost on client operations. Loss of quorum prevents successful reads and writes. Asynchronous record replication can still lose recently acknowledged writes.

Do not switch an existing live explicit-ownership cluster into quorum mode by simply adding flags. Use a planned migration into a fresh cluster.

Start the data nodes

On node n1, from the directory holding cluster.json:

smkv-server --cluster-map cluster.json --node-id n1 \
  --data-dir ./data-n1 --partitions 3 --workers 3 \
  --max-entries 100000 --max-log-bytes 1073741824 \
  --metrics-bind 10.0.0.11:9108

For n2/n3, change the node ID, local directory, and metrics address. The map supplies data, replication, and management binds. For quorum mode, append the following to each server command before starting it:

--authority-seed 10.0.0.11:7390 \
--authority-seed 10.0.0.12:7390 \
--authority-seed 10.0.0.13:7390

The default transports are plaintext and unauthenticated. Enable optional security consistently before exposing endpoints outside your trusted network.

Start quorum voters, if selected

Use peers.json containing all three voter endpoints. Keep voter directories separate from database directories and durable across restart. Start voters 2 and 3 with their own IDs and directories, omitting the bootstrap map. Once all data nodes are reachable and enrolled, start voter 1 with the map:

# On host 10.0.0.12
smkv-authority --id 2 --peers peers.json --data-dir ./voter-2 \
  --failover-after-seconds 10
# On host 10.0.0.13
smkv-authority --id 3 --peers peers.json --data-dir ./voter-3 \
  --failover-after-seconds 10
# On host 10.0.0.11
smkv-authority --id 1 --peers peers.json --data-dir ./voter-1 \
  --bootstrap-map cluster.json --failover-after-seconds 10

Run these on the indicated hosts in separate supervised processes. A value of 0 disables automatic promotion. Packaged installation does not configure a voter service for you. Authority-voter membership is fixed; resizing data nodes does not resize voters.

Verify before application traffic

smkv-ctl --seed 10.0.0.11:7381 info
smkv-ctl --seed 10.0.0.11:7381 partitions
smkv-ctl --seed 10.0.0.11:7381 health --json

Check the cluster name, all members, primary/replica ownership, readiness, and replication observations. Resolve incomplete discovery before proceeding. Use the Go cluster client to route keys; the raw smkv --addr client targets one node and does not discover owners automatically.