302 lines
8.7 KiB
Plaintext
302 lines
8.7 KiB
Plaintext
---
|
|
title: "Self-Hosting Overview"
|
|
description: "Complete guide to self-hosting AgentOps backend services and infrastructure"
|
|
---
|
|
|
|
# Self-Hosting AgentOps
|
|
|
|
Welcome to the AgentOps self-hosting documentation. This section provides comprehensive guides for running AgentOps backend services and infrastructure on your own infrastructure.
|
|
|
|
## What is Self-Hosting?
|
|
|
|
Self-hosting AgentOps means running the entire AgentOps platform on your own servers or cloud infrastructure, giving you complete control over:
|
|
|
|
- **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
|
|
|
|
The AgentOps platform consists of several key components:
|
|
|
|
### 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
|
|
Perfect for local development and testing:
|
|
- **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
|
|
For production workloads:
|
|
- **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
|
|
Before you begin, ensure you have:
|
|
- 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
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
Visit http://localhost:3000 to access the dashboard!
|
|
|
|
## Documentation Sections
|
|
|
|
### [Backend Setup Guide](/v2/self-hosting/backend-setup)
|
|
Complete guide for setting up the AgentOps backend services, including:
|
|
- Prerequisites and system requirements
|
|
- Environment configuration
|
|
- External service setup
|
|
- Service verification and troubleshooting
|
|
|
|
### [Docker Guide](/v2/self-hosting/docker-guide)
|
|
Comprehensive Docker and Docker Compose documentation:
|
|
- Docker configuration and setup
|
|
- Container management commands
|
|
- Production Docker configurations
|
|
- Performance optimization and monitoring
|
|
|
|
### [Native Development Guide](/v2/self-hosting/native-development)
|
|
Guide for running services natively without Docker:
|
|
- Fastest development setup
|
|
- IDE configuration and debugging
|
|
- Performance optimization
|
|
- Advanced development workflows
|
|
|
|
### [Just Commands Reference](/v2/self-hosting/just-commands)
|
|
Complete reference for all available Just commands:
|
|
- Setup and installation commands
|
|
- Development workflow commands
|
|
- Testing and quality assurance
|
|
- Docker management utilities
|
|
|
|
## Choosing Your Setup
|
|
|
|
### For Active Development
|
|
**Recommended: Native Development**
|
|
- Fastest iteration cycles
|
|
- Direct debugging capabilities
|
|
- Lower resource usage
|
|
- Immediate file system access
|
|
|
|
```bash
|
|
just api-native # Start API natively
|
|
just fe-run # Start dashboard
|
|
```
|
|
|
|
### For Team Development
|
|
**Recommended: Docker Development**
|
|
- Consistent environment across team
|
|
- Isolated service dependencies
|
|
- Easy environment reset
|
|
- Production-like testing
|
|
|
|
```bash
|
|
just up # Start all services
|
|
just logs # Monitor services
|
|
```
|
|
|
|
### For Production
|
|
**Recommended: Docker with External Services**
|
|
- 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](https://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](https://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](/v2/self-hosting/backend-setup)** - 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
|
|
|
|
Ready to begin? Start with our [Backend Setup Guide](/v2/self-hosting/backend-setup)! |