Self-Hosting

Manual Deployment

Manual deployment of Rivet is meant for advanced use cases. For a simpler solution, try our Docker Compose.


Prerequisites


Architecture overview

Core cluster:

  • Contains hardware running the Rivet server as well as databases.

Edge server:

  • Contains hardware running the Rivet client.

Core Cluster Setup

  1. Clone repo
  2. Setup prerequisites

    This guide assumes you have the following already running in your core cluster:

  3. Setup the Rivet server config with your existing components:

    server:
      cockroachdb:
        url: <crdb instance url>
        username: root
      redis:
        ephemeral:
          url: <redis instance url>
          password: <redis password>
        persistent:
          url: <redis instance url>
          password: <redis password>
      clickhouse:
        http_url: <clickhouse instance http url>
        native_url: <clickhouse instance native url>
        username: default
      s3:
        region: <s3 region>
        endpoint_internal: <s3 internal url>
        endpoint_edge_internal: <s3 edge url> # see "Core Cluster <-> Edge Server" below
        endpoint_external: <s3 public url>
        access_key_id: <s3 access key id>
        secret_access_key: <s3 secret access key>
      nats:
        urls:
          - <nats url>
    
      # ...
    
    rivet.yaml
  4. Build and run the Rivet server docker container:

    # Run in the root of the Rivet repo
    docker build -t rivet-server -f docker/universal/Dockerfile --target server-full .
    
    Command Line
    docker run \
      -v "$(pwd)/rivet-server.yaml:/etc/rivet-server/config.yaml:ro" \ # Mount local config
      -v "$(pwd)/rivet-server-data:/data" \ # Persist data to `$(pwd)/rivet-server-data`
      -p 8080:8080 \
      -p 8081:8080 \
      -p 8082:8082 \
      rivet-server \
      /usr/bin/rivet-server start
    
    Command Line

Once running, you can visit the dashboard at http://localhost:8080.


Edge Server Setup

  1. Clone repo
  2. Setup Prerequisites

    This guide assumes you already have FoundationDB running on the edge.

  3. Setup the Rivet client config:

    client:
      runner:
        flavor: isolate
      cluster:
        client_id: <unique uuid for each server>
        datacenter_id: 00000000-0000-0000-0000-000000000000
        api_endpoint: <core cluster url>:8080 # see "Core Cluster <-> Edge Server" below
        pegboard_endpoint: <core cluster url>:8082 # see "Core Cluster <-> Edge Server" below
      network:
        bind_ip: 127.0.0.1
        lan_ip: 127.0.0.1
        wan_ip: <public ip of this server>
    
      # ...
    
    rivet.yaml

    Currently, only the "isolate" flavor is supported for self hosting.

  4. Build and run the Rivet client docker container:

    # Run in the root of the Rivet repo
    docker build -t rivet-client -f docker/universal/Dockerfile --target client-full .
    
    Command Line
    docker run \
      -v "$(pwd)/rivet-client.yaml:/etc/rivet-client/config.yaml:ro" \ # Mount local config
      -v "$(pwd)/rivet-client-data:/var/lib/rivet-client" \ # Persist data to `$(pwd)/rivet-client-data`
      -p 20000-20100:20000-20100 \
      rivet-client \
      -c /etc/rivet-client/config.yaml
    
    Command Line

Test deployment

To test creating an actor end-to-end, run:

./scripts/manual_tests/actors_e2e_js.ts
Command Line

You should see an actor in the actor list in the dashboard.


Core Cluster <-> Edge Server

Communication between the core and edge should be handled via secure mTLS encrypted tunnels. Some common solutions:

  • Cloudflare Tunnels
  • common VLAN
  • Tailscale
  • Wireguard

Rivet Guard

The Rivet Guard system is currently unavailable with a manual deployment. Coming soon!


Caveats

Manual deployment currently only supports host networking and host ports.

Read more about host networking and ports here.