zopu-code/.agents/skills/rivetkit/reference/self-hosting/docker-container.md

Docker Container

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

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.
6. Go to Confirm Connection, enter your app endpoint, 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

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

# 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

• Review the Production Checklist before going live
• Use Docker Compose for multi-container setups
• See Configuration for all options

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