Self-Hosting Installation

Overview

OpenSight can be self-hosted on your own infrastructure, giving you complete control over your brand monitoring data. This guide covers deployment using Docker Compose for a production-ready setup.

Self-hosting requires basic familiarity with Docker, environment variables, and server administration.

Prerequisites

Before you begin, ensure you have the following installed:

Docker 20.10 or higher
Docker Compose 2.0 or higher
Git for cloning the repository
Node.js 20+ (for local development only)
2GB+ RAM recommended for production
10GB+ disk space for database and logs

For production deployments, we recommend at least 4GB RAM and 20GB disk space.

Quick Start with Docker

Get OpenSight running in under 5 minutes with Docker Compose.

Clone the repository

git clone https://github.com/shuvamk/opensight.git
cd opensight

Configure environment variables

Copy the example environment file and update with your settings:

cp .env.example .env

Edit .env with your preferred text editor. See Environment Variables for details.

Start the full stack

docker compose -f docker/docker-compose.yml up -d

This command starts:

Web UI on port 3000
API server on port 4000
PostgreSQL database on port 5432
Redis cache on port 6379

Access OpenSight

Open your browser and navigate to:

Web UI: http://localhost:3000
API: http://localhost:4000
API Documentation: http://localhost:4000/api/docs

Initial startup may take 1-2 minutes while the database initializes.

Docker Compose Configuration

OpenSight uses Docker Compose to orchestrate multiple services. Here’s the complete configuration:

docker/docker-compose.yml

version: '3.8'

services:
  web:
    build:
      context: ..
      dockerfile: docker/Dockerfile.web
    ports:
      - "3000:3000"
    env_file: ../.env
    environment:
      - NODE_ENV=production
    depends_on:
      - api
    restart: unless-stopped

  api:
    build:
      context: ..
      dockerfile: docker/Dockerfile.api
    ports:
      - "4000:4000"
    env_file: ../.env
    environment:
      - NODE_ENV=production
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: opensight
      POSTGRES_PASSWORD: opensight
      POSTGRES_DB: opensight
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U opensight"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:
  redisdata:

Environment Variables

Configure OpenSight by setting these environment variables in your .env file.

Database Configuration

# PostgreSQL connection string
DATABASE_URL=postgresql://opensight:opensight@postgres:5432/opensight

Change the default password in production deployments!

Redis Configuration

# Redis connection for caching
UPSTASH_REDIS_REST_URL=https://your-upstash-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

# Or use local Redis (for Docker deployments)
# REDIS_URL=redis://redis:6379

Authentication

# JWT secrets for authentication
JWT_SECRET=generate-a-64-char-random-string
JWT_REFRESH_SECRET=generate-another-64-char-random-string

# OAuth providers (optional)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Generate secure random strings for JWT secrets:

openssl rand -hex 32

AI Engine APIs

These API keys enable OpenSight to query AI engines:

# Required for AI monitoring
OPENAI_API_KEY=sk-...
PERPLEXITY_API_KEY=pplx-...
SERPER_API_KEY=...

You need at least one AI engine API key for OpenSight to function. Get API keys from:

Email Configuration

# Resend for transactional emails
RESEND_API_KEY=re_...
EMAIL_FROM=[email protected]

Payment Processing (Optional)

# Stripe for subscription billing
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_STARTER_PRICE_ID=price_...
STRIPE_GROWTH_PRICE_ID=price_...

File Upload (Optional)

# UploadThing for file uploads
UPLOADTHING_SECRET=sk_live_...
UPLOADTHING_APP_ID=...

Application URLs

# Frontend and API URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:4000
FRONTEND_URL=http://localhost:3000
API_PORT=4000

# Environment
NODE_ENV=production

Feature Flags

# Enable/disable features
ENABLE_CONTENT_SCORING=true
ENABLE_WEBHOOKS=true

Error Tracking (Optional)

# Sentry for error monitoring
SENTRY_DSN=https://[email protected]/...
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/...

Local Development Setup

For local development without Docker, follow these steps.

Install dependencies

npm install

OpenSight uses pnpm workspaces. If you prefer pnpm:

pnpm install

Start development services

Start PostgreSQL and Redis in Docker:

docker compose -f docker/docker-compose.dev.yml up -d

This starts only the database and cache, not the application.

Initialize the database

npm run db:generate  # Generate Drizzle schema
npm run db:migrate   # Run migrations
npm run db:seed      # Seed with sample data (optional)

Or run all at once:

npm run db:setup

Start development servers

npm run dev

This starts:

Web UI at http://localhost:3000
API server at http://localhost:4000

To start services individually:

npm run dev:web      # Web UI only
npm run dev:api      # API server only

Database Management

OpenSight uses Drizzle ORM for database management.

Generate Schema

npm run db:generate

Generates TypeScript types from your database schema.

Run Migrations

npm run db:migrate

Applies pending migrations to your database.

Seed Database

npm run db:seed

Populates the database with sample data for development.

Production Deployment

Build for Production

# Build all services
npm run build

# Or build individually
npm run build:web
npm run build:api

Start Production Services

# Using Docker Compose (recommended)
docker compose -f docker/docker-compose.yml up -d

# Or using npm scripts
npm run start:web
npm run start:api

Health Checks

Verify services are running:

# Check API health
curl http://localhost:4000/health

# Check PostgreSQL
docker compose -f docker/docker-compose.yml exec postgres pg_isready -U opensight

# Check Redis
docker compose -f docker/docker-compose.yml exec redis redis-cli ping

View Logs

# All services
docker compose -f docker/docker-compose.yml logs -f

# Specific service
docker compose -f docker/docker-compose.yml logs -f api
docker compose -f docker/docker-compose.yml logs -f web

Monitoring & Maintenance

Database Backups

Create automated backups of your PostgreSQL database:

# Manual backup
docker compose -f docker/docker-compose.yml exec postgres pg_dump -U opensight opensight > backup.sql

# Restore from backup
cat backup.sql | docker compose -f docker/docker-compose.yml exec -T postgres psql -U opensight opensight

Set up automated backups for production deployments. Consider using managed database services for critical data.

Redis Cache

Clear the Redis cache if needed:

docker compose -f docker/docker-compose.yml exec redis redis-cli FLUSHALL

Update OpenSight

To update to the latest version:

git pull origin main
npm install
npm run build
docker compose -f docker/docker-compose.yml up -d --build

Troubleshooting

Services fail to start

Check Docker logs for errors:

docker compose -f docker/docker-compose.yml logs

Common issues:

Ports already in use (3000, 4000, 5432, 6379)
Insufficient disk space
Missing environment variables

Database connection errors

Verify PostgreSQL is running and accessible:

docker compose -f docker/docker-compose.yml ps postgres

Check the DATABASE_URL in your .env file matches the Docker service name.

API requests failing

Common causes:

Missing AI engine API keys
Incorrect NEXT_PUBLIC_API_URL in frontend
CORS configuration issues

Check API logs:

docker compose -f docker/docker-compose.yml logs -f api

Out of memory errors

OpenSight requires at least 2GB RAM. If running on a constrained system:

Increase Docker memory limits
Reduce concurrent analysis jobs
Use external managed services for PostgreSQL/Redis

Security Considerations

Follow these security best practices for production deployments:

Change default passwords for PostgreSQL
Use strong JWT secrets (64+ characters)
Enable HTTPS with a reverse proxy (nginx, Caddy)
Restrict database access to application containers only
Keep dependencies updated with npm audit
Set up firewall rules to limit exposed ports
Enable Redis authentication for production
Rotate API keys regularly
Use environment-specific .env files (never commit secrets)

Scaling Considerations

For high-traffic deployments:

Use managed PostgreSQL (AWS RDS, Railway, Supabase)
Use managed Redis (Upstash, Redis Cloud)
Deploy multiple API instances behind a load balancer
Enable CDN for static assets
Consider horizontal scaling with Kubernetes

Next Steps

Environment Variables

Complete reference for all configuration options.

Docker Guide

Advanced Docker deployment patterns.

API Reference

Integrate OpenSight into your workflows.

Platform Features

Explore plan tiers and features.

Need Help?

If you encounter issues during installation:

Check GitHub Issues
Review Docker documentation
Join our community discussions

Get Started

Core Features

Deployment

Platform

​Overview

​Prerequisites

​Quick Start with Docker

​Docker Compose Configuration

​Environment Variables

​Database Configuration

​Redis Configuration

​Authentication

​AI Engine APIs

​Email Configuration

​Payment Processing (Optional)

​File Upload (Optional)

​Application URLs

​Feature Flags

​Error Tracking (Optional)

​Local Development Setup

​Database Management

​Generate Schema

​Run Migrations

​Seed Database

​Production Deployment

​Build for Production

​Start Production Services

​Health Checks

​View Logs

​Monitoring & Maintenance

​Database Backups

​Redis Cache

​Update OpenSight

​Troubleshooting

​Security Considerations

​Scaling Considerations

​Next Steps

Environment Variables

Docker Guide

API Reference

Platform Features

​Need Help?

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Start with Docker

Docker Compose Configuration

Environment Variables

Database Configuration

Redis Configuration

Authentication

AI Engine APIs

Email Configuration

Payment Processing (Optional)

File Upload (Optional)

Application URLs

Feature Flags

Error Tracking (Optional)

Local Development Setup

Database Management

Generate Schema

Run Migrations

Seed Database

Production Deployment

Build for Production

Start Production Services

Health Checks

View Logs

Monitoring & Maintenance

Database Backups

Redis Cache

Update OpenSight

Troubleshooting

Security Considerations

Scaling Considerations

Next Steps

Need Help?