Skip to main content
Sign In
Platforms

Docker Compose

Deploy Rivet Engine with docker-compose for multi-container setups.

Quick Start

Create docker-compose.yaml

Create a docker-compose.yaml in your project root:

services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
    restart: unless-stopped

volumes:
  rivet-data:

Start the engine

docker-compose up -d

Connecting Your Project

Once the engine is running, add your app as a service in the same Compose file.

Create your server

Follow the quickstart to create a working server with actors.

Create a Dockerfile

Create a Dockerfile in your project root:

FROM node:22-slim
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
CMD ["node", "dist/index.js"]

Add your app to docker-compose.yaml

Update your docker-compose.yaml to include your app alongside the engine:

services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
    restart: unless-stopped

  my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:admin@rivet-engine:6420"
    depends_on:
      - rivet-engine
    restart: unless-stopped

volumes:
  rivet-data:

RIVET_ENDPOINT tells your app to connect to the engine as a runner instead of running standalone. The URL uses the format http://namespace:token@host:port. Inside the Docker network, your app reaches the engine at rivet-engine:6420. See Endpoints for all options.

Start the services

docker-compose up -d

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>@rivet-engine: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

Config File

Mount a JSON configuration file in your docker-compose.yaml:

services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - ./rivet-config.json:/etc/rivet/config.json:ro
      - rivet-data:/data
    restart: unless-stopped

volumes:
  rivet-data:

Create rivet-config.json in the same directory as your docker-compose.yaml. See the Configuration docs for all available options and the full JSON Schema.

{
  "postgres": {
    "url": "postgresql://rivet:password@postgres:5432/rivet"
  }
}

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.

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: rivet
      POSTGRES_USER: rivet
      POSTGRES_PASSWORD: rivet_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    environment:
      RIVET__POSTGRES__URL: postgresql://rivet:rivet_password@postgres:5432/rivet
    depends_on:
      - postgres
    restart: unless-stopped

volumes:
  postgres-data:

Next Steps

Edit this page