Deploy with systemd

Deploy a three-node cluster on three Linux machines and run it as a systemd service. A TeselaDB cluster is the same binary started on several machines: the first one creates the CA, and each of the others joins with its own single-use enrolment token, gets a certificate signed by that CA and starts receiving replicas of the ranges that already exist.

Requirements

• Three Linux machines with the binary installed. If you do not have it yet, follow Install on Linux.
• Port 27100 open between the three machines, 27017 towards your applications and 27200 towards your operations team.
• Clocks synchronised with NTP.

Step 1. Start the first node

teseladb start --dbpath /var/lib/teseladb \
  --bind_ip 0.0.0.0 --peer-listen 0.0.0.0:27100 --admin-listen 0.0.0.0:27200

On node-01, start the node listening on an address the other two machines can reach. The first start creates the cluster CA and the root user inside /var/lib/teseladb.

Step 2. Create an enrolment token

teseladb admin --dbpath /var/lib/teseladb token create --ttl 1h

On node-01. The token is single-use and expires; --ttl sets how long it lasts. teseladb admin presents itself to the node with the certificate it finds in --dbpath.

Step 3. Join the other nodes

teseladb start --dbpath /var/lib/teseladb \
  --bind_ip 0.0.0.0 --peer-listen 0.0.0.0:27100 --admin-listen 0.0.0.0:27200 \
  --join node-01:27100 --enroll-token <token>

Start node-02 and node-03 this way, with a different token for each node. The new node checks the CA fingerprint the token carries, receives its certificate and the master key over that encrypted channel and joins the cluster. The token is only needed the first time.

Step 4. Run it as a service

[Unit]
Description=TeselaDB
After=network-online.target

[Service]
ExecStart=/usr/local/bin/teseladb start --dbpath /var/lib/teseladb --bind_ip 0.0.0.0 --peer-listen 0.0.0.0:27100 --admin-listen 0.0.0.0:27200
Restart=on-failure

[Install]
WantedBy=multi-user.target

On each machine, create /etc/systemd/system/teseladb.service with the same start command, without --join or --enroll-token, because the node already has its certificate. Then stop the process you started by hand and turn the service on with systemctl enable --now teseladb, which starts it now and on every reboot of the machine.

Check

teseladb admin --dbpath /var/lib/teseladb nodes
teseladb admin --dbpath /var/lib/teseladb ranges --collection shop.orders

nodes lists the three nodes and their state. ranges shows the ranges of a collection with their replicas and their leader; as the collection grows, its ranges split and the balancer spreads replicas and leaders across the three nodes without you moving them.

Common problems

• If the new node does not join and the token is refused, that token was already used or has expired. Create another with token create.
• If the new node cannot reach node-01, port 27100 is closed between the machines or --peer-listen only listens on 127.0.0.1.

See also

• Production checklist, before taking real traffic.
• Nodes, to grow or retire machines later.
• To try it on a single machine, teseladb dev --nodes 3 starts three nodes in one process; node k listens on the client port plus k.