Platforms

VM & Bare Metal

Run the control plane with systemd on Linux virtual machines or bare metal.

The control plane runs anywhere that meets the requirements below. The example runs it with systemd on Linux virtual machines or bare metal.

Requirements

Every control plane instance needs:

Its own persistent disk. A local or block-storage disk that survives restarts and supports fsync. Never share one disk between instances, and never use a network file system such as NFS or EFS.
A stable private address that the other instances can reach on port 6421.
Access to the bucket.
A pinned image or binary version. Run the same version on every instance.

Run at least three instances in production, each on its own machine.

Steps

Install the binary

Copy rivet-engine from the rivetdev/engine:2.3.31 image to each machine and create the disk directory:

docker create --name rivet-extract rivetdev/engine:2.3.31
docker cp rivet-extract:/usr/bin/rivet-engine /usr/local/bin/rivet-engine
docker rm rivet-extract
sudo useradd --system rivet
sudo mkdir -p /var/lib/rivet/log && sudo chown rivet /var/lib/rivet/log

Mount the instance’s disk at /var/lib/rivet/log.

Write the config file

Save this as /etc/rivet/config.json on each machine. Set advertise_address to that machine’s private IP.

{
	"auth": { "admin_token": "<rivet-token>" },
	"api_peer": { "advertise_address": "10.0.0.11:6421" },
	"depot": { "log_directory": "/var/lib/rivet/log" },
	"object_storage": {
		"primary": {
			"s3": {
				"bucket": "my-rivet-bucket",
				"region": "us-east-1",
				"access_key_id": "AKIA...",
				"secret_access_key": "..."
			}
		}
	}
}

Use the same Rivet token and bucket on every instance. Make the file readable only by the rivet user. See Storage for other object storage backends.

Create the service

Save this as /etc/systemd/system/rivet.service:

[Unit]
Description=Rivet control plane
After=network-online.target
Wants=network-online.target

[Service]
User=rivet
ExecStart=/usr/local/bin/rivet-engine --config /etc/rivet/config.json
Restart=always
LimitNOFILE=1048576
TimeoutStopSec=660

[Install]
WantedBy=multi-user.target

Start every instance

Start all instances within a minute of each other, so the first storage placement uses all of them.

sudo systemctl enable --now rivet
curl http://localhost:6420/health

{"runtime":"engine","status":"ok","version":"2.3.31",...}

Add a load balancer

Point a load balancer at port 6420 on every instance, terminate TLS there and raise its idle timeout to one hour. See Ports & TLS.