Skip to main content
Sign In
Platforms

Docker Container

Run Rivet Engine in a single Docker container.

Quick Start

Start the engine

docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  rivetdev/engine:latest

Verify the engine is running

curl http://localhost:6420/health

Connecting Your Project

Once the engine is running, connect your app to it.

Create your server

Follow the quickstart to create a working server with actors.

Start your app with RIVET_ENDPOINT

Set RIVET_ENDPOINT to tell your app to connect to the engine as a runner instead of running standalone:

RIVET_ENDPOINT="http://default:admin@host.docker.internal:6420" npm start

If running your app outside of Docker, use localhost instead of host.docker.internal:

RIVET_ENDPOINT="http://default:admin@localhost:6420" npm start

See Endpoints for all options.

Register your runner with the engine

If you set an admin token (RIVET__AUTH__ADMIN_TOKEN), the engine’s API requires authentication. Use that token in RIVET_ENDPOINT (http://default:<token>@host:6420) and add -H "Authorization: Bearer <token>" to the registration request. Without an admin token configured, the API is unauthenticated and the token in these examples is ignored.

Configuration

Environment Variables

Configure Rivet using environment variables:

docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  -e RIVET__POSTGRES__URL="postgresql://postgres:password@localhost:5432/db" \
  rivetdev/engine:latest

Config File

Mount a JSON configuration file:

docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -v $(pwd)/rivet-config.json:/etc/rivet/config.json:ro \
  rivetdev/engine:latest

Create rivet-config.json in your working directory. See the Configuration docs for all available options and the full JSON Schema.

{
  "postgres": {
    "url": "postgresql://postgres:password@localhost:5432/db"
  }
}

Postgres Setup

PostgreSQL is the recommended backend for multi-node self-hosted deployments. It is production-ready for light-to-moderate workloads, up to roughly 1,000 concurrent actors, but is not built for enterprise scale beyond that. For a single-node deployment, use the file system backend (RocksDB-based). Teams running larger or high-throughput realtime workloads should contact enterprise support about FoundationDB.

# Create network
docker network create rivet-net

# Run PostgreSQL
docker run -d \
  --name postgres \
  --network rivet-net \
  -e POSTGRES_DB=rivet \
  -e POSTGRES_USER=rivet \
  -e POSTGRES_PASSWORD=rivet_password \
  -v postgres-data:/var/lib/postgresql/data \
  postgres:15

# Run Rivet Engine
docker run -d \
  --name rivet-engine \
  --network rivet-net \
  -p 6420:6420 \
  -e RIVET__POSTGRES__URL="postgresql://rivet:rivet_password@postgres:5432/rivet" \
  rivetdev/engine

Next Steps

Edit this page