# 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.

| Port in this guide | Role | Who needs access |
| --- | --- | --- |
| 7379 | Data TCP | Applications and scan clients |
| 7380 | Replication TCP | Cluster members and backup tools |
| 7381 | Management TCP | SDK discovery, operators, dashboard |
| 7390 | Optional authority TCP | Voters, data nodes, operators |
| 9108 | Optional metrics HTTP | Prometheus and dashboard backend |

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](examples/cluster.json) and [authority peers](examples/peers.json).

```json
{
  "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`:

```sh
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:

```sh
--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](security.html) 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:

```sh
# 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

```sh
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](go-client.html) to route keys; the raw `smkv --addr` client targets one node and does not discover owners automatically.