zopu-code/.agents/skills/multiplayer-game/reference/self-hosting/docker-compose.md

Docker Compose

Source: src/content/docs/self-hosting/docker-compose.mdx Canonical URL: https://rivet.dev/docs/self-hosting/docker-compose Description: 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

Dashboard

1. Open the Rivet Engine dashboard at http://localhost:6420.
2. Enter your admin token when prompted.
3. In the namespace sidebar, click Settings.
4. Click Add Provider, then choose Custom.
5. Click Next (these settings can be changed later).
6. Click Next (you can safely skip the env ar step for Docker Compose).
7. Go to Confirm Connection, enter your app endpoint (http://my-app:6420/api/rivet), then click Add.

CLI (curl)

Register your runner programmatically via the engine API:

curl -X PUT "http://localhost:6420/runner-configs/default?namespace=default" \
  -H "Content-Type: application/json" \
  -d '{
    "datacenters": {
      "default": {
        "normal": {}
      }
    }
  }'

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 today, but it remains experimental. For a production-ready single-node Rivet deployment, use the file system backend (RocksDB-based). Enterprise teams can contact enterprise support about FoundationDB for the most scalable production-ready deployment.

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

• Review the Production Checklist before going live
• See Configuration for all options

Source doc path: /docs/self-hosting/docker-compose