Codakey
Play
← Back to openreplay

How to Deploy & Use openreplay

OpenReplay Deployment and Usage Guide

1. Prerequisites

Before deploying OpenReplay, ensure you have:

Runtime & Tools:

  • Node.js 18+ and npm/yarn/pnpm (for building and running the TypeScript-based project)
  • Docker and Docker Compose (for containerized deployment)
  • Git (for cloning the repository)
  • A modern web browser (Chrome recommended for Spot extension)

Infrastructure Requirements:

  • A server/VM with minimum 4GB RAM (8GB+ recommended for production)
  • 50GB+ of storage (for session data)
  • Public IP address or domain with SSL certificate
  • One of the supported cloud providers: AWS, Google Cloud, Azure, DigitalOcean, Scaleway, OVHcloud, or Kubernetes cluster

Accounts:

  • Cloud provider account (if deploying to AWS, GCP, Azure, etc.)
  • Domain registrar (for custom domain setup)

2. Installation

Clone the repository and set up the project:

# Clone the OpenReplay repository
git clone https://github.com/openreplay/openreplay.git
cd openreplay

# Install dependencies (using pnpm as preferred package manager)
pnpm install

# For specific component installation:
cd tracker  # Tracker library
pnpm install

cd ../frontend  # Web dashboard
pnpm install

cd ../backend  # API services
pnpm install

Spot Chrome Extension Installation:

  1. Open Chrome and navigate to chrome://extensions/
  2. Enable "Developer mode"
  3. Load unpacked extension from openreplay/spot/ directory
  4. The extension will be available in your Chrome toolbar

3. Configuration

OpenReplay uses environment variables for configuration. Create a .env file in the root directory:

# Required: Database configuration
POSTGRES_DB=openreplay
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Required: Redis configuration
REDIS_HOST=redis
REDIS_PORT=6379

# Required: Application URLs
ASSIST_URL=http://localhost:4445
API_URL=http://localhost:4446
INGESTOR_URL=http://localhost:4444
FRONTEND_URL=http://localhost:3000

# Optional: SSL configuration (for production)
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

# Optional: Email configuration (for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password

# Optional: Cloud storage for recordings
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
S3_BUCKET=openreplay-recordings

Tracker Configuration: In your web application, configure the tracker:

import Tracker from '@openreplay/tracker';
import trackerAssist from '@openreplay/tracker-assist';
import trackerRedux from '@openreplay/tracker-redux';

const tracker = new Tracker({
  projectKey: 'YOUR_PROJECT_KEY',
  ingestPoint: 'https://your-domain.com/ingest', // Your OpenReplay ingest URL
  defaultInputMode: 0, // 0: plain, 1: obscure, 2: hidden
  obscureTextNumbers: false,
  obscureTextEmails: true,
  network: {
    capturePayload: true,
    sessionTokenHeader: false,
  },
});

// Add plugins
tracker.use(trackerAssist({
  onAgentConnect: (agentInfo) => {
    console.log('Agent connected:', agentInfo);
  },
  onCallStart: (agentInfo) => {
    console.log('Call started with:', agentInfo);
  },
  session_calling_peer_key: 'your_peer_key',
  serverURL: 'https://your-domain.com',
}));

tracker.use(trackerRedux());

tracker.start();

4. Build & Run

Development Mode:

# Start all services in development mode
docker-compose -f docker-compose.dev.yml up

# Or run services individually:
cd frontend && pnpm dev  # Frontend dashboard on http://localhost:3000
cd backend && pnpm dev   # API server on http://localhost:4446

Production Build:

# Build all components
pnpm build

# Build individual components
cd tracker && pnpm build
cd ../frontend && pnpm build
cd ../backend && pnpm build

# Start production services
docker-compose up -d

Using Docker Compose:

# Pull latest images
docker-compose pull

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

5. Deployment

OpenReplay can be deployed on multiple platforms:

Kubernetes (Recommended for production):

# Apply Kubernetes manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/postgres.yaml
kubectl apply -f k8s/redis.yaml
kubectl apply -f k8s/openreplay.yaml

# Set up ingress with SSL
kubectl apply -f k8s/ingress.yaml

AWS EC2 Deployment:

  1. Launch an EC2 instance (t3.medium or larger)
  2. Install Docker and Docker Compose
  3. Clone repository and configure .env
  4. Run: docker-compose -f docker-compose.aws.yml up -d

DigitalOcean One-Click App:

  1. Use the DigitalOcean Marketplace
  2. Select droplet size (8GB RAM minimum)
  3. Configure domain and SSL

Manual Server Deployment:

# On your server
git clone https://github.com/openreplay/openreplay.git
cd openreplay

# Configure environment
cp .env.example .env
nano .env  # Edit with your configuration

# Start with Docker Compose
docker-compose up -d

# Set up reverse proxy (Nginx example)
sudo apt install nginx
sudo cp nginx/openreplay.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/openreplay.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Required Ports:

  • 3000 - Frontend dashboard
  • 4444 - Ingest service (session data)
  • 4445 - Assist service (cobrowsing)
  • 4446 - API service
  • 5432 - PostgreSQL database
  • 6379 - Redis

6. Troubleshooting

Common Issues and Solutions:

  1. "Tracker not sending data"

    • Verify ingest URL is accessible: curl https://your-domain.com/ingest
    • Check browser console for tracker errors
    • Ensure CORS is properly configured on your ingest server

  2. "Database connection failed"

    # Check PostgreSQL is running
docker-compose ps postgres

# View database logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres psql -U postgres -d openreplay

  3. "Low disk space"

    • Sessions are stored in PostgreSQL and S3
    • Clean old sessions: DELETE FROM sessions WHERE created_at < NOW() - INTERVAL '30 days';
    • Configure S3 lifecycle policies for automatic cleanup

  4. "Assist/cobrowsing not working"

    • Ensure WebSocket connections are allowed (ports 4444-4446)
    • Check STUN/TURN server configuration for NAT traversal
    • Verify SSL certificates are valid and trusted

  5. "High memory usage"

    • Increase Redis memory limit in configuration
    • Add more workers for ingest service
    • Monitor with: docker stats

  6. "Spot extension not recording"

    • Check extension permissions in Chrome
    • Verify the tab is not in incognito mode
    • Ensure network tracking is enabled in extension settings
    • Check console for errors: chrome://extensions/ → "Inspect views background page"

  7. "Build failures"

    # Clear node_modules and rebuild
rm -rf node_modules
pnpm install
pnpm build

# Check TypeScript errors
pnpm type-check

  8. "Performance issues"

    • Enable gzip compression in Nginx/Apache
    • Configure CDN for static assets
    • Optimize PostgreSQL with appropriate indexes
    • Use Redis caching for frequent queries

Getting Help:

← Project overviewView alternatives to openreplay →