Backend Setup Guide

This guide covers how to set up and run the AgentOps backend services from the /app directory. The backend includes the API server, dashboard, database services, and observability infrastructure.

Architecture Overview

The AgentOps backend consists of several interconnected services:

API Server (api/) - FastAPI backend with authentication, billing, and data processing
Dashboard (dashboard/) - Next.js frontend for visualization and management
Supabase - Authentication and primary PostgreSQL database
ClickHouse - Analytics database for traces and metrics
OpenTelemetry Collector - Observability and trace collection
Redis (optional) - Caching and session storage

Prerequisites

Before setting up the backend, ensure you have the following installed:

Required Software

Node.js 18+ (Download)
Python 3.12+ (Download)
Docker & Docker Compose (Download)
Bun (recommended) or npm (Install Bun)
uv (recommended for Python) (Install uv)
Just (optional, for convenience commands) (Install Just)

External Services

You’ll need accounts and setup for these external services:

Supabase - Database and authentication (supabase.com)
ClickHouse Cloud - Analytics database (clickhouse.com/cloud)
Stripe (optional) - Payment processing (stripe.com)

Quick Start

1. Clone and Navigate

git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app

2. Environment Setup

Copy and configure environment files:

# Root environment (for Docker Compose)
cp .env.example .env

# API environment
cp api/.env.example api/.env

# Dashboard environment  
cp dashboard/.env.example dashboard/.env.local

3. Install Dependencies

# Using Just (recommended)
just install

# Or manually:
bun install                              # Root dependencies
uv pip install -r requirements-dev.txt  # Python dev tools
cd api && uv pip install -e . && cd ..  # API dependencies
cd dashboard && bun install && cd ..    # Dashboard dependencies

4. Configure External Services

Update your .env files with your service credentials. See External Services Configuration below.

5. Start Services

# Option 1: Using Docker Compose (recommended)
docker-compose up -d

# Option 2: Using Just commands
just api-run    # Start API server
just fe-run     # Start dashboard (in another terminal)

# Option 3: Native development
cd api && uv run python run.py          # API server
cd dashboard && bun dev                  # Dashboard (in another terminal)

6. Verify Setup

Dashboard: http://localhost:3000
API Documentation: http://localhost:8000/redoc
API Health Check: http://localhost:8000/health

External Services Configuration

Supabase Setup

Create a new project at supabase.com
Go to Settings → API to get your keys
Run the database migrations:
cd supabase npx supabase db push

Update your .env files with:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_PROJECT_ID=your-project-id

ClickHouse Setup

Sign up for ClickHouse Cloud or self-host
Create a database and get connection details

Run the ClickHouse migrations:

# Apply schema from clickhouse/schema_dump.sql

Update your .env files with:

CLICKHOUSE_HOST=your-host.clickhouse.cloud
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_DATABASE=your-database
CLICKHOUSE_SECURE=true

Stripe Setup (Optional)

For billing functionality:

Create a Stripe account
Get your API keys from the dashboard

Update your .env files with:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Additional Services (Optional)

Sentry: Error monitoring

SENTRY_DSN=https://your-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=development

PostHog: Analytics

NEXT_PUBLIC_POSTHOG_KEY=phc_your-key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

Development Workflow

Using Just Commands (Recommended)

The justfile provides convenient commands for development:

# Setup and installation
just setup              # Complete development setup
just install             # Install all dependencies

# API Development
just api-native          # Run API natively (fastest)
just api-build           # Build API Docker image
just api-run             # Run API in Docker
just api-test            # Run API tests

# Frontend Development  
just fe-run              # Run dashboard development server
just fe-build            # Build dashboard for production
just fe-test             # Run frontend tests

# Code Quality
just lint                # Run all linting checks
just format              # Format all code
just test                # Run all tests

# Docker Management
just up                  # Start all services
just down                # Stop all services
just logs                # View service logs
just clean               # Clean up Docker resources

Manual Development

If you prefer running services manually:

# Start API server
cd api && uv run python run.py

# Start dashboard (in another terminal)
cd dashboard && bun dev

# Start landing page (in another terminal)  
cd landing && bun dev

Service Configuration

API Server Configuration

Key environment variables for the API server (api/.env):

# Database connections
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host

# Application settings
APP_URL=http://localhost:3000
LOGGING_LEVEL=INFO
JWT_SECRET_KEY=your-jwt-secret

# External integrations
SENTRY_DSN=your-sentry-dsn

Dashboard Configuration

Key environment variables for the dashboard (dashboard/.env.local):

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Features
NEXT_PUBLIC_ENVIRONMENT_TYPE=development
NEXT_PUBLIC_PLAYGROUND=true

Troubleshooting

Common Issues

Port conflicts:

# Check what's running on ports 3000 and 8000
lsof -i :3000
lsof -i :8000

Database connection issues:

Verify your Supabase and ClickHouse credentials
Check network connectivity to external services
Ensure database migrations have been applied

Docker issues:

# Reset Docker environment
just clean
docker system prune -f
just up

Dependency issues:

# Clean and reinstall
rm -rf node_modules api/.venv dashboard/node_modules
just install

Logs and Debugging

# View service logs
just logs

# View specific service logs
docker-compose logs api
docker-compose logs dashboard

# Run with debug logging
LOGGING_LEVEL=DEBUG just api-run

Next Steps

Once your backend is running:

Create an account at http://localhost:3000
Generate an API key in the dashboard
Install the AgentOps SDK and start tracking your AI agents
Explore the dashboard to view traces and analytics

For production deployment, see our Deployment Guide.

Getting Started

Concepts

Integrations

Usage

Self-Hosting

Other Info

Backend Setup Guide

Backend Setup Guide

Architecture Overview

Prerequisites

Required Software

External Services

Quick Start

1. Clone and Navigate

2. Environment Setup

3. Install Dependencies

4. Configure External Services

5. Start Services

6. Verify Setup

External Services Configuration

Supabase Setup

ClickHouse Setup

Stripe Setup (Optional)

Additional Services (Optional)

Development Workflow

Using Just Commands (Recommended)

Manual Development

Service Configuration

API Server Configuration

Dashboard Configuration

Troubleshooting

Common Issues

Logs and Debugging

Next Steps

​Backend Setup Guide

​Architecture Overview

​Prerequisites

​Required Software

​External Services

​Quick Start

​1. Clone and Navigate

​2. Environment Setup

​3. Install Dependencies

​4. Configure External Services

​5. Start Services

​6. Verify Setup

​External Services Configuration

​Supabase Setup

​ClickHouse Setup

​Stripe Setup (Optional)

​Additional Services (Optional)

​Development Workflow

​Using Just Commands (Recommended)

​Manual Development

​Service Configuration

​API Server Configuration

​Dashboard Configuration

​Troubleshooting

​Common Issues

​Logs and Debugging

​Next Steps

Backend Setup Guide

Architecture Overview

Prerequisites

Required Software

External Services

Quick Start

1. Clone and Navigate

2. Environment Setup

3. Install Dependencies

4. Configure External Services

5. Start Services

6. Verify Setup

External Services Configuration

Supabase Setup

ClickHouse Setup

Stripe Setup (Optional)

Additional Services (Optional)

Development Workflow

Using Just Commands (Recommended)

Manual Development

Service Configuration

API Server Configuration

Dashboard Configuration

Troubleshooting

Common Issues

Logs and Debugging

Next Steps