ContextQMD
Back to Rivet

Docker Compose

website/src/content/docs/self-hosting/docker-compose.mdx

2.2.14.5 KB
Original Source

Quick Start

<Steps> <Step title="Create docker-compose.yaml">

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

yaml
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:
</Step> <Step title="Start the engine">
bash
docker-compose up -d
</Step> </Steps>

Connecting Your Project

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

<Steps> <Step title="Create your server">

Follow the quickstart to create a working server with actors.

</Step> <Step title="Create a Dockerfile">

Create a Dockerfile in your project root:

dockerfile
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"]
</Step> <Step title="Add your app to docker-compose.yaml">

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

yaml
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.

</Step> <Step title="Start the services">
bash
docker-compose up -d
</Step> <Step title="Register your runner with the engine"> <Tabs> <Tab title="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.
</Tab> <Tab title="CLI (curl)">

Register your runner programmatically via the engine API:

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

Configuration

Config File

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

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.

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

Postgres Setup

<Warning> 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](https://rivet.dev/sales) about FoundationDB for the most scalable production-ready deployment. </Warning>
yaml
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