Platforms

Docker Compose

Run a single control plane instance with Docker Compose and connect your app to it.

This runs one control plane instance that keeps its data on local Docker volumes. It is the fastest way to try Rivet. A single instance keeps one copy of your data, so use Kubernetes or VMs with three or more instances and a bucket for production.

Requirements

Docker
About 10 GB of free disk space

Steps

Write the config file

Save this as rivet.json. It keeps recent writes on one volume and the durable copy on another, and creates the instance’s storage on first start.

{
	"depot": {
		"log_directory": "/var/lib/rivet/log",
		"auto_provision_tablets": 1,
		"balancing": { "enabled": false }
	},
	"object_storage": {
		"primary": { "file_system": { "path": "/var/lib/rivet/objects" } }
	}
}

The quickstart keeps objects on a local volume. You can configure S3, GCS, Azure and other object storage on the Storage page.

Generate a Rivet token

export RIVET_TOKEN="$(openssl rand -hex 32)"
echo "$RIVET_TOKEN"

The control plane reads it from its auth.admin_token setting and refuses to start without one. Your app uses the same token to connect, so save it with your other backend secrets.

Start the instance

docker run -d --name rivet \
  -e RIVET__AUTH__ADMIN_TOKEN="$RIVET_TOKEN" \
  -p 6420:6420 \
  -v "$PWD/rivet.json:/etc/rivet/config.json:ro" \
  -v rivet-log:/var/lib/rivet/log \
  -v rivet-objects:/var/lib/rivet/objects \
  rivetdev/engine:2.3.31

curl http://localhost:6420/health

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

Connect your app

Point your app at the instance with RIVET_ENDPOINT and start it. It connects as a node in the default node pool.

export RIVET_ENDPOINT="http://default:$RIVET_TOKEN@localhost:6420"
npm start

Check that your Rivet Actors run

Call one of your Rivet Actors from a client, then list what the control plane is running:

curl -H "Authorization: Bearer $RIVET_TOKEN" \
  "http://localhost:6420/actors?namespace=default&name=counter"

The response lists the Rivet Actors named counter.

Using Docker Compose

The same instance as a Compose service, with your app beside it:

services:
  rivet:
    image: rivetdev/engine:2.3.31
    ports:
      - "6420:6420"
    environment:
      RIVET__AUTH__ADMIN_TOKEN: "${RIVET_TOKEN}"
    volumes:
      - ./rivet.json:/etc/rivet/config.json:ro
      - rivet-log:/var/lib/rivet/log
      - rivet-objects:/var/lib/rivet/objects
    restart: unless-stopped

  my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:${RIVET_TOKEN}@rivet:6420"
    depends_on:
      - rivet
    restart: unless-stopped

volumes:
  rivet-log:
  rivet-objects:

Your app reaches the control plane at rivet:6420 rather than localhost, so create the default node pool before it starts. The control plane refuses a node whose pool does not exist. See Nodes & Node Pools.

docker compose up -d rivet
curl -X PUT "http://localhost:6420/pools/default?namespace=default" -H "Authorization: Bearer $RIVET_TOKEN" -H 'Content-Type: application/json' -d '{}'
docker compose up -d

{"pool":{"name":"default","drain_on_version_upgrade":false,"actor_eviction_delay":0,"actor_eviction_period":0,"actor_eviction_rate":1.0,"metadata":null}}

Never delete the rivet-log volume while the instance has data: it holds writes that have not reached the rivet-objects volume yet.