From 9a560f2723b22f58b2a963d9da8d4385dcbc7a9b Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Sat, 13 Sep 2025 15:23:06 -0700 Subject: [PATCH] chore(site): doc pino --- site/public/llms-full.txt | 2766 ++----------------- site/public/llms.txt | 33 +- site/src/content/docs/general/logging.mdx | 168 +- site/src/content/docs/integrations/pino.mdx | 11 + site/src/sitemap/mod.ts | 9 +- 5 files changed, 394 insertions(+), 2593 deletions(-) create mode 100644 site/src/content/docs/integrations/pino.mdx diff --git a/site/public/llms-full.txt b/site/public/llms-full.txt index 69c503eb74..497ad55e80 100644 --- a/site/public/llms-full.txt +++ b/site/public/llms-full.txt @@ -5546,1205 +5546,489 @@ async function examples() ); # Vitest See [Testing](/docs/general/testing) documentation. -## Binary +## AWS Fargate Deployment -# Binary Installation +# AWS Fargate Deployment - Binary releases are coming soon. For now, please use the [Docker image](/docs/self-hosting/installing/docker-image) or [build from source](/docs/self-hosting/installing/build-from-source). - -## Coming Soon + Documentation coming soon +## Configuration -We're working on providing pre-built binaries for: +# Configuration -- Linux (x86_64, ARM64) -- macOS (Intel, Apple Silicon) -- Windows (x86_64) +Rivet Engine can be configured through environment variables or configuration files. The configuration system is defined in `packages/common/config/`. -Binary releases will be available through: -- Direct download from GitHub releases -- Package managers (Homebrew, apt, yum) -- Installation scripts +## Configuration Loading -## Alternative Installation Methods +Rivet supports multiple configuration sources: -While we prepare binary releases, you can use: +1. **Default Values**: All configurations have sensible defaults +2. **File-based Configuration**: JSON, JSON5, JSONC, YAML, and YML files +3. **Environment Variables**: Using `RIVET__` prefix with `__` as separator (e.g., `RIVET__database__postgres__url`) +4. **Multi-path Loading**: Can load from multiple configuration files +5. **System Paths**: Platform-specific system configuration directories: + - Linux: `/etc/rivet/` + - macOS: `/Library/Application Support/rivet/` + - Windows: `C:\ProgramData\rivet\` -- [Docker Image](/docs/self-hosting/installing/docker-image) - Recommended for most users -- [Build from Source](/docs/self-hosting/installing/build-from-source) - For advanced users who need custom builds -## Build From Source +## Definition -# Build From Source +```typescript +interface RivetConfig ; + }; + }; -Build Rivet Engine from source for custom configurations or to contribute to development. + // Public API service configuration + api_public?: ; -## Prerequisites + // Private API service configuration + api_peer?: ; -- Rust 1.75+ (install via [rustup](https://rustup.rs/)) -- Git -- C compiler (for native dependencies) + // Runner WebSocket connection management + pegboard?: ; -## Clone the Repository + // WebSocket proxy gateway service + pegboard_gateway?: ; -```bash -git clone https://github.com/rivet-gg/rivet.git -cd rivet -``` + // Tunnel protocol message forwarding + pegboard_tunnel?: ; -## Build the Engine + // Logging configuration + logs?: ; -### Development Build + // Multi-datacenter topology + topology?: ; -```bash -cargo build -p rivet-engine -``` + // Database backend configuration + database?: + | ; + } + | ; + }; -The binary will be available at `target/debug/rivet-engine`. + // Message pub/sub system + pubsub?: + | ; + } + | ; + } + | ; + }; -### Release Build + // Caching layer configuration + cache?: ; -For production use, build with optimizations: + // ClickHouse analytics database (optional) + clickhouse?: ; + }; + }; -```bash -cargo build --release -p rivet-engine + // Vector HTTP endpoint (optional) + vector_http?: ; +} ``` +## Connecting Your Backend to Rivet Engine -The optimized binary will be at `target/release/rivet-engine`. +# Connecting Your Backend to Rivet Engine -## Run the Engine +Unless exlpicitly configured, Rivet will default to running on the local file system without using the Rivet Engine. This is perfect for local development and testing. -After building, run the engine: +When ready to scale the backend, RivetKit can connect to a Rivet Engine instance using the `RIVET_ENGINE` environment variable. -```bash -# Development build -./target/debug/rivet-engine - -# Release build -./target/release/rivet-engine -``` + The engine is not required at any point during development. It is only required to scale RivetKit to multiple nodes. -## Configuration +## Connecting Runners -Configure the engine using environment variables or a configuration file: +To connect a runner to your Rivet Engine, set the `RIVET_ENGINE` environment variable: ```bash -RIVET_PORT=5032 \ -RIVET_STORAGE_TYPE=filesystem \ -RIVET_DATA_DIR=/path/to/data \ -./target/release/rivet-engine +RIVET_ENGINE=http://your-engine-host:6420 npm run dev ``` -## Building with Features - -Enable specific features during build: - -```bash -# Build with FoundationDB support (enterprise) -cargo build --release -p rivet-engine --features foundationdb - -# Build with all features -cargo build --release -p rivet-engine --all-features -``` +Once connected: +- The runner appears in the Runners tab of the dashboard +- Your actor names show up in the sidebar +- The engine begins routing traffic to your runner -## Docker Build +## Environment Variables -Build your own Docker image: +### `RIVET_ENGINE` +The endpoint of your Rivet Engine instance. ```bash -docker build -t my-rivet-engine . -``` - -## Next Steps - -- [Configure the engine](/docs/self-hosting/reference/configuration) -- [Connect runners](/docs/self-hosting/reference/connecting) -- Set up your [database backend](/docs/self-hosting/reference/databases) -## Docker Image - -# Docker Image - -The official Rivet Engine Docker image is available on Docker Hub at `rivetkit/engine`. +# Local development +RIVET_ENGINE=http://localhost:6420 -## Quick Start +# Production +RIVET_ENGINE=https://engine.your-domain.com +``` -Run the Rivet Engine with the following command: +### `RIVET_NAMESPACE` +The namespace to run actors in. Useful for multi-tenant deployments. ```bash -docker run -p 5032:5032 -v rivet-data:/data rivetkit/engine +RIVET_NAMESPACE=production ``` -This will: -- Expose the engine on port 5032 -- Mount a volume for persistent data storage -- Use the default file system storage backend - -## Configuration - -### Environment Variables - -You can configure the engine using environment variables: +### `RIVET_RUNNER` +A name for the runner to allow filtering which nodes to run actors on. ```bash -docker run -p 5032:5032 \ - -v rivet-data:/data \ - -e RIVET_STORAGE_TYPE=postgres \ - -e RIVET_POSTGRES_URL="postgresql://user:pass@host:5432/db" \ - rivetkit/engine +RIVET_RUNNER=worker-01 ``` -### Volume Mounts - -For file system storage, mount a volume to persist data: +### `RIVET_RUNNER_KEY` +A unique key for the runner. If another runner connects with the same key, the previous one is disconnected. This is useful for handling zombie runners that weren't shut down gracefully. ```bash -docker run -p 5032:5032 \ - -v /path/to/local/data:/data \ - rivetkit/engine +RIVET_RUNNER_KEY=unique-runner-key-123 ``` -## Available Tags - -- `latest` - Latest stable release -- `vX.Y.Z` - Specific version tags -- `edge` - Development builds (not recommended for production) - -## Next Steps - -- [Connect your runners](/docs/self-hosting/reference/connecting) to the engine -- Configure your [database backend](/docs/self-hosting/reference/databases) -- Learn about [networking options](/docs/self-hosting/reference/networking) -## AWS - -# AWS Deployment - - Coming Soon - - AWS deployment documentation is currently being prepared. This will include: - - • ECS (Elastic Container Service) deployment - • EKS (Elastic Kubernetes Service) setup - • EC2 instance configuration - • RDS PostgreSQL integration - • Application Load Balancer setup - • Auto Scaling Groups - • CloudFormation templates - • CDK (Cloud Development Kit) examples - • Cost optimization strategies + Generate a unique runner key using: `uuidgen` or `openssl rand -hex 16` -## Deployment Options +## Connection Examples -We'll cover multiple AWS deployment strategies: +### Testing Setup -### ECS Fargate -- Serverless container hosting -- Automatic scaling -- No infrastructure management +You do not need the engine for local development, but it can be helpful for testing your production-readiness: -### ECS on EC2 -- More control over instances -- Cost-effective for steady workloads -- Custom AMI support +```bash +# Start the engine +docker run -p 6420:6420 rivetkit/engine -### EKS -- Managed Kubernetes -- Integration with existing K8s workflows -- Advanced orchestration features +# In another terminal, start your runner +RIVET_ENGINE=http://localhost:6420 npm run dev +``` -### EC2 -- Full control over deployment -- Custom configurations -- Traditional VM approach +### Production Setup -## In the Meantime +```bash +# Assume the engine is running at 1.2.3.4 -- Deploy using [Docker](/docs/self-hosting/platforms/docker-container) on EC2 instances -- Use [Docker Compose](/docs/self-hosting/platforms/docker-compose) for quick setups -- Check [Railway](/docs/self-hosting/platforms/railway) for managed deployments +# On runner nodes +RIVET_ENGINE=http://1.2.3.4 \ +RIVET_NAMESPACE=production \ +RIVET_RUNNER=worker-$(hostname) \ +RIVET_RUNNER_KEY=$(cat /etc/machine-id) \ +npm run start +``` ## Docker Compose -# Docker Compose Deployment - -Docker Compose simplifies multi-container Rivet deployments with declarative configuration. +# Docker Compose ## Quick Start -Create a `docker-compose.yml` file: +Run with ephemeral storage: ```yaml -version: '3.8' +services: + rivet-engine: + image: rivetkit/engine:latest + ports: + - "6420:6420" + restart: unless-stopped +``` +Run with persistent storage: + +```yaml services: rivet-engine: image: rivetkit/engine:latest ports: - - "5032:5032" + - "6420:6420" volumes: - rivet-data:/data environment: - - RIVET_STORAGE_TYPE=filesystem + RIVET__FILE_SYSTEM__PATH: "/data" restart: unless-stopped volumes: rivet-data: ``` -Start the deployment: +Start the services: ```bash docker-compose up -d ``` -## Full Stack Example +## Configuration + +### Environment Variables -Complete deployment with PostgreSQL and NATS: +Configure Rivet using environment variables in your compose file: ```yaml -version: '3.8' - services: - postgres: - image: postgres:15 - environment: - POSTGRES_DB: rivet - POSTGRES_USER: rivet - POSTGRES_PASSWORD: rivet_password - volumes: - - postgres-data:/var/lib/postgresql/data - healthcheck: - test: ["CMD-SHELL", "pg_isready -U rivet"] - interval: 10s - timeout: 5s - retries: 5 - - nats: - image: nats:latest - command: "-js -sd /data" - volumes: - - nats-data:/data - healthcheck: - test: ["CMD", "nats", "account", "info"] - interval: 10s - timeout: 5s - retries: 5 - rivet-engine: image: rivetkit/engine:latest ports: - - "5032:5032" # API - - "5033:5033" # Proxy - - "9090:9090" # Metrics + - "6420:6420" + volumes: + - rivet-data:/data environment: - RIVET_STORAGE_TYPE: postgres - RIVET_POSTGRES_URL: postgresql://rivet:rivet_password@postgres:5432/rivet - RIVET_PUBSUB_TYPE: nats - RIVET_NATS_URL: nats://nats:4222 - RIVET_LOG_LEVEL: info - depends_on: - postgres: - condition: service_healthy - nats: - condition: service_healthy + RIVET__POSTGRES__URL: "postgresql://postgres:password@localhost:5432/db" restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/health"] - interval: 30s - timeout: 10s - retries: 3 volumes: - postgres-data: - nats-data: rivet-data: ``` -## Environment Configuration - -### Using .env File - -Create a `.env` file: - -```env -# Database -POSTGRES_PASSWORD=secure_password_here -RIVET_POSTGRES_URL=postgresql://rivet:secure_password_here@postgres:5432/rivet - -# PubSub -RIVET_NATS_URL=nats://nats:4222 +Or use a `.env` file: -# Engine Config -RIVET_LOG_LEVEL=info -RIVET_AUTH_TOKEN=your_secret_token +```txt +# .env +POSTGRES_PASSWORD=secure_password +RIVET__POSTGRES__URL=postgresql://rivet:secure_password@postgres:5432/rivet ``` -Reference in `docker-compose.yml`: +Reference in compose: ```yaml services: rivet-engine: - image: rivetkit/engine:latest env_file: - .env - environment: - RIVET_STORAGE_TYPE: postgres -``` - -### Multiple Environment Files - -```yaml -services: - rivet-engine: - env_file: - - common.env - - secrets.env - - $.env # dev.env, prod.env, etc. ``` -## Networking +### Config File -### Custom Network +Mount a JSON configuration file: ```yaml -version: '3.8' - -networks: - rivet-net: - driver: bridge - ipam: - config: - - subnet: 172.20.0.0/16 - services: rivet-engine: - networks: - rivet-net: - ipv4_address: 172.20.0.10 + image: rivetkit/engine:latest + ports: + - "6420:6420" + volumes: + - ./rivet-config.json:/etc/rivet/config.json:ro + - rivet-data:/data + restart: unless-stopped + +volumes: + rivet-data: ``` -### External Network +Create the config file (`rivet-config.json`): -```yaml -networks: - external-net: - external: true +```json -services: - rivet-engine: - networks: - - external-net - - default +} ``` -## Scaling +## Production Setup -### Multiple Runners +#### With PostgreSQL ```yaml services: - rivet-runner: - image: your-app:latest + postgres: + image: postgres:15 environment: - RIVET_ENGINE: http://rivet-engine:5032 - RIVET_RUNNER_KEY: $ - deploy: - replicas: 3 - depends_on: - - rivet-engine -``` - -Scale dynamically: - -```bash -docker-compose up -d --scale rivet-runner=5 -``` - -## Resource Limits + POSTGRES_DB: rivet + POSTGRES_USER: rivet + POSTGRES_PASSWORD: rivet_password + volumes: + - postgres-data:/var/lib/postgresql/data + restart: unless-stopped -```yaml -services: rivet-engine: image: rivetkit/engine:latest - deploy: - resources: - limits: - cpus: '2' - memory: 4G - reservations: - cpus: '1' - memory: 2G -``` - -## Health Monitoring - -### Health Checks - -```yaml -services: - rivet-engine: - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s -``` - -### Monitoring Stack - -Add Prometheus and Grafana: - -```yaml -services: - prometheus: - image: prom/prometheus - volumes: - - ./prometheus.yml:/etc/prometheus/prometheus.yml - - prometheus-data:/prometheus - command: - - '--config.file=/etc/prometheus/prometheus.yml' - - '--storage.tsdb.path=/prometheus' ports: - - "9091:9090" - - grafana: - image: grafana/grafana + - "6420:6420" environment: - GF_SECURITY_ADMIN_PASSWORD: admin - volumes: - - grafana-data:/var/lib/grafana - ports: - - "3000:3000" + RIVET__POSTGRES__URL: postgresql://rivet:rivet_password@postgres:5432/rivet depends_on: - - prometheus + - postgres + restart: unless-stopped volumes: - prometheus-data: - grafana-data: + postgres-data: ``` -Prometheus configuration (`prometheus.yml`): +## Next Steps -```yaml -global: - scrape_interval: 15s +- See [Configuration](/docs/self-hosting/configuration) for all options +## Docker Container -scrape_configs: - - job_name: 'rivet-engine' - static_configs: - - targets: ['rivet-engine:9090'] -``` +# Docker Container -## Backup and Restore +## Quick Start -### Backup Script +Run with ephemeral storage: -```yaml -services: - backup: - image: alpine:latest - volumes: - - postgres-data:/postgres-data:ro - - ./backups:/backups - command: > - sh -c "tar czf /backups/backup-$$(date +%Y%m%d-%H%M%S).tar.gz - -C / postgres-data" - profiles: - - tools +```bash +docker run -p 6420:6420 rivetkit/engine ``` -Run backup: +Run with persistent storage: ```bash -docker-compose run --rm backup +docker run \ + -p 6420:6420 \ + -v rivet-data:/data \ + -e RIVET__FILE_SYSTEM__PATH="/data" \ + rivetkit/engine ``` -### Restore Script +## Configuration -```yaml -services: - restore: - image: alpine:latest - volumes: - - postgres-data:/postgres-data - - ./backups:/backups - command: > - sh -c "tar xzf /backups/$$BACKUP_FILE -C /" - profiles: - - tools -``` +### Environment Variables -Run restore: +Configure Rivet using environment variables: ```bash -BACKUP_FILE=backup-20240101-120000.tar.gz \ -docker-compose run --rm restore +docker run -p 6420:6420 \ + -v rivet-data:/data \ + -e RIVET__POSTGRES__URL="postgresql://postgres:password@localhost:5432/db" \ + rivetkit/engine ``` -## Production Configuration +### Config File -### docker-compose.prod.yml +Mount a JSON configuration file: -```yaml -version: '3.8' +```bash +# Create config file +cat rivet-config.json -services: - rivet-engine: - image: rivetkit/engine:$ - logging: - driver: json-file - options: - max-size: "10m" - max-file: "3" - deploy: - restart_policy: - condition: any - delay: 5s - max_attempts: 3 - window: 120s - secrets: - - db_password - - auth_token - environment: - RIVET_POSTGRES_PASSWORD_FILE: /run/secrets/db_password - RIVET_AUTH_TOKEN_FILE: /run/secrets/auth_token +} +EOF -secrets: - db_password: - file: ./secrets/db_password.txt - auth_token: - file: ./secrets/auth_token.txt +# Run with mounted config +docker run -p 6420:6420 \ + -v rivet-data:/data \ + -v $(pwd)/rivet-config.json:/etc/rivet/config.json:ro \ + rivetkit/engine ``` -Deploy production: +## Production Setup + +### With PostgreSQL ```bash -docker-compose -f docker-compose.yml \ - -f docker-compose.prod.yml \ - up -d +# 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" \ + rivetkit/engine ``` -## SSL/TLS with Traefik +## Next Steps -```yaml -services: - traefik: - image: traefik:v2.10 - command: - - "--providers.docker=true" - - "--providers.docker.exposedbydefault=false" - - "--entrypoints.websecure.address=:443" - - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true" - - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com" - - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json" - ports: - - "443:443" - volumes: - - /var/run/docker.sock:/var/run/docker.sock:ro - - letsencrypt:/letsencrypt +- Use [Docker Compose](/docs/self-hosting/docker-compose) for multi-container setups +- See [Configuration](/docs/self-hosting/configuration) for all options +## Google Cloud Run Deployment - rivet-engine: - labels: - - "traefik.enable=true" - - "traefik.http.routers.rivet.rule=Host(`engine.example.com`)" - - "traefik.http.routers.rivet.entrypoints=websecure" - - "traefik.http.routers.rivet.tls.certresolver=letsencrypt" - - "traefik.http.services.rivet.loadbalancer.server.port=5032" +# Google Cloud Run Deployment -volumes: - letsencrypt: -``` + Documentation coming soon +## Hetzner Deployment -## Common Commands +# Hetzner Deployment -```bash -# Start services -docker-compose up -d + Documentation coming soon +## Self-Hosting Overview -# Stop services -docker-compose down +# Self-Hosting Overview -# View logs -docker-compose logs -f rivet-engine +Rivet consists of several core components that work together to provide a complete actor orchestration platform. The Rivet Engine is the core of self-hosting and is used for orchestrating actors at scale: -# Restart service -docker-compose restart rivet-engine +## Core Components -# Execute command in container -docker-compose exec rivet-engine sh +- **Your Backend** - Your application server that handles user requests and includes a runner component that executes actor code +- **Rivet Engine** - Main orchestration service that manages actor lifecycle, routes messages, and provides APIs +- **Storage** - Persistence layer for actor state and messaging infrastructure for real-time communication -# Update images -docker-compose pull -docker-compose up -d +## Architecture -# Clean up -docker-compose down -v # Also removes volumes +```txt } +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│Your Backend │◀───▶│Rivet Engine │◀───▶│ Storage │ +│ (w/ runner) │ │ │ │ (DB/File) │ +└─────────────┘ └─────────────┘ └─────────────┘ ``` -## Override Files - -Development override (`docker-compose.override.yml`): - -```yaml -version: '3.8' +## Storage Backends -services: - rivet-engine: - environment: - RIVET_LOG_LEVEL: debug - ports: - - "5032:5032" - - "9090:9090" - volumes: - - ./config:/config -``` +Rivet supports multiple storage backends: +- **File System** - Default, suitable for single-node deployments +- **PostgreSQL** - Recommended for production +- **FoundationDB** - Enterprise option for massive scale - Docker Compose automatically loads `docker-compose.override.yml` if it exists, perfect for local development settings. +## Deployment Platforms -## Troubleshooting +Deploy Rivet on your preferred platform: -### Service Dependencies +- [Docker Container](./docker-container) +- [Docker Compose](./docker-compose) +- [Kubernetes](./kubernetes) +- [AWS Fargate](./aws-fargate) +- [Google Cloud Run](./google-cloud-run) +- [Hetzner](./hetzner) +- [Railway](./railway) -Ensure proper startup order: +## Next Steps -```yaml -services: - rivet-engine: - depends_on: - postgres: - condition: service_healthy - nats: - condition: service_started -``` +- [Install Rivet Engine](./install) +- [Connect your backend](./connect-backend) +- [Configure your deployment](./configuration) +- [Multi-region setup](./multi-region) +## Installing Rivet Engine -### Network Issues +# Installing Rivet Engine -Debug networking: +## Docker ```bash -# List networks -docker network ls +docker run -p 6420:6420 rivetkit/engine +``` -# Inspect network -docker network inspect rivet_default +For more options: +- [Docker Container](/docs/self-hosting/docker-container) - Persistent storage, configuration, production setup +- [Docker Compose](/docs/self-hosting/docker-compose) - Multi-container deployments with PostgreSQL -# Test connectivity -docker-compose exec rivet-engine ping postgres -``` +## Prebuilt Binaries -### Volume Permissions + Prebuilt binaries coming soon -Fix permission issues: +## Build From Source ```bash -# Run as specific user -services: - rivet-engine: - user: "1000:1000" - -# Or fix in entrypoint - entrypoint: > - sh -c "chown -R 1000:1000 /data && exec rivet-engine" -``` - -## Next Steps - -- Deploy to [Railway](/docs/self-hosting/platforms/railway) for managed hosting -- Scale with [Kubernetes](/docs/self-hosting/platforms/kubernetes) -- Set up [monitoring](/docs/self-hosting/reference/monitoring) -## Docker Container - -# Docker Container Deployment - -Deploy Rivet Engine as a Docker container for simple, portable deployments. - -## Quick Start - -```bash -docker run -d \ - --name rivet-engine \ - -p 5032:5032 \ - -v rivet-data:/data \ - rivetkit/engine -``` - -This command: -- Runs the container in detached mode (`-d`) -- Names the container `rivet-engine` -- Exposes port 5032 for API access -- Creates a named volume `rivet-data` for persistence - -## Full Configuration - -```bash -docker run -d \ - --name rivet-engine \ - --restart unless-stopped \ - -p 5032:5032 \ - -p 5033:5033 \ - -p 9090:9090 \ - -v rivet-data:/data \ - -v /path/to/config:/config \ - -e RIVET_STORAGE_TYPE=postgres \ - -e RIVET_POSTGRES_URL="postgresql://user:pass@db:5432/rivet" \ - -e RIVET_PUBSUB_TYPE=nats \ - -e RIVET_NATS_URL="nats://nats:4222" \ - -e RIVET_LOG_LEVEL=info \ - rivetkit/engine -``` - -## Docker Run Options - -### Container Management - -```bash -# Auto-restart on failure ---restart unless-stopped - -# Resource limits ---memory="2g" ---cpus="2" - -# Health check ---health-cmd="curl -f http://localhost:8080/health || exit 1" ---health-interval=30s ---health-timeout=10s ---health-retries=3 -``` - -### Networking - -```bash -# Use host networking (Linux only) ---network host - -# Custom network ---network rivet-net - -# Expose additional ports --p 5033:5033 # Proxy port --p 9090:9090 # Metrics port --p 8080:8080 # Health port -``` - -### Volumes - -```bash -# Named volume (recommended) --v rivet-data:/data - -# Bind mount --v /host/path/data:/data - -# Configuration file --v /host/path/config.yaml:/config/rivet.yaml -``` - -## Environment Variables - -Common environment variables for configuration: - -```bash -# Storage --e RIVET_STORAGE_TYPE=postgres --e RIVET_POSTGRES_URL="postgresql://..." - -# PubSub --e RIVET_PUBSUB_TYPE=nats --e RIVET_NATS_URL="nats://..." - -# Performance --e RIVET_WORKERS=4 --e RIVET_MAX_CONNECTIONS=10000 - -# Security --e RIVET_AUTH_TOKEN="secret-token" --e RIVET_TLS_ENABLED=true - -# Logging --e RIVET_LOG_LEVEL=info --e RIVET_LOG_FORMAT=json -``` - -## Data Persistence - -### Using Named Volumes - -```bash -# Create volume -docker volume create rivet-data - -# Run with volume -docker run -v rivet-data:/data rivetkit/engine - -# Backup volume -docker run --rm \ - -v rivet-data:/source \ - -v $(pwd):/backup \ - alpine tar czf /backup/rivet-backup.tar.gz -C /source . - -# Restore volume -docker run --rm \ - -v rivet-data:/target \ - -v $(pwd):/backup \ - alpine tar xzf /backup/rivet-backup.tar.gz -C /target -``` - -### Using Bind Mounts - -```bash -# Create data directory -mkdir -p /opt/rivet/data - -# Set permissions -chown 1000:1000 /opt/rivet/data - -# Run with bind mount -docker run -v /opt/rivet/data:/data rivetkit/engine -``` - -## Container Management - -### Starting and Stopping - -```bash -# Start container -docker start rivet-engine - -# Stop gracefully -docker stop rivet-engine - -# Restart -docker restart rivet-engine - -# Remove container -docker rm rivet-engine -``` - -### Monitoring - -```bash -# View logs -docker logs rivet-engine -docker logs -f rivet-engine # Follow logs - -# Check status -docker ps -docker inspect rivet-engine - -# Resource usage -docker stats rivet-engine - -# Enter container -docker exec -it rivet-engine sh -``` - -### Updates - -```bash -# Pull latest image -docker pull rivetkit/engine:latest - -# Stop old container -docker stop rivet-engine -docker rm rivet-engine - -# Start with new image -docker run -d \ - --name rivet-engine \ - -v rivet-data:/data \ - rivetkit/engine:latest -``` - -## Production Deployment - -### Security Hardening - -```bash -docker run -d \ - --name rivet-engine \ - --restart unless-stopped \ - --read-only \ - --tmpfs /tmp \ - --security-opt no-new-privileges:true \ - --cap-drop ALL \ - --cap-add NET_BIND_SERVICE \ - -v rivet-data:/data \ - rivetkit/engine -``` - -### Resource Limits - -```bash -docker run -d \ - --name rivet-engine \ - --memory="4g" \ - --memory-swap="4g" \ - --cpus="4" \ - --pids-limit 1000 \ - -v rivet-data:/data \ - rivetkit/engine -``` - -### Logging - -```bash -docker run -d \ - --name rivet-engine \ - --log-driver json-file \ - --log-opt max-size=10m \ - --log-opt max-file=3 \ - -v rivet-data:/data \ - rivetkit/engine -``` - -## Networking Examples - -### Bridge Network - -```bash -# Create network -docker network create rivet-net - -# Run containers on network -docker run -d --network rivet-net --name postgres postgres:15 -docker run -d --network rivet-net --name nats nats:latest -docker run -d --network rivet-net \ - -e RIVET_POSTGRES_URL="postgresql://user:pass@postgres:5432/rivet" \ - -e RIVET_NATS_URL="nats://nats:4222" \ - rivetkit/engine -``` - -### Host Network (Linux) - -```bash -docker run -d \ - --network host \ - -v rivet-data:/data \ - rivetkit/engine -``` - -## Health Checks - -### Built-in Health Check - -The container includes a health check endpoint: - -```bash -# Check health from host -curl http://localhost:8080/health - -# Check from another container -docker run --rm curlimages/curl \ - curl http://rivet-engine:8080/health -``` - -### Custom Health Check - -```dockerfile -# In your Dockerfile -HEALTHCHECK --interval=30s --timeout=10s --retries=3 \ - CMD curl -f http://localhost:8080/health || exit 1 -``` - -## Troubleshooting - -### Container Won't Start - -```bash -# Check logs -docker logs rivet-engine - -# Check events -docker events --filter container=rivet-engine - -# Debug mode -docker run -it --rm \ - -e RIVET_LOG_LEVEL=debug \ - rivetkit/engine -``` - -### Permission Issues - -```bash -# Fix volume permissions -docker run --rm \ - -v rivet-data:/data \ - alpine chown -R 1000:1000 /data -``` - -### Network Issues - -```bash -# Test network connectivity -docker run --rm --network rivet-net \ - nicolaka/netshoot \ - ping postgres - -# Check port binding -netstat -tlpn | grep 5032 +git clone https://github.com/rivet-gg/rivet.git +cd rivet +cargo build --release -p rivet-engine +./target/release/rivet-engine ``` - - Use Docker Compose for more complex deployments with multiple services. See the [Docker Compose guide](/docs/self-hosting/platforms/docker-compose). - -## Next Steps - -- Set up [Docker Compose](/docs/self-hosting/platforms/docker-compose) for multi-container deployments -- Deploy to [Kubernetes](/docs/self-hosting/platforms/kubernetes) for orchestration -- Configure [monitoring and metrics](/docs/self-hosting/reference/monitoring) -## Google Cloud - -# Google Cloud Deployment - - Coming Soon - - Google Cloud deployment documentation is currently being prepared. This will include: - - • Cloud Run deployment (serverless) - • GKE (Google Kubernetes Engine) setup - • Compute Engine VM configuration - • Cloud SQL PostgreSQL integration - • Load Balancer configuration - • Cloud Build CI/CD pipelines - • Terraform configurations - • Identity and Access Management (IAM) - • Cost optimization with committed use discounts - -## Deployment Options - -We'll cover multiple GCP deployment strategies: - -### Cloud Run -- Fully managed serverless platform -- Automatic scaling to zero -- Pay-per-use pricing - -### GKE Autopilot -- Managed Kubernetes without node management -- Automatic scaling and updates -- Built-in security best practices - -### GKE Standard -- Full Kubernetes control -- Custom node pools -- Advanced networking options - -### Compute Engine -- Traditional VM deployment -- Full infrastructure control -- Custom machine types - -## In the Meantime - -- Deploy using [Docker](/docs/self-hosting/platforms/docker-container) on Compute Engine -- Use [Docker Compose](/docs/self-hosting/platforms/docker-compose) for quick deployments -- Try [Railway](/docs/self-hosting/platforms/railway) for simplified hosting -## Hetzner - -# Hetzner Cloud Deployment - - Coming Soon - - Hetzner deployment documentation is currently being prepared. This will include: - - • Cloud server provisioning - • Load balancer configuration - • Floating IPs for high availability - • Volume storage setup - • Private networks configuration - • Firewall rules - • Snapshot backups - • Terraform deployment scripts - • Cost-effective scaling strategies - -## Why Hetzner? - -Hetzner Cloud offers: -- **Excellent price-performance ratio** -- **German data centers** with strong privacy laws -- **Simple, predictable pricing** -- **Fast NVMe SSD storage** -- **100% renewable energy** - -## Deployment Preview - -We'll provide: -- One-click deployment scripts -- Ansible playbooks for automation -- Docker Swarm cluster setup -- Kubernetes (k3s) lightweight deployment -- Monitoring with Hetzner Cloud metrics - -## In the Meantime - -- Deploy using [Docker](/docs/self-hosting/platforms/docker-container) on Hetzner Cloud servers -- Use [Docker Compose](/docs/self-hosting/platforms/docker-compose) for multi-container setups -- Check our [installation guide](/docs/self-hosting/installing/docker-image) for Docker deployment -## Kubernetes +## Kubernetes Deployment # Kubernetes Deployment - Coming Soon - - Kubernetes deployment documentation is currently being prepared. This will include: - - • Helm charts for easy deployment - • Kubernetes manifests (Deployment, Service, ConfigMap) - • Horizontal Pod Autoscaling configuration - • Persistent volume setup - • Ingress configuration - • Multi-node clustering - • Security best practices + Documentation coming soon +## Multi-Region -## Quick Preview +# Multi-Region -While we prepare comprehensive documentation, here's a basic example: +Rivet Engine supports scaling transparently across multiple regions. -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: rivet-engine -spec: - replicas: 3 - selector: - matchLabels: - app: rivet-engine - template: - metadata: - labels: - app: rivet-engine - spec: - containers: - - name: engine - image: rivetkit/engine:latest - ports: - - containerPort: 5032 - env: - - name: RIVET_STORAGE_TYPE - value: postgres - - name: RIVET_POSTGRES_URL - valueFrom: - secretKeyRef: - name: rivet-secrets - key: postgres-url ---- -apiVersion: v1 -kind: Service -metadata: - name: rivet-engine -spec: - selector: - app: rivet-engine - ports: - - port: 5032 - targetPort: 5032 - type: LoadBalancer -``` - -## In the Meantime - -- Use [Docker](/docs/self-hosting/platforms/docker-container) for container deployments -- Try [Docker Compose](/docs/self-hosting/platforms/docker-compose) for multi-container setups -- Deploy to [Railway](/docs/self-hosting/platforms/railway) for managed Kubernetes -## Railway + Documentation coming soon +## Railway Deployment # Railway Deployment @@ -6752,9 +6036,9 @@ Railway provides a simple platform for deploying Rivet Engine with automatic sca ## Quick Deploy - Railway template coming soon. For now, follow the manual deployment steps below. +[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/rivet?referralCode=RC7bza&utm_medium=integration&utm_source=template&utm_campaign=generic) -[![Deploy on Railway](https://railway.app/button.svg)](TODO) +You can also use the [Rivet Railway template](https://github.com/rivet-gg/template-railway) as a starting point for your application. ## Manual Deployment @@ -6775,1479 +6059,25 @@ railway init ### Step 2: Add Services -#### PostgreSQL Database +#### Deploy PostgreSQL Database 1. Click "New Service" → "Database" → "PostgreSQL" 2. Railway automatically provisions and configures PostgreSQL 3. Note the connection string from the service variables -#### Rivet Engine +#### Deploy Rivet Engine 1. Click "New Service" → "Docker Image" 2. Set image: `rivetkit/engine:latest` -3. Configure environment variables - -### Step 3: Environment Variables - -In the Rivet Engine service settings: - -```bash -# Database (use Railway's PostgreSQL reference) -RIVET_STORAGE_TYPE=postgres -RIVET_POSTGRES_URL=$} - -# Engine Configuration -RIVET_PORT=5032 -RIVET_LOG_LEVEL=info - -# Optional: Authentication -RIVET_AUTH_TOKEN=your-secret-token-here -``` - -### Step 4: Configure Networking - -1. Go to Settings → Networking -2. Generate a domain or use custom domain -3. Set port to `5032` - -## Railway Configuration File - -Create `railway.toml` in your project: - -```toml -[deploy] -dockerfilePath = "Dockerfile" - -[build] -builder = "dockerfile" - -[[services]] -name = "rivet-engine" -image = "rivetkit/engine:latest" - -[[services.ports]] -port = 5032 -targetPort = 5032 - -[[services.envs]] -RIVET_STORAGE_TYPE = "postgres" -RIVET_POSTGRES_URL = "$}" -RIVET_LOG_LEVEL = "info" -``` - -## Custom Dockerfile - -For custom configurations, create a `Dockerfile`: - -```dockerfile -FROM rivetkit/engine:latest - -# Add custom configuration -COPY config.yaml /config/rivet.yaml - -# Set environment -ENV RIVET_CONFIG_FILE=/config/rivet.yaml - -EXPOSE 5032 5033 9090 - -CMD ["rivet-engine"] -``` - -Deploy with: +3. Configure environment variables: + - `RIVET__POSTGRES__URL=$}` -```bash -railway up -``` - -## Database Setup - -### Using Railway PostgreSQL - -Railway automatically provides: -- Managed PostgreSQL instance -- Automatic backups -- Connection pooling -- SSL connections - -Access database URL: - -```bash -railway variables -# Copy DATABASE_URL value -``` - -### External Database - -Use any PostgreSQL-compatible database: - -```bash -RIVET_POSTGRES_URL=postgresql://user:pass@external-db.com:5432/rivet -``` - -## Scaling - -### Horizontal Scaling +### Step 3: Deploy Your Application -Railway supports multiple instances: - -```bash -# Via CLI -railway scale --count 3 - -# Or in dashboard -# Service → Settings → Scaling → Instance Count -``` - -### Resource Limits - -Configure in service settings: - -- **Memory**: 512MB - 8GB -- **CPU**: 0.5 - 8 vCPUs -- **Disk**: 1GB - 100GB - -Recommended production settings: -- Memory: 2GB minimum -- CPU: 1 vCPU minimum -- Disk: 10GB for file storage - -## Monitoring - -### Railway Metrics - -Built-in metrics available in dashboard: -- CPU usage -- Memory usage -- Network I/O -- Request count -- Response times - -### Custom Metrics - -Enable Prometheus endpoint: - -```bash -RIVET_METRICS_ENABLED=true -RIVET_METRICS_PORT=9090 -``` - -Access metrics at: `https://your-app.railway.app:9090/metrics` - -### Logging - -View logs in Railway dashboard or CLI: - -```bash -# Stream logs -railway logs - -# Filter logs -railway logs --filter "error" - -# Export logs -railway logs > logs.txt -``` - -## Custom Domains - -### Add Custom Domain - -1. Go to Settings → Networking → Custom Domain -2. Add your domain: `engine.yourdomain.com` -3. Configure DNS: - -``` -CNAME engine.yourdomain.com -> your-app.railway.app -``` - -### SSL Certificates - -Railway automatically provides: -- Free SSL certificates via Let's Encrypt -- Automatic renewal -- HTTP → HTTPS redirect - -## Environment Management - -### Development Environment - -```bash -# Create dev environment -railway environment create dev - -# Switch to dev -railway environment dev - -# Deploy to dev -railway up -``` - -### Production Environment - -```bash -# Switch to production -railway environment production - -# Set production variables -railway variables set RIVET_LOG_LEVEL=warn -railway variables set RIVET_AUTH_ENABLED=true -``` - -## Connecting Runners - -Connect external runners to Railway-hosted engine: - -```bash -# Get public URL -railway domain - -# Configure runner -RIVET_ENGINE=https://your-app.railway.app npm run start -``` - -## CI/CD Integration - -### GitHub Integration - -1. Connect GitHub repo in Railway dashboard -2. Configure automatic deployments -3. Set branch triggers - -### GitHub Actions - -```yaml -name: Deploy to Railway - -on: - push: - branches: [main] - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Deploy to Railway - uses: bervProject/railway-deploy@main - with: - railway_token: $} - service: rivet-engine -``` - -### GitLab CI - -```yaml -deploy: - stage: deploy - script: - - npm install -g @railway/cli - - railway up - environment: - name: production - only: - - main -``` - -## Backup and Recovery - -### Automatic Backups - -Railway PostgreSQL includes: -- Daily automatic backups -- 7-day retention -- Point-in-time recovery - -### Manual Backup - -```bash -# Export database -railway run pg_dump $DATABASE_URL > backup.sql - -# Import database -railway run psql $DATABASE_URL - Join Railway's Discord community for help and best practices: [discord.gg/railway](https://discord.gg/railway) - -## Next Steps - -- Configure [monitoring](/docs/self-hosting/reference/monitoring) -- Set up [high availability](/docs/self-hosting/reference/high-availability) -- Explore [Kubernetes deployment](/docs/self-hosting/platforms/kubernetes) for more control -## Architecture - -# Architecture - - Coming Soon - - Detailed architecture documentation is currently being prepared. This will include: - - • System design and components - • Data flow and communication patterns - • Scaling strategies - • Performance considerations - • Security architecture - -## In the Meantime - -While we prepare comprehensive architecture documentation, you can: - -- Review the [Overview](/docs/self-hosting/reference/overview) for a high-level understanding -- Explore the [source code](https://github.com/rivet-gg/rivet) on GitHub -- Check our [system architecture](/docs/general/system-architecture) documentation -- Join our [Discord community](https://discord.gg/rivet) for discussions -## Configuration - -# Configuration - -Rivet Engine can be configured through environment variables or configuration files. The configuration system is defined in `packages/common/config/`. - -## Configuration Methods - -### Environment Variables - -The most common way to configure Rivet: - -```bash -RIVET_PORT=5032 \ -RIVET_STORAGE_TYPE=postgres \ -RIVET_POSTGRES_URL="postgresql://..." \ -rivet-engine -``` - -### Configuration File - -For complex deployments, use a YAML or JSON configuration file: - -```yaml -# rivet.yaml -port: 5032 -storage: - type: postgres - postgres: - url: postgresql://... -``` - -Load the configuration: - -```bash -rivet-engine --config rivet.yaml -``` - -## Core Configuration - -### Server Settings - -| Variable | Description | Default | -|----------|-------------|---------| -| `RIVET_PORT` | HTTP server port | `5032` | -| `RIVET_HOST` | Bind address | `0.0.0.0` | -| `RIVET_WORKERS` | Number of worker threads | CPU cores | -| `RIVET_MAX_CONNECTIONS` | Maximum concurrent connections | `10000` | - -### Storage Configuration - -| Variable | Description | Options | -|----------|-------------|---------| -| `RIVET_STORAGE_TYPE` | Storage backend type | `filesystem`, `postgres`, `foundationdb` | -| `RIVET_DATA_DIR` | Directory for file storage | `/data` | - -### Database Settings - -For PostgreSQL: - -| Variable | Description | -|----------|-------------| -| `RIVET_POSTGRES_URL` | PostgreSQL connection string | -| `RIVET_POSTGRES_POOL_SIZE` | Connection pool size | -| `RIVET_POSTGRES_MAX_CONNECTIONS` | Maximum connections | - -### PubSub Configuration - -| Variable | Description | Options | -|----------|-------------|---------| -| `RIVET_PUBSUB_TYPE` | PubSub backend | `memory`, `postgres`, `nats` | -| `RIVET_NATS_URL` | NATS server URL | | -| `RIVET_NATS_CLUSTER` | NATS cluster name | | - -## Advanced Configuration - -### Performance Tuning - -```bash -# Increase connection limits -RIVET_MAX_CONNECTIONS=50000 -RIVET_POSTGRES_POOL_SIZE=100 - -# Optimize for throughput -RIVET_BATCH_SIZE=1000 -RIVET_FLUSH_INTERVAL=100 - -# Enable compression -RIVET_COMPRESSION=true -RIVET_COMPRESSION_LEVEL=6 -``` - -### High Availability - -```bash -# Enable clustering -RIVET_CLUSTER_ENABLED=true -RIVET_CLUSTER_NODE_ID=node-1 -RIVET_CLUSTER_SEEDS=node-2:5032,node-3:5032 - -# Configure replication -RIVET_REPLICATION_FACTOR=3 -RIVET_MIN_REPLICAS=2 -``` - -### Security - -```bash -# Authentication -RIVET_AUTH_ENABLED=true -RIVET_AUTH_TOKEN=secret-token -RIVET_AUTH_METHOD=bearer - -# TLS/SSL -RIVET_TLS_ENABLED=true -RIVET_TLS_CERT=/path/to/cert.pem -RIVET_TLS_KEY=/path/to/key.pem - -# Network restrictions -RIVET_ALLOWED_ORIGINS=https://app.example.com -RIVET_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16 -``` - -### Monitoring - -```bash -# Metrics -RIVET_METRICS_ENABLED=true -RIVET_METRICS_PORT=9090 -RIVET_METRICS_PATH=/metrics - -# Logging -RIVET_LOG_LEVEL=info -RIVET_LOG_FORMAT=json -RIVET_LOG_OUTPUT=/var/log/rivet/engine.log - -# Tracing -RIVET_TRACING_ENABLED=true -RIVET_TRACING_ENDPOINT=http://jaeger:14268 -``` - -## Configuration Profiles - -### Development - -```bash -# Minimal configuration for local development -RIVET_STORAGE_TYPE=filesystem -RIVET_DATA_DIR=./data -RIVET_LOG_LEVEL=debug -``` - -### Production - -```bash -# Robust configuration for production -RIVET_STORAGE_TYPE=postgres -RIVET_POSTGRES_URL="postgresql://user:pass@db:5432/rivet" -RIVET_POSTGRES_POOL_SIZE=50 -RIVET_PUBSUB_TYPE=nats -RIVET_NATS_URL=nats://nats:4222 -RIVET_AUTH_ENABLED=true -RIVET_AUTH_TOKEN="$" -RIVET_TLS_ENABLED=true -RIVET_LOG_LEVEL=warn -RIVET_METRICS_ENABLED=true -``` - -### High Performance - -```bash -# Optimized for maximum throughput -RIVET_WORKERS=32 -RIVET_MAX_CONNECTIONS=100000 -RIVET_BATCH_SIZE=5000 -RIVET_COMPRESSION=false -RIVET_STORAGE_TYPE=foundationdb -RIVET_FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster -``` - -## Environment-Specific Overrides - -Use environment prefixes for different deployments: - -```bash -# Production -PROD_RIVET_STORAGE_TYPE=postgres -PROD_RIVET_AUTH_ENABLED=true - -# Staging -STAGING_RIVET_STORAGE_TYPE=postgres -STAGING_RIVET_LOG_LEVEL=debug - -# Development -DEV_RIVET_STORAGE_TYPE=filesystem -DEV_RIVET_LOG_LEVEL=trace -``` - - For a complete list of configuration options, refer to the source code in `packages/common/config/`. - -## Next Steps - -- Choose a [database backend](/docs/self-hosting/reference/databases) -- Configure [networking options](/docs/self-hosting/reference/networking) -- Set up [monitoring and metrics](/docs/self-hosting/reference/monitoring) -## Connecting - -# Connecting to Rivet Engine - -## Default Configuration - -With no environment variables set, Rivet defaults to: -- Storing data on the local filesystem -- Running on `localhost:5032` -- Using in-memory pubsub - -This is perfect for local development and testing. - -## Connecting Runners - -To connect a runner to your Rivet Engine, set the `RIVET_ENGINE` environment variable: - -```bash -RIVET_ENGINE=http://your-engine-host:5032 npm run dev -``` - -Once connected: -- The runner appears in the Runners tab of the dashboard -- Your actor names show up in the sidebar -- The engine begins routing traffic to your runner - -## Environment Variables - -### Core Variables - -#### `RIVET_ENGINE` -The endpoint of your Rivet Engine instance. - -```bash -# Local development -RIVET_ENGINE=http://localhost:5032 - -# Production -RIVET_ENGINE=https://engine.your-domain.com -``` - -#### `RIVET_NAMESPACE` -The namespace to run actors in. Useful for multi-tenant deployments. - -```bash -RIVET_NAMESPACE=production -``` - -#### `RIVET_RUNNER` -A human-readable name for the runner. - -```bash -RIVET_RUNNER=worker-01 -``` - -#### `RIVET_RUNNER_KEY` -A unique key for the runner. If another runner connects with the same key, the previous one is disconnected. This is useful for handling zombie runners that weren't shut down gracefully. - -```bash -RIVET_RUNNER_KEY=unique-runner-key-123 -``` - - Generate a unique runner key using: `uuidgen` or `openssl rand -hex 16` - -## Connection Examples - -### Development Setup - -```bash -# Start the engine (defaults to local storage) -rivet-engine - -# In another terminal, start your runner -RIVET_ENGINE=http://localhost:5032 npm run dev -``` - -### Production Setup - -```bash -# On the engine server -RIVET_STORAGE_TYPE=postgres \ -RIVET_POSTGRES_URL="postgresql://..." \ -rivet-engine - -# On runner nodes -RIVET_ENGINE=https://engine.example.com \ -RIVET_NAMESPACE=production \ -RIVET_RUNNER=worker-$(hostname) \ -RIVET_RUNNER_KEY=$(cat /etc/machine-id) \ -npm run start -``` - -## Client Connection - -Clients connect to the engine using RivetKit: - -```typescript -const rivet = new Rivet(); -``` - -## Connection Security - -### Authentication - -For production deployments, secure your engine: - -```bash -# Engine configuration -RIVET_AUTH_TOKEN=secret-token-here - -# Runner configuration -RIVET_ENGINE=https://engine.example.com -RIVET_AUTH_TOKEN=secret-token-here -``` - -### TLS/SSL - -Always use HTTPS in production: -- Use a reverse proxy (nginx, Caddy) with SSL certificates -- Or configure the engine with TLS certificates directly - -## Troubleshooting - -### Runner Not Appearing - -If your runner doesn't appear in the dashboard: - -1. Check the engine is accessible: - ```bash - curl http://your-engine:5032/health - ``` - -2. Verify environment variables are set: - ```bash - echo $RIVET_ENGINE - ``` - -3. Check runner logs for connection errors - -### Connection Refused - -- Ensure the engine is running on the correct port -- Check firewall rules allow traffic on port 5032 -- Verify the engine host is reachable from runner nodes - -### Duplicate Runners - -If you see duplicate runners: -- Set unique `RIVET_RUNNER_KEY` values -- Or let the engine auto-generate keys (omit the variable) - -## Next Steps - -- Configure your [engine settings](/docs/self-hosting/reference/configuration) -- Set up a [database backend](/docs/self-hosting/reference/databases) -- Learn about [networking options](/docs/self-hosting/reference/networking) -## Supported Databases - -# Supported Databases - -Rivet supports multiple database backends for storing actor state and metadata. Choose based on your scale and operational requirements. - -## PostgreSQL - -**Recommended for most production deployments.** - -PostgreSQL provides a robust, battle-tested foundation for Rivet with excellent performance and reliability. - -### Features -- ACID compliance -- Strong consistency -- Built-in replication -- Extensive tooling ecosystem -- Supports up to thousands of actors - -### Configuration - -```bash -RIVET_STORAGE_TYPE=postgres -RIVET_POSTGRES_URL="postgresql://user:password@localhost:5432/rivet" -``` - -### Connection String Format - -``` -postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] -``` - -### Required Schema - -Rivet automatically creates required tables on startup: -- `actors` - Actor metadata and configuration -- `actor_state` - Persistent actor state -- `messages` - Message queue for actors -- `events` - Event log for debugging - -### Performance Tuning - -```sql --- Optimize for Rivet workload -ALTER SYSTEM SET max_connections = 200; -ALTER SYSTEM SET shared_buffers = '256MB'; -ALTER SYSTEM SET effective_cache_size = '1GB'; -ALTER SYSTEM SET work_mem = '4MB'; -``` - -### High Availability - -Use PostgreSQL replication for HA: -- Streaming replication for read replicas -- Logical replication for multi-region -- Tools like Patroni for automatic failover - -## FoundationDB (Enterprise) - -**For massive scale deployments.** - -FoundationDB is a distributed database designed for extreme scale and reliability. - - FoundationDB support is available in Rivet Enterprise. Contact us for access. - -### Features -- Unbounded horizontal scaling -- ACID transactions across clusters -- Automatic sharding and rebalancing -- Multi-region support -- Supports millions of actors - -### Configuration - -```bash -RIVET_STORAGE_TYPE=foundationdb -RIVET_FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster -``` - -### Cluster File - -``` -# /etc/foundationdb/fdb.cluster -cluster_name:id@host1:4500,host2:4500,host3:4500 -``` - -### Benefits -- No manual sharding required -- Automatic failure recovery -- Consistent performance at any scale -- Multi-datacenter deployments - -## File System - -**For development and single-node deployments.** - -The file system backend stores data directly on disk using efficient binary formats. - -### Features -- Zero dependencies -- Simple backup/restore -- Good performance for small deployments -- Suitable for up to hundreds of actors - -### Configuration - -```bash -RIVET_STORAGE_TYPE=filesystem -RIVET_DATA_DIR=/var/lib/rivet/data -``` - -### Directory Structure - -``` -/var/lib/rivet/data/ -├── actors/ -│ ├── metadata/ -│ └── state/ -├── messages/ -└── events/ -``` - -### Limitations -- Single node only (no clustering) -- No concurrent access from multiple engines -- Limited query capabilities -- Manual backup required - -### Backup - -```bash -# Stop the engine -systemctl stop rivet-engine - -# Backup data directory -tar -czf rivet-backup.tar.gz /var/lib/rivet/data - -# Restore -tar -xzf rivet-backup.tar.gz -C / -``` - -## Choosing a Database - -### Development - -Use **File System** for: -- Local development -- Testing and CI/CD -- Prototyping - -### Small to Medium Production - -Use **PostgreSQL** for: -- Production deployments up to 10,000 actors -- When you need SQL compatibility -- Existing PostgreSQL infrastructure -- Strong consistency requirements - -### Large Scale Production - -Use **FoundationDB** for: -- More than 10,000 actors -- Multi-region deployments -- Automatic scaling requirements -- Mission-critical reliability - -## Migration Between Backends - -Rivet provides tools to migrate between storage backends: - -```bash -# Export from filesystem to PostgreSQL -rivet-migrate \ - --from filesystem --from-path /data \ - --to postgres --to-url "postgresql://..." - -# Export from PostgreSQL to FoundationDB -rivet-migrate \ - --from postgres --from-url "postgresql://..." \ - --to foundationdb --to-cluster /etc/fdb.cluster -``` - - Always test migrations in a staging environment first. Migrations may require downtime. - -## Performance Comparison - -| Backend | Actors | Latency | Throughput | HA | Scaling | -|---------|--------|---------|------------|-------|---------| -| File System | < 1K | < 1ms | High | No | Manual | -| PostgreSQL | < 100K | < 5ms | High | Yes | Vertical | -| FoundationDB | Unlimited | < 10ms | Very High | Yes | Horizontal | - -## Next Steps - -- Configure [PubSub backends](/docs/self-hosting/reference/pubsub) -- Set up [networking](/docs/self-hosting/reference/networking) -- Learn about [monitoring options](/docs/self-hosting/reference/monitoring) -## Networking - -# Networking - -Rivet provides sophisticated networking capabilities that are automatically configured for you, including proxying and secure tunneling. - -## Rivet Proxy - -The Rivet Proxy enables seamless communication with actors through HTTP/WebSocket endpoints. - -### How It Works - -1. **Client Request**: Client sends request to Rivet Proxy -2. **Routing**: Proxy identifies target actor and runner -3. **Forwarding**: Request forwarded to appropriate runner -4. **Response**: Runner processes request and returns response - -``` -Client → Rivet Proxy → Runner → Actor - ↓ - [Routing Logic] -``` - -### Automatic Configuration - -The proxy is automatically configured when you: -- Start the Rivet Engine -- Connect runners to the engine -- Deploy actors - -No manual configuration required! - -### Request Routing - -Requests are routed based on: -- Actor ID in the URL path -- Custom routing rules -- Load balancing policies -- Geographic proximity (enterprise) - -Example URLs: -``` -https://engine.example.com/actors//action -wss://engine.example.com/actors//connect -``` - -## Tunneling - -Rivet includes built-in tunneling (similar to ngrok) for exposing actors securely without opening public ports. - -### How Tunneling Works - -1. **Runner Registration**: Runner connects to engine via outbound connection -2. **Tunnel Creation**: Engine creates secure tunnel back to runner -3. **Request Proxying**: Incoming requests routed through tunnel -4. **No Inbound Ports**: Runner needs no open inbound ports - -``` -Internet → Engine (Public) → Tunnel → Runner (Private) → Actor -``` - -### Benefits - -- **Security**: No exposed ports on runner machines -- **Simplicity**: Works behind NAT/firewalls -- **Automatic**: No configuration needed -- **Scalable**: Thousands of concurrent tunnels - -### Use Cases - -Perfect for: -- Development machines behind NAT -- Runners in private networks -- Edge deployments -- Kubernetes pods without ingress - -## Network Architecture - -### Single Node - -``` -┌─────────────────────────────┐ -│ Rivet Node │ -│ │ -│ ┌─────────┐ ┌──────────┐ │ -│ │ Engine │──│ Runner │ │ -│ └────┬────┘ └──────────┘ │ -│ │ │ -│ ┌────▼────┐ │ -│ │ Proxy │◄───────────────┼── Clients -│ └─────────┘ │ -└─────────────────────────────┘ -``` - -### Distributed - -``` -┌──────────────┐ ┌──────────────┐ -│ Engine Node │ │ Runner Node │ -│ │ │ │ -│ ┌────────┐ │ │ ┌────────┐ │ -│ │ Engine │◄─┼─────┼──│ Runner │ │ -│ └───┬────┘ │ │ └────────┘ │ -│ │ │ └──────────────┘ -│ ┌───▼────┐ │ -│ │ Proxy │◄─┼───── Clients -│ └────────┘ │ -└──────────────┘ -``` - -## Port Configuration - -### Default Ports - -| Service | Port | Protocol | Purpose | -|---------|------|----------|---------| -| Engine API | 5032 | HTTP/WS | API and WebSocket connections | -| Proxy | 5033 | HTTP/WS | Actor proxy endpoint | -| Metrics | 9090 | HTTP | Prometheus metrics | -| Health | 8080 | HTTP | Health checks | - -### Custom Port Configuration - -```bash -# Change default ports -RIVET_PORT=8080 -RIVET_PROXY_PORT=8081 -RIVET_METRICS_PORT=9091 -RIVET_HEALTH_PORT=8082 -``` - -## Load Balancing - -### Built-in Load Balancing - -Rivet automatically load balances across: -- Multiple runners for the same actor type -- Geographic regions (enterprise) -- Available resources - -### Load Balancing Strategies - -```bash -# Round-robin (default) -RIVET_LB_STRATEGY=round-robin - -# Least connections -RIVET_LB_STRATEGY=least-conn - -# Resource-based -RIVET_LB_STRATEGY=resource - -# Geographic (enterprise) -RIVET_LB_STRATEGY=geo -``` - -## TLS/SSL Configuration - -### Enable TLS - -```bash -RIVET_TLS_ENABLED=true -RIVET_TLS_CERT=/path/to/cert.pem -RIVET_TLS_KEY=/path/to/key.pem -RIVET_TLS_CA=/path/to/ca.pem -``` - -### Automatic TLS (Let's Encrypt) - -```bash -RIVET_TLS_AUTO=true -RIVET_TLS_DOMAINS=engine.example.com,api.example.com -RIVET_TLS_EMAIL=admin@example.com -``` - -### TLS Between Components - -```bash -# Secure runner connections -RIVET_INTERNAL_TLS=true -RIVET_INTERNAL_TLS_VERIFY=true -``` - -## Firewall Configuration - -### Required Inbound Ports - -For the **Engine**: -```bash -# Allow API access -ufw allow 5032/tcp - -# Allow proxy access -ufw allow 5033/tcp - -# Allow metrics (internal only) -ufw allow from 10.0.0.0/8 to any port 9090 -``` - -For **Runners** (with tunneling): -```bash -# No inbound ports required! -# Only outbound to engine:5032 -``` - -### Network Policies (Kubernetes) - -```yaml -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: rivet-engine -spec: - podSelector: - matchLabels: - app: rivet-engine - ingress: - - ports: - - port: 5032 - - port: 5033 - egress: - - # Allow all outbound -``` - -## DNS Configuration - -### Basic Setup - -```bash -# A records -engine.example.com → Engine IP -*.actors.example.com → Engine IP - -# With CDN -engine.example.com → CDN → Engine IP -``` - -### Multi-Region (Enterprise) - -```bash -# GeoDNS routing -us.engine.example.com → US Engine -eu.engine.example.com → EU Engine -ap.engine.example.com → AP Engine - -# Global endpoint with latency routing -engine.example.com → Nearest Engine -``` - -## Network Optimization - -### TCP Tuning - -```bash -# Increase connection limits -sysctl -w net.core.somaxconn=65535 -sysctl -w net.ipv4.tcp_max_syn_backlog=65535 - -# Enable TCP fast open -sysctl -w net.ipv4.tcp_fastopen=3 - -# Optimize for low latency -sysctl -w net.ipv4.tcp_low_latency=1 -``` - -### HTTP/2 and WebSocket - -```bash -# Enable HTTP/2 -RIVET_HTTP2_ENABLED=true - -# WebSocket configuration -RIVET_WS_MAX_FRAME_SIZE=1048576 -RIVET_WS_COMPRESSION=true -``` - -## Monitoring Network Health - -### Health Endpoints - -```bash -# Engine health -curl http://engine:8080/health - -# Proxy health -curl http://engine:5033/health - -# Runner connectivity -curl http://engine:5032/api/runners -``` - -### Network Metrics - -Monitor these key metrics: -- Connection count -- Request latency -- Tunnel stability -- Bandwidth usage -- Error rates - -## Troubleshooting - -### Connection Issues - -1. **Check engine is reachable**: - ```bash - telnet engine.example.com 5032 - ``` - -2. **Verify DNS resolution**: - ```bash - nslookup engine.example.com - ``` - -3. **Test with curl**: - ```bash - curl -v http://engine.example.com:5032/health - ``` - -### Tunnel Problems - -1. **Check runner logs** for tunnel errors -2. **Verify outbound connectivity** from runner -3. **Ensure no proxy** interfering with WebSocket -4. **Check firewall** allows outbound connections - -### Performance Issues - -1. **Monitor latency** between components -2. **Check network** bandwidth utilization -3. **Verify MTU** settings (especially for tunnels) -4. **Enable compression** for large payloads - - Rivet's networking is designed to work out-of-the-box in most environments. Manual configuration is only needed for advanced use cases. - -## Next Steps - -- Learn about [deployment platforms](/docs/self-hosting/platforms/docker-container) -- Configure [monitoring and metrics](/docs/self-hosting/reference/monitoring) -- Set up [high availability](/docs/self-hosting/reference/high-availability) -## Overview - -# Self-Hosting Overview - -Rivet consists of three main components that work together to provide a complete actor orchestration platform: - -## Core Components - -### Rivet Engine - -The main service that orchestrates actors. The engine: -- Manages actor lifecycle (creation, destruction, scaling) -- Handles state persistence and replication -- Routes messages between actors and clients -- Provides the HTTP/WebSocket API for communication - -### RivetKit - -The JavaScript/TypeScript library that connects your application code to the Rivet Engine. RivetKit: -- Provides the actor programming model -- Handles serialization and communication with the engine -- Offers client libraries for connecting to actors -- Manages local development workflows - -### Runners - -Processes that execute your actor code. Runners: -- Connect to the Rivet Engine to receive work -- Execute actor instances in isolated environments -- Handle actor lifecycle events -- Report health and metrics back to the engine - -## Architecture - -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Client │────▶│ Engine │◀────│ Runner │ -│ (RivetKit) │ │ │ │ │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ - ▼ - ┌─────────────┐ - │ Storage │ - │ (DB/File) │ - └─────────────┘ -``` - -## Deployment Models - -### Single Node - -All components run on a single machine: -- Engine, runners, and storage co-located -- Suitable for development and small deployments -- Simple to manage and operate - -### Distributed - -Components spread across multiple machines: -- Engine runs on dedicated nodes -- Runners distributed across worker nodes -- Storage on separate database cluster -- Suitable for production and high-availability - -## Storage Backends - -Rivet supports multiple storage backends: -- **File System** - Default, suitable for single-node deployments -- **PostgreSQL** - Recommended for production -- **FoundationDB** - Enterprise option for massive scale - -## Next Steps - -- Learn how to [connect runners](/docs/self-hosting/reference/connecting) -- Understand [configuration options](/docs/self-hosting/reference/configuration) -- Choose a [database backend](/docs/self-hosting/reference/databases) -## Supported PubSub - -# Supported PubSub Backends - -Rivet uses PubSub for real-time messaging between components. Choose a backend based on your deployment architecture and scale requirements. - -## PostgreSQL NOTIFY - -**Best for PostgreSQL-based deployments.** - -Uses PostgreSQL's built-in LISTEN/NOTIFY for pub/sub messaging. - -### Features -- No additional infrastructure -- Guaranteed delivery to connected clients -- Simple and reliable -- Good for small to medium scale - -### Configuration - -```bash -RIVET_PUBSUB_TYPE=postgres -RIVET_POSTGRES_URL="postgresql://user:password@localhost:5432/rivet" -``` - -### How It Works - -Rivet uses PostgreSQL channels for different message types: -- `rivet_actor_events` - Actor lifecycle events -- `rivet_state_updates` - State synchronization -- `rivet_messages` - Inter-actor messaging - -### Limitations -- Limited to 8KB payload size -- Requires persistent connections -- Performance degrades with many listeners -- Single region only - -### Performance Tuning - -```sql --- Increase notification queue size -ALTER SYSTEM SET max_notify_queue_pages = 8; -``` - -## NATS - -**Recommended for distributed deployments.** - -NATS is a high-performance messaging system designed for cloud-native applications. - -### Features -- Extremely high throughput (millions of messages/sec) -- Low latency ( - Never use memory pubsub in production. It's only suitable for development and testing. - -## Choosing a PubSub Backend - -### Development - -Use **Memory** for: -- Local development -- Unit testing -- Quick prototypes - -### Small Production - -Use **PostgreSQL NOTIFY** for: -- When already using PostgreSQL for storage -- Simple deployments -- < 100 messages per second -- Single datacenter - -### Large Production - -Use **NATS** for: -- Distributed deployments -- High message throughput -- Multi-region setups -- Microservices architecture - -## Performance Comparison - -| Backend | Throughput | Latency | HA | Persistence | Complexity | -|---------|------------|---------|-------|-------------|------------| -| Memory | Unlimited* | < 0.1ms | No | No | None | -| PostgreSQL | 1K msg/s | < 5ms | Yes | Yes | Low | -| NATS | 1M+ msg/s | < 1ms | Yes | Optional | Medium | - -*Limited by single process capacity - -## Message Patterns - -Rivet uses these PubSub patterns: - -### Topic-Based Routing - -``` -actors...events -actors...messages -system.health -system.metrics -``` - -### Request-Reply - -For synchronous operations: -``` -requests. -replies. -``` - -### Broadcast - -For cluster-wide notifications: -``` -cluster.nodes.join -cluster.nodes.leave -cluster.config.update -``` - -## Monitoring PubSub - -### PostgreSQL NOTIFY - -Monitor active listeners: -```sql -SELECT pid, state, query -FROM pg_stat_activity -WHERE query LIKE 'LISTEN%'; -``` - -### NATS - -Use NATS monitoring endpoints: -```bash -# Server stats -curl http://localhost:8222/varz - -# Connection info -curl http://localhost:8222/connz - -# Route info (cluster) -curl http://localhost:8222/routez -``` - -### Memory - -Enable debug logging: -```bash -RIVET_LOG_LEVEL=debug -RIVET_LOG_PUBSUB=true -``` - -## Troubleshooting - -### Messages Not Delivered - -1. Check connectivity to PubSub backend -2. Verify authentication credentials -3. Ensure topics/channels exist -4. Check for network partitions - -### High Latency - -1. Monitor PubSub server load -2. Check network latency -3. Consider upgrading to NATS -4. Enable batching if supported - -### Message Loss - -1. Enable persistence (NATS JetStream) -2. Increase buffer sizes -3. Implement retry logic -4. Monitor for disconnections - -## Next Steps +Follow the [Railway Quick Start guide](https://docs.railway.com/quick-start) to deploy your repository: -- Configure [networking options](/docs/self-hosting/reference/networking) -- Set up [monitoring](/docs/self-hosting/reference/monitoring) -- Deploy to [production platforms](/docs/self-hosting/platforms/docker-container) \ No newline at end of file +1. Connect your GitHub account to Railway +2. Select your repository containing your Rivet application +3. Railway will automatically detect and deploy your application +4. Configure environment variables for your application: + - `RIVET_ENGINE=$}` - Points to the Rivet Engine service's private domain \ No newline at end of file diff --git a/site/public/llms.txt b/site/public/llms.txt index 73fce599e4..28919f183f 100644 --- a/site/public/llms.txt +++ b/site/public/llms.txt @@ -14,6 +14,8 @@ https://rivet.gg/blog/2025-06-02-faster-route-propagation-by-rewriting-our-traef https://rivet.gg/blog/2025-06-10-rivet-functions-launch https://rivet.gg/blog/2025-06-24-cloudflare-containers-vs-rivet-containers-vs-fly-machines https://rivet.gg/blog/2025-07-01-introducing-rivetkit-backend-libraries-that-replace-saas +https://rivet.gg/blog/2025-09-04-rivet-v2-launch +https://rivet.gg/blog/2025-09-12-performance-lifecycle-updates https://rivet.gg/blog/2025-1-12-rivet-inspector https://rivet.gg/blog/godot-multiplayer-compared-to-unity https://rivet.gg/changelog @@ -29,6 +31,8 @@ https://rivet.gg/changelog/2025-06-02-faster-route-propagation-by-rewriting-our- https://rivet.gg/changelog/2025-06-10-rivet-functions-launch https://rivet.gg/changelog/2025-06-24-cloudflare-containers-vs-rivet-containers-vs-fly-machines https://rivet.gg/changelog/2025-07-01-introducing-rivetkit-backend-libraries-that-replace-saas +https://rivet.gg/changelog/2025-09-04-rivet-v2-launch +https://rivet.gg/changelog/2025-09-12-performance-lifecycle-updates https://rivet.gg/changelog/2025-1-12-rivet-inspector https://rivet.gg/changelog/godot-multiplayer-compared-to-unity https://rivet.gg/cloud @@ -86,23 +90,18 @@ https://rivet.gg/docs/integrations/hono https://rivet.gg/docs/integrations/next-js https://rivet.gg/docs/integrations/trpc https://rivet.gg/docs/integrations/vitest -https://rivet.gg/docs/self-hosting/installing/binary -https://rivet.gg/docs/self-hosting/installing/build-from-source -https://rivet.gg/docs/self-hosting/installing/docker-image -https://rivet.gg/docs/self-hosting/platforms/aws -https://rivet.gg/docs/self-hosting/platforms/docker-compose -https://rivet.gg/docs/self-hosting/platforms/docker-container -https://rivet.gg/docs/self-hosting/platforms/google-cloud -https://rivet.gg/docs/self-hosting/platforms/hetzner -https://rivet.gg/docs/self-hosting/platforms/kubernetes -https://rivet.gg/docs/self-hosting/platforms/railway -https://rivet.gg/docs/self-hosting/reference/architecture -https://rivet.gg/docs/self-hosting/reference/configuration -https://rivet.gg/docs/self-hosting/reference/connecting -https://rivet.gg/docs/self-hosting/reference/databases -https://rivet.gg/docs/self-hosting/reference/networking -https://rivet.gg/docs/self-hosting/reference/overview -https://rivet.gg/docs/self-hosting/reference/pubsub +https://rivet.gg/docs/self-hosting +https://rivet.gg/docs/self-hosting/aws-fargate +https://rivet.gg/docs/self-hosting/configuration +https://rivet.gg/docs/self-hosting/connect-backend +https://rivet.gg/docs/self-hosting/docker-compose +https://rivet.gg/docs/self-hosting/docker-container +https://rivet.gg/docs/self-hosting/google-cloud-run +https://rivet.gg/docs/self-hosting/hetzner +https://rivet.gg/docs/self-hosting/install +https://rivet.gg/docs/self-hosting/kubernetes +https://rivet.gg/docs/self-hosting/multi-region +https://rivet.gg/docs/self-hosting/railway https://rivet.gg/guides/chat https://rivet.gg/meme/wired-in https://rivet.gg/oss-friends diff --git a/site/src/content/docs/general/logging.mdx b/site/src/content/docs/general/logging.mdx index 501074d8bb..86ead2d751 100644 --- a/site/src/content/docs/general/logging.mdx +++ b/site/src/content/docs/general/logging.mdx @@ -2,139 +2,101 @@ Actors provide a built-in way to log complex data to the console. -When dealing with lots of data, `console.log` often doesn't cut it. Using the context's log object (`c.log`) allows you to log complex data using structured logging. +Using the context's log object (`c.log`) allows you to log complex data using structured logging. -Using the actor logging API is completely optional. +Using the actor logging API is completely optional. ## Log levels -There are 5 log levels: +There are 7 log levels: -| Level | Call | Description | -| -------- | ------------------------------- | ---------------------------------------------------------------- | -| Critical | `c.log.critical(message, ...args);` | Severe errors that prevent core functionality | -| Error | `c.log.error(message, ...args);` | Errors that affect functionality but allow continued operation | -| Warning | `c.log.warn(message, ...args);` | Potentially harmful situations that should be addressed | -| Info | `c.log.info(message, ...args);` | General information about significant events & state changes | -| Debug | `c.log.debug(message, ...args);` | Detailed debugging information, usually used only in development | +| Level | Call | Description | +| ------ | ------------------------------- | ---------------------------------------------------------------- | +| Fatal | `c.log.fatal(message, ...args);` | Critical errors that prevent core functionality | +| Error | `c.log.error(message, ...args);` | Errors that affect functionality but allow continued operation | +| Warn | `c.log.warn(message, ...args);` | Potentially harmful situations that should be addressed | +| Info | `c.log.info(message, ...args);` | General information about significant events & state changes | +| Debug | `c.log.debug(message, ...args);` | Detailed debugging information, usually used in development | +| Trace | `c.log.trace(message, ...args);` | Very detailed debugging information, usually for tracing flow | +| Silent | N/A | Disables all logging output | ## Structured logging The built-in logging API (using `c.log`) provides structured logging to let you log key-value -pairs instead of raw strings. Structures logs are readable by both machines & +pairs instead of raw strings. Structured logs are readable by both machines & humans to make them easier to parse & search. -Passing an object to a log will print as structured data. For example: +When using `c.log`, the actor's name, key, and actor ID are automatically included in every log output. This makes it easy to filter and trace logs by specific actors in production environments. + +### Examples ```typescript -c.log.info('increment', { connection: c.conn.id, count }); -// Prints: level=INFO msg=increment connection=123 count=456 -``` +// Just a message +c.log.info('server started'); +// Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 msg="server started" -The first parameter in each log method is the message. The rest of the arguments are used for structured logging. +// Message with an object +c.log.info('user connected', { userId: 123, ip: '192.168.1.1' }); +// Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 msg="user connected" userId=123 ip="192.168.1.1" -## `c.log` vs `console.log` logging +// Just an object (no message) +c.log.info({ action: 'purchase', amount: 99.99, currency: 'USD' }); +// Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 action="purchase" amount=99.99 currency="USD" +``` -`c.log` makes it easier to manage complex logs, while `console.log` can -become unmaintainable at scale. +The logging system is built on [Pino](https://getpino.io/#/docs/api?id=logger), a high-performance structured logger for Node.js. -Consider this example: +## Configuration - +### Environment Variables -```typescript structured_logging.ts -import { actor } from "@rivetkit/actor"; +You can configure logging behavior using environment variables: -const counter = actor({ - state: { count: 0 }, - - actions: { - increment: (c, count) => { - // Prints: level=INFO msg=increment connection=123 count=456 - c.log.info('increment', { connection: c.conn.id, count }); +| Variable | Description | Values | Default | +| -------- | ----------- | ------ | ------- | +| `LOG_LEVEL` | Sets the minimum log level to display | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent` | `warn` | +| `LOG_TARGET` | Include the module name that logged the message | `1` to enable, `0` to disable | `0` | +| `LOG_TIMESTAMP` | Include timestamp in log output | `1` to enable, `0` to disable | `0` | - c.state.count += count; - return c.state.count; - } - } -}); +Example: +```bash +LOG_LEVEL=debug LOG_TARGET=1 LOG_TIMESTAMP=1 node server.js ``` -```typescript unstructured_logging.ts -import { actor } from "@rivetkit/actor"; +### Log Level -const counter = actor({ - state: { count: 0 }, - - actions: { - increment: (c, count) => { - // Prints: Increment for connection 123 with count 456 - console.log(`Increment for connection ${c.conn.id} with count ${count}`); +You can configure the log level programmatically when running your server: - c.state.count += count; - return c.state.count; - } - } -}); +```typescript +registry.runServer({ + logging: { + logLevel: "debug" + } +}) ``` - +### Custom Pino Logger -If you need to search through a lot of logs, it's easier to read the structured logs. To find increments for a single connection, you can search `connection=123`. - -Additionally, structured logs can be parsed and queried at scale using tools like Elasticsearch, Loki, or Datadog. For example, you can parse the log `level=INFO msg=increment connection=123 count=456` in to the JSON object `{"level":"INFO","msg":"increment","connection":123,"count":456}` and then query it as you would any other structured data. - -## Usage in lifecycle hooks - -The logger is available in all lifecycle hooks: +You can also provide a custom Pino base logger for more advanced logging configurations: ```typescript -import { actor } from "@rivetkit/actor"; - -const loggingExample = actor({ - state: { events: [] }, - - onStart: (c) => { - c.log.info('actor_started', { timestamp: Date.now() }); - }, - - onBeforeConnect: (c, { params }) => { - c.log.debug('connection_attempt', { - ip: params.ip, - timestamp: Date.now() - }); - - return { authorized: true }; - }, - - onConnect: (c) => { - c.log.info('connection_established', { - connectionId: c.conn.id, - timestamp: Date.now() - }); - - c.state.events.push({ - type: 'connect', - connectionId: c.conn.id, - timestamp: Date.now() - }); - }, - - onDisconnect: (c) => { - c.log.info('connection_closed', { - connectionId: c.conn.id, - timestamp: Date.now() - }); - - c.state.events.push({ - type: 'disconnect', - connectionId: c.conn.id, - timestamp: Date.now() - }); - }, - - actions: { - // Actor actions... +import { pino } from "pino"; + +const customLogger = pino({ + level: "info", + transport: { + target: "pino-pretty" } }); + +registry.runServer({ + logging: { + baseLogger: customLogger, // Use your custom Pino logger + } +}) ``` + +If using a custom base logger, you must manually configure your own log level in the Pino logger. + +For more advanced Pino configuration options, see the [Pino API documentation](https://getpino.io/#/docs/api?id=export). + diff --git a/site/src/content/docs/integrations/pino.mdx b/site/src/content/docs/integrations/pino.mdx new file mode 100644 index 0000000000..320f025ba1 --- /dev/null +++ b/site/src/content/docs/integrations/pino.mdx @@ -0,0 +1,11 @@ +# Pino + +Rivet's actor system uses [Pino](https://getpino.io/), a high-performance structured logging library for Node.js, to power its logging infrastructure. + +For detailed information on how to use and configure logging in your actors, see the [Logging documentation](/docs/general/logging). + +## Learn More + +- [Logging in RivetKit](/docs/general/logging) - Complete guide to using logs in your actors +- [Pino Documentation](https://getpino.io/#/docs/api) - Official Pino API documentation + diff --git a/site/src/sitemap/mod.ts b/site/src/sitemap/mod.ts index 90ddc3631d..cc557cfcbf 100644 --- a/site/src/sitemap/mod.ts +++ b/site/src/sitemap/mod.ts @@ -324,6 +324,10 @@ export const sitemap = [ title: "Vitest", href: "/docs/integrations/vitest", }, + { + title: "Pino", + href: "/docs/integrations/pino", + }, ], }, ], @@ -412,11 +416,6 @@ export const sitemap = [ title: "More", collapsible: true, pages: [ - { - title: "Edge", - href: "/docs/cloud/edge", - icon: faGlobe, - }, { title: "CORS", href: "/docs/general/cors",