Documentation

Learn how to integrate Revi

docs
getting started
installation

Installation

Complete installation guide for setting up Revi error monitoring in your development environment, including backend, dashboard, and SDK components.

Installation Guide

Welcome to the complete installation guide for Revi! This guide covers setting up the full Revi stack, including the backend API, dashboard, and SDK for comprehensive error monitoring and session replay.

Architecture Overview

Revi consists of three main components:

  • Backend API: Encore.ts-based service for data collection and storage
  • Dashboard: Next.js web application for monitoring and analytics
  • SDK: Client-side JavaScript library for error capture and session recording
1
Step 1: Clone the Repository

Clone the Revi repository to get started:

git clone https://github.com/your-org/revi.git
cd revi
2
Step 2: Set Up the Backend

The Revi backend is built with Encore.ts and requires PostgreSQL.

Install Encore CLI:

curl -L https://encore.dev/install.sh | bash

Navigate to the backend directory:

cd backend

Install dependencies:

npm
pnpm
yarn
npm install

Set up environment variables:

cp .env.example .env
# Edit .env with your database credentials

Run database migrations:

encore db migrate

Start the backend server:

encore run

The backend will be available at http://localhost:4000

3
Step 3: Set Up the Dashboard

The dashboard is a Next.js application that provides the web interface.

Navigate to the dashboard directory:

cd ../dashboard

Install dependencies:

npm
pnpm
yarn
npm install

Configure environment variables:

cp .env.example .env

Edit .env with your configuration:

DATABASE_URL=postgresql://user:password@localhost:5432/revi
NEXT_PUBLIC_REVI_API_URL=http://localhost:4000
BETTER_AUTH_SECRET=your-auth-secret-here
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-secret

Set up the database schema:

npx drizzle-kit push

Start the dashboard:

npm
pnpm
yarn
npm run dev

The dashboard will be available at http://localhost:3000

4
Step 4: Build and Test the SDK

The SDK is the client-side library that captures errors and user sessions.

Navigate to the SDK directory:

cd ../sdk

Install dependencies:

npm
pnpm
yarn
npm install

Build the SDK:

npm
pnpm
yarn
npm run build

Test the SDK (optional):

npm
pnpm
yarn
npm test

Create a test application:

cd examples/react-demo
npm install
npm start
5
Step 5: Create Your First Project

Now that everything is running, create your first monitoring project:

  1. Open the dashboard at http://localhost:3000
  2. Sign in with Google OAuth or create an account
  3. Click "Create New Project" and fill in the details
  4. Copy the generated API key
  5. Use the API key in your applications with the Revi SDK

Your project structure should look like this:

revi
backend

encore.app

package.json

dashboard

package.json

.env

sdk

package.json

dist/

Environment Configuration

Backend Environment Variables

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/revi
 
# API Settings
PORT=4000
NODE_ENV=development
 
# Optional: External integrations
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Dashboard Environment Variables

# Database (same as backend)
DATABASE_URL=postgresql://user:password@localhost:5432/revi
 
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_REVI_API_URL=http://localhost:4000
NEXT_PUBLIC_REVI_PROJECT_ID=1
 
# Authentication
BETTER_AUTH_SECRET=your-long-random-secret-key-here
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret

Development Workflow

Starting the Full Stack

# Terminal 1: Start the backend
cd backend && encore run
 
# Terminal 2: Start the dashboard
cd dashboard && npm run dev
 
# Terminal 3: Build/watch the SDK (if developing)
cd sdk && npm run build:watch

Database Management

Reset the database:

cd backend && encore db reset
cd dashboard && npx drizzle-kit push

View database contents:

cd backend && encore db shell

Building for Production

Backend:

cd backend && encore build

Dashboard:

cd dashboard && npm run build

SDK:

cd sdk && npm run build

Troubleshooting

Common Issues

Port conflicts:

  • Backend: Change port in encore.app or set PORT environment variable
  • Dashboard: Use npm run dev -- -p 3001 to use a different port

Database connection errors:

  • Ensure PostgreSQL is running
  • Check DATABASE_URL in both backend and dashboard .env files
  • Run database migrations: encore db migrate and npx drizzle-kit push

Authentication not working:

  • Verify Google OAuth credentials are correct
  • Ensure BETTER_AUTH_SECRET is set and matches between components
  • Check that callback URLs are configured in Google Console

SDK not capturing errors:

  • Verify the backend is running and accessible
  • Check browser network tab for API call errors
  • Ensure the API key is correct and the project exists

Getting Help

  • Documentation: Continue reading the guides in this documentation
  • GitHub Issues: Report bugs and request features
  • Discord Community: Join our developer community for real-time help

🎉 Congratulations! You now have a complete Revi installation running locally. Continue to the Quick Start Guide to integrate Revi into your first application.