Codakey
Play
← Back to rybbit

How to Deploy & Use rybbit

Rybbit Deployment & Usage Guide

1. Prerequisites

Before deploying Rybbit, ensure you have:

Runtime & Tools:

  • Node.js (v18 or higher)
  • npm or yarn package manager
  • PostgreSQL (v14 or higher) - Primary database
  • ClickHouse (v23 or higher) - Analytics database
  • Redis (v7 or higher) - For job queue and caching
  • Docker & Docker Compose (optional, for containerized deployment)

Accounts (Optional):

  • BetterAuth account (for authentication, integrated via schema)
  • Email service (SMTP) for notifications and user verification

2. Installation

Clone the repository and install dependencies:

# Clone the repository
git clone https://github.com/rybbit-io/rybbit.git
cd rybbit

# Install dependencies
npm install
# or with yarn
yarn install

# Install dependencies for both server and client (if monorepo structure)
cd server && npm install
cd ../client && npm install

3. Configuration

Create environment files and configure essential services:

Create .env file in the server directory:

# Database Configuration
DATABASE_URL="postgresql://user:password@localhost:5432/rybbit"
CLICKHOUSE_URL="http://localhost:8123/rybbit"
CLICKHOUSE_USER="default"
CLICKHOUSE_PASSWORD=""
REDIS_URL="redis://localhost:6379"

# Application Settings
NODE_ENV="production"
PORT=3000
HOST="0.0.0.0"
SECRET_KEY="your-secret-key-here"

# Authentication (BetterAuth)
AUTH_SECRET="your-auth-secret"
AUTH_URL="http://localhost:3000"
AUTH_TRUST_HOST=true

# Email Configuration (for notifications)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="noreply@yourdomain.com"

# Uptime Monitoring (optional)
UPTIME_WORKER_CONCURRENCY=10
DISABLE_ORIGIN_CHECK=false  # Set to true only for development

# Tracking Configuration
TRACKING_ENDPOINT="/api/track"
ALLOWED_ORIGINS="https://yourdomain.com,http://localhost:3000"

Database Setup:

  1. PostgreSQL:
CREATE DATABASE rybbit;
CREATE USER rybbit_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE rybbit TO rybbit_user;
  1. ClickHouse:
# Install ClickHouse (Ubuntu/Debian)
sudo apt-get install clickhouse-server clickhouse-client

# Create database
clickhouse-client --query "CREATE DATABASE IF NOT EXISTS rybbit"
  1. Redis:
# Install Redis
sudo apt-get install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

4. Build & Run

Development Mode:

# Start development server with hot reload
npm run dev
# or
yarn dev

# The application will be available at http://localhost:3000

Production Build:

# Build the TypeScript application
npm run build
# or
yarn build

# Run the production server
npm start
# or
yarn start

# Using PM2 for process management (recommended for production)
npm install -g pm2
pm2 start dist/index.js --name "rybbit"

Database Migrations:

# Run database migrations (Drizzle ORM)
npm run db:push
# or
npx drizzle-kit push

# Generate migration files
npx drizzle-kit generate

Uptime Monitoring Worker:

# Start the BullMQ worker for uptime monitoring
npm run worker:uptime
# or run via PM2
pm2 start npm --name "rybbit-worker" -- run worker:uptime

5. Deployment

Rybbit can be deployed on various platforms:

Option A: Traditional VPS (Recommended for full control)

  • Platforms: DigitalOcean, Linode, AWS EC2, Google Cloud Compute
  • Requirements: Minimum 2GB RAM, 2 vCPUs, 20GB SSD
  • Setup: Follow the installation steps above on your VPS

Option B: Containerized Deployment

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: rybbit
      POSTGRES_USER: rybbit
      POSTGRES_PASSWORD: your_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  clickhouse:
    image: clickhouse/clickhouse-server:23
    volumes:
      - clickhouse_data:/var/lib/clickhouse
  
  redis:
    image: redis:7-alpine
  
  rybbit:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://rybbit:your_password@postgres:5432/rybbit
      - CLICKHOUSE_URL=http://clickhouse:8123/rybbit
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - clickhouse
      - redis

volumes:
  postgres_data:
  clickhouse_data:

Option C: Platform-as-a-Service

  • Railway.app: One-click deployment with PostgreSQL, Redis, and ClickHouse add-ons
  • Render.com: Supports background workers for uptime monitoring
  • Fly.io: Good for global distribution of tracking endpoints

Reverse Proxy Setup (Nginx):

server {
    listen 80;
    server_name analytics.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

6. Troubleshooting

Common Issues and Solutions:

  1. Database Connection Errors:
# Check PostgreSQL is running
sudo systemctl status postgresql

# Verify connection
psql -h localhost -U rybbit_user -d rybbit

# Ensure ClickHouse is accessible
curl http://localhost:8123
  1. TypeScript Build Errors:
# Clear build cache
rm -rf dist node_modules/.cache

# Reinstall dependencies
npm ci

# Check TypeScript version compatibility
npx tsc --version
  1. Uptime Monitoring Not Working:
# Check Redis connection for BullMQ
redis-cli ping

# Verify worker is running
pm2 status rybbit-worker

# Check logs for validation errors
tail -f logs/monitor-executor.log
  1. Tracking Endpoint Issues:
# Test tracking endpoint
curl -X POST http://localhost:3000/api/track \
  -H "Content-Type: application/json" \
  -d '{"event": "pageview", "url": "https://example.com"}'

# If CORS errors, verify ALLOWED_ORIGINS includes your domain
# For development, set DISABLE_ORIGIN_CHECK=true temporarily
  1. High Memory Usage:
# Monitor ClickHouse memory
clickhouse-client --query "SELECT * FROM system.metrics WHERE metric LIKE '%Memory%'"

# Adjust ClickHouse config in /etc/clickhouse-server/config.xml
# Set max_memory_usage and max_memory_usage_for_user appropriately
  1. Email Notifications Not Sending:
# Test SMTP connection
npm run test:email
# or use telnet
telnet your-smtp-server.com 587

# Check email logs
grep -i "smtp\|email" logs/*.log

Getting Help:

← Project overviewView alternatives to rybbit →