​

Self-Hosting AgentOps

​

What is Self-Hosting?

• Data sovereignty - Your data stays on your infrastructure
• Customization - Modify the platform to fit your needs
• Security - Implement your own security policies
• Compliance - Meet specific regulatory requirements
• Cost control - Manage infrastructure costs directly

​

Architecture Overview

​

Core Services

• API Server - FastAPI backend handling authentication, data processing, and business logic
• Dashboard - Next.js frontend providing the user interface and visualization
• Database Layer - Supabase (PostgreSQL) for primary data and ClickHouse for analytics

​

Supporting Infrastructure

• OpenTelemetry Collector - Trace and metrics collection
• Authentication - Supabase Auth for user management
• File Storage - Supabase Storage for file handling
• Monitoring - Optional Sentry, PostHog integration

​

External Dependencies

• Supabase - Database and authentication services
• ClickHouse - Analytics database for traces and metrics
• Stripe (optional) - Payment processing for billing features

​

Deployment Options

​

1. Development Setup

• Native Development - Run services directly on your machine
• Docker Development - Use Docker Compose for isolated environment
• Hybrid Approach - Mix native and containerized services

​

2. Production Deployment

• Docker Compose - Simple single-server deployment
• Kubernetes - Scalable container orchestration
• Cloud Platforms - Deploy to AWS, GCP, Azure
• Serverless - Use cloud functions and managed services

​

Quick Start Guide

​

Prerequisites

• Modern operating system (Linux, macOS, or Windows with WSL)
• Docker and Docker Compose
• Node.js 18+ and Python 3.12+
• Access to external services (Supabase, ClickHouse)

​

5-Minute Setup

# 1. Clone the repository
git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app

# 2. Copy environment files
cp .env.example .env
cp api/.env.example api/.env
cp dashboard/.env.example dashboard/.env.local

# 3. Configure external services (see guides below)
# Edit .env files with your service credentials

# 4. Start with Docker
docker-compose up -d

# Or start natively for development
just api-native    # Terminal 1
just fe-run        # Terminal 2

​

Documentation Sections

​

Backend Setup Guide

• Prerequisites and system requirements
• Environment configuration
• External service setup
• Service verification and troubleshooting

​

Docker Guide

• Docker configuration and setup
• Container management commands
• Production Docker configurations
• Performance optimization and monitoring

​

Native Development Guide

• Fastest development setup
• IDE configuration and debugging
• Performance optimization
• Advanced development workflows

​

Just Commands Reference

• Setup and installation commands
• Development workflow commands
• Testing and quality assurance
• Docker management utilities

​

Choosing Your Setup

​

For Active Development

• Fastest iteration cycles
• Direct debugging capabilities
• Lower resource usage
• Immediate file system access

just api-native    # Start API natively
just fe-run        # Start dashboard

​

For Team Development

• Consistent environment across team
• Isolated service dependencies
• Easy environment reset
• Production-like testing

just up            # Start all services
just logs          # Monitor services

​

For Production

• Scalable and maintainable
• Health checks and restart policies
• Resource limits and monitoring
• Easy backup and recovery

​

External Services Setup

​

Required Services

​

Supabase (Database & Auth)

• Purpose: Primary PostgreSQL database and user authentication
• Setup: Create project at supabase.com
• Cost: Free tier available, pay-as-you-scale
• Alternatives: Self-hosted PostgreSQL + custom auth

​

ClickHouse (Analytics)

• Purpose: High-performance analytics database for traces and metrics
• Setup: ClickHouse Cloud or self-hosted
• Cost: Pay-per-usage or fixed instances
• Alternatives: PostgreSQL (with performance trade-offs)

​

Optional Services

​

Stripe (Billing)

• Purpose: Payment processing and subscription management
• Setup: Create account at stripe.com
• Required for: Billing features
• Alternatives: Remove billing features or custom payment solution

​

Monitoring & Analytics

• Sentry: Error tracking and performance monitoring
• PostHog: Product analytics and feature flags
• Setup: Optional but recommended for production

​

Security Considerations

​

Authentication & Authorization

• JWT tokens for API authentication
• Supabase Auth for user management
• Row-level security in PostgreSQL
• API key management for SDK access

​

Data Protection

• HTTPS/TLS encryption in transit
• Database encryption at rest
• Environment variable security
• Secret management best practices

​

Network Security

• Firewall configuration
• VPN or private networks
• API rate limiting
• CORS configuration

​

Monitoring & Observability

​

Application Monitoring

• Health check endpoints
• Application metrics and logs
• Error tracking with Sentry
• Performance monitoring

​

Infrastructure Monitoring

• Container resource usage
• Database performance
• Network connectivity
• Storage utilization

​

Alerting

• Service availability alerts
• Error rate monitoring
• Resource usage thresholds
• Custom business metrics

​

Scaling Considerations

​

Horizontal Scaling

• Multiple API server instances
• Load balancer configuration
• Database connection pooling
• Shared session storage

​

Vertical Scaling

• Resource allocation optimization
• Database performance tuning
• Caching strategies
• CDN for static assets

​

Database Scaling

• Read replicas for PostgreSQL
• ClickHouse cluster setup
• Connection pool management
• Query optimization

​

Backup & Recovery

​

Database Backups

• Automated Supabase backups
• ClickHouse data exports
• Point-in-time recovery
• Cross-region replication

​

Application Backups

• Configuration files
• Environment variables
• Custom modifications
• SSL certificates

​

Disaster Recovery

• Recovery time objectives (RTO)
• Recovery point objectives (RPO)
• Failover procedures
• Data integrity verification

​

Cost Optimization

​

Infrastructure Costs

• Right-size compute resources
• Use spot instances where appropriate
• Implement auto-scaling
• Monitor and optimize usage

​

Service Costs

• Optimize database queries
• Implement caching strategies
• Use appropriate service tiers
• Monitor third-party service usage

​

Getting Help

​

Documentation

• Follow the step-by-step guides
• Check troubleshooting sections
• Review configuration examples
• Understand architecture decisions

​

Community Support

• GitHub Issues for bug reports
• GitHub Discussions for questions
• Discord community for real-time help
• Stack Overflow for technical questions

​

Professional Support

• Enterprise support options
• Consulting services available
• Custom deployment assistance
• Training and onboarding

​

Next Steps

1. Start with the Backend Setup Guide - Get your environment running
2. Choose your deployment method - Docker or native development
3. Configure external services - Set up Supabase and ClickHouse
4. Customize for your needs - Modify configuration and features
5. Plan for production - Implement monitoring, backups, and scaling