diff --git a/docs/mint.json b/docs/mint.json index c995598b9..3af5008ae 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -179,6 +179,17 @@ ], "version": "v2" }, + { + "group": "Self-Hosting", + "pages": [ + "v2/self-hosting/overview", + "v2/self-hosting/backend-setup", + "v2/self-hosting/docker-guide", + "v2/self-hosting/native-development", + "v2/self-hosting/just-commands" + ], + "version": "v2" + }, { "group": "Other Info", "pages": [ diff --git a/docs/v2/self-hosting/backend-setup.mdx b/docs/v2/self-hosting/backend-setup.mdx new file mode 100644 index 000000000..b4586a593 --- /dev/null +++ b/docs/v2/self-hosting/backend-setup.mdx @@ -0,0 +1,294 @@ +--- +title: "Backend Setup Guide" +description: "Complete guide for setting up and running AgentOps backend services" +--- + +# 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](https://nodejs.org/)) +- **Python** 3.12+ ([Download](https://www.python.org/downloads/)) +- **Docker & Docker Compose** ([Download](https://www.docker.com/get-started)) +- **Bun** (recommended) or npm ([Install Bun](https://bun.sh/)) +- **uv** (recommended for Python) ([Install uv](https://github.com/astral-sh/uv)) +- **Just** (optional, for convenience commands) ([Install Just](https://github.com/casey/just)) + +### External Services +You'll need accounts and setup for these external services: + +- **Supabase** - Database and authentication ([supabase.com](https://supabase.com)) +- **ClickHouse Cloud** - Analytics database ([clickhouse.com/cloud](https://clickhouse.com/cloud)) +- **Stripe** (optional) - Payment processing ([stripe.com](https://stripe.com)) + +## Quick Start + +### 1. Clone and Navigate +```bash +git clone https://github.com/AgentOps-AI/AgentOps.Next.git +cd AgentOps.Next/app +``` + +### 2. Environment Setup +Copy and configure environment files: + +```bash +# 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 +```bash +# 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](#external-services-configuration) below. + +### 5. Start Services +```bash +# 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 +1. Create a new project at [supabase.com](https://supabase.com) +2. Go to Settings → API to get your keys +3. Run the database migrations: + ```bash + cd supabase + npx supabase db push + ``` +4. Update your `.env` files with: + ```env + 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 +1. Sign up for [ClickHouse Cloud](https://clickhouse.com/cloud) or self-host +2. Create a database and get connection details +3. Run the ClickHouse migrations: + ```bash + # Apply schema from clickhouse/schema_dump.sql + ``` +4. Update your `.env` files with: + ```env + 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: +1. Create a [Stripe](https://stripe.com) account +2. Get your API keys from the dashboard +3. Update your `.env` files with: + ```env + NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... + STRIPE_SECRET_KEY=sk_test_... + STRIPE_WEBHOOK_SECRET=whsec_... + ``` + +### Additional Services (Optional) +- **Sentry**: Error monitoring + ```env + SENTRY_DSN=https://your-dsn@sentry.io/project-id + SENTRY_ENVIRONMENT=development + ``` +- **PostHog**: Analytics + ```env + 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: + +```bash +# 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: + +```bash +# 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`): + +```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`): + +```env +# 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:** +```bash +# 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:** +```bash +# Reset Docker environment +just clean +docker system prune -f +just up +``` + +**Dependency issues:** +```bash +# Clean and reinstall +rm -rf node_modules api/.venv dashboard/node_modules +just install +``` + +### Logs and Debugging + +```bash +# 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: + +1. **Create an account** at http://localhost:3000 +2. **Generate an API key** in the dashboard +3. **Install the AgentOps SDK** and start tracking your AI agents +4. **Explore the dashboard** to view traces and analytics + +For production deployment, see our [Deployment Guide](/v2/self-hosting/deployment). \ No newline at end of file diff --git a/docs/v2/self-hosting/docker-guide.mdx b/docs/v2/self-hosting/docker-guide.mdx new file mode 100644 index 000000000..e0045e96a --- /dev/null +++ b/docs/v2/self-hosting/docker-guide.mdx @@ -0,0 +1,427 @@ +--- +title: "Docker Guide" +description: "Complete guide for running AgentOps with Docker and Docker Compose" +--- + +# Docker Guide + +This guide covers how to run AgentOps backend services using Docker and Docker Compose. This is the recommended approach for both development and production deployments. + +## Overview + +The AgentOps Docker setup includes: + +- **API Server** - FastAPI backend service +- **Dashboard** - Next.js frontend application +- **OpenTelemetry Collector** - Observability and trace collection +- **External Services** - Supabase, ClickHouse (configured separately) + +## Docker Compose Configuration + +The main `compose.yaml` file in the `/app` directory defines the service architecture: + +```yaml +services: + api: + build: + context: ./api + dockerfile: Dockerfile + ports: + - '8000:8000' + environment: + # Database connections + SUPABASE_URL: ${NEXT_PUBLIC_SUPABASE_URL} + SUPABASE_KEY: ${SUPABASE_SERVICE_ROLE_KEY} + CLICKHOUSE_HOST: ${CLICKHOUSE_HOST} + # ... other environment variables + network_mode: 'host' + volumes: + - ./api:/app/api + + dashboard: + profiles: ['dashboard'] + build: + context: ./dashboard + dockerfile: Dockerfile + ports: + - '3000:3000' + environment: + # Frontend configuration + NEXT_PUBLIC_SUPABASE_URL: ${NEXT_PUBLIC_SUPABASE_URL} + NEXT_PUBLIC_SUPABASE_ANON_KEY: ${NEXT_PUBLIC_SUPABASE_ANON_KEY} + # ... other environment variables + network_mode: 'host' + depends_on: + - api + volumes: + - ./dashboard:/app/ +``` + +## Quick Start with Docker + +### 1. Prerequisites +- Docker Engine 20.10+ +- Docker Compose 2.0+ +- Git + +### 2. Clone and Setup +```bash +git clone https://github.com/AgentOps-AI/AgentOps.Next.git +cd AgentOps.Next/app + +# Copy environment files +cp .env.example .env +cp api/.env.example api/.env +cp dashboard/.env.example dashboard/.env.local +``` + +### 3. Configure Environment Variables +Update your `.env` files with your external service credentials: + +```env +# .env (root) +NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co +SUPABASE_SERVICE_ROLE_KEY=your-service-role-key +CLICKHOUSE_HOST=your-clickhouse-host +CLICKHOUSE_PASSWORD=your-password +# ... other variables +``` + +### 4. Start Services +```bash +# Start all services +docker-compose up -d + +# Or start with dashboard profile +docker-compose --profile dashboard up -d + +# View logs +docker-compose logs -f +``` + +### 5. Verify Services +- **API Health**: http://localhost:8000/health +- **API Docs**: http://localhost:8000/redoc +- **Dashboard**: http://localhost:3000 + +## Docker Commands Reference + +### Basic Operations + +```bash +# Start all services in detached mode +docker-compose up -d + +# Start services with dashboard +docker-compose --profile dashboard up -d + +# Stop all services +docker-compose down + +# Stop and remove volumes +docker-compose down -v + +# View service status +docker-compose ps + +# View logs for all services +docker-compose logs -f + +# View logs for specific service +docker-compose logs -f api +docker-compose logs -f dashboard +``` + +### Development Commands + +```bash +# Rebuild services after code changes +docker-compose build + +# Rebuild specific service +docker-compose build api +docker-compose build dashboard + +# Force recreate containers +docker-compose up -d --force-recreate + +# Scale services (if needed) +docker-compose up -d --scale api=2 +``` + +### Debugging Commands + +```bash +# Execute commands in running containers +docker-compose exec api bash +docker-compose exec dashboard sh + +# View container resource usage +docker stats + +# Inspect service configuration +docker-compose config + +# View service networks +docker network ls +docker network inspect app_default +``` + +## Using Just Commands + +The project includes a `justfile` with convenient Docker commands: + +```bash +# Start all services +just up + +# Stop all services +just down + +# View logs +just logs + +# Clean up Docker resources +just clean + +# Build and run API +just api-build +just api-run +``` + +## Service-Specific Configuration + +### API Service + +The API service runs a FastAPI application with the following configuration: + +**Dockerfile highlights:** +```dockerfile +FROM python:3.12-slim +WORKDIR /app +COPY requirements.txt . +RUN pip install -r requirements.txt +COPY . . +EXPOSE 8000 +CMD ["python", "run.py"] +``` + +**Key environment variables:** +- `SUPABASE_URL`, `SUPABASE_KEY` - Database connection +- `CLICKHOUSE_HOST`, `CLICKHOUSE_PASSWORD` - Analytics database +- `LOGGING_LEVEL` - Log verbosity (DEBUG, INFO, WARNING, ERROR) +- `SENTRY_DSN` - Error tracking + +### Dashboard Service + +The Dashboard service runs a Next.js application: + +**Dockerfile highlights:** +```dockerfile +FROM node:18-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY . . +RUN npm run build +EXPOSE 3000 +CMD ["npm", "start"] +``` + +**Key environment variables:** +- `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` - Frontend auth +- `NEXT_PUBLIC_APP_URL` - API server URL +- `NEXT_PUBLIC_ENVIRONMENT_TYPE` - Environment (development/production) + +## OpenTelemetry Collector + +The OpenTelemetry Collector is included via a separate compose file: + +```yaml +# opentelemetry-collector/compose.yaml +services: + otel-collector: + image: otel/opentelemetry-collector-contrib:latest + command: ["--config=/etc/otel-collector-config.yaml"] + volumes: + - ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml + ports: + - "4317:4317" # OTLP gRPC receiver + - "4318:4318" # OTLP HTTP receiver + - "8889:8889" # Prometheus metrics +``` + +## Production Configuration + +### Environment Variables for Production + +```env +# Security +DEBUG=false +LOGGING_LEVEL=WARNING +JWT_SECRET_KEY=your-secure-jwt-secret + +# URLs +PROTOCOL=https +API_DOMAIN=api.yourdomain.com +APP_DOMAIN=yourdomain.com + +# Database +CLICKHOUSE_SECURE=true +SUPABASE_URL=https://your-prod-project.supabase.co + +# Monitoring +SENTRY_ENVIRONMENT=production +NEXT_PUBLIC_ENVIRONMENT_TYPE=production +``` + +### Production Docker Compose + +For production, you may want to: + +1. **Use specific image tags** instead of building locally +2. **Configure resource limits** +3. **Set up health checks** +4. **Use external networks** + +Example production overrides (`compose.prod.yaml`): + +```yaml +services: + api: + image: agentops/api:v1.0.0 + deploy: + resources: + limits: + cpus: '1.0' + memory: 1G + reservations: + cpus: '0.5' + memory: 512M + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8000/health"] + interval: 30s + timeout: 10s + retries: 3 + restart: unless-stopped + + dashboard: + image: agentops/dashboard:v1.0.0 + deploy: + resources: + limits: + cpus: '0.5' + memory: 512M + restart: unless-stopped +``` + +Run with production config: +```bash +docker-compose -f compose.yaml -f compose.prod.yaml up -d +``` + +## Troubleshooting + +### Common Issues + +**Services won't start:** +```bash +# Check logs for errors +docker-compose logs api +docker-compose logs dashboard + +# Verify environment variables +docker-compose config +``` + +**Port conflicts:** +```bash +# Check what's using ports +lsof -i :3000 +lsof -i :8000 + +# Use different ports +docker-compose up -d -p 3001:3000 -p 8001:8000 +``` + +**Database connection issues:** +- Verify external service credentials in `.env` files +- Check network connectivity from containers +- Ensure services are accessible from Docker network + +**Build failures:** +```bash +# Clean build cache +docker system prune -f +docker-compose build --no-cache + +# Check Dockerfile syntax +docker-compose config +``` + +### Performance Optimization + +**Resource monitoring:** +```bash +# Monitor container resources +docker stats + +# View container processes +docker-compose exec api top +``` + +**Volume optimization:** +```bash +# Use named volumes for better performance +volumes: + - api_data:/app/data + - dashboard_cache:/app/.next +``` + +**Network optimization:** +```bash +# Create custom network for better isolation +networks: + agentops: + driver: bridge +``` + +## Maintenance + +### Regular Maintenance Tasks + +```bash +# Update images +docker-compose pull +docker-compose up -d + +# Clean up unused resources +docker system prune -f + +# Backup volumes +docker run --rm -v app_api_data:/data -v $(pwd):/backup alpine tar czf /backup/api_data.tar.gz -C /data . + +# View disk usage +docker system df +``` + +### Monitoring + +```bash +# Service health checks +curl http://localhost:8000/health +curl http://localhost:3000/api/health + +# Container logs +docker-compose logs --tail=100 -f api + +# Resource usage +docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" +``` + +## Next Steps + +- Set up [monitoring and observability](/v2/self-hosting/monitoring) +- Configure [production deployment](/v2/self-hosting/deployment) +- Set up [backup and recovery](/v2/self-hosting/backup) +- Configure [SSL/TLS certificates](/v2/self-hosting/ssl) \ No newline at end of file diff --git a/docs/v2/self-hosting/just-commands.mdx b/docs/v2/self-hosting/just-commands.mdx new file mode 100644 index 000000000..34e77470e --- /dev/null +++ b/docs/v2/self-hosting/just-commands.mdx @@ -0,0 +1,467 @@ +--- +title: "Just Commands Reference" +description: "Complete reference for all available Just commands in AgentOps development" +--- + +# Just Commands Reference + +[Just](https://github.com/casey/just) is a command runner that provides convenient shortcuts for common development tasks. The AgentOps project includes a comprehensive `justfile` with commands for setup, development, testing, and deployment. + +## Installation + +First, install Just if you haven't already: + +```bash +# macOS +brew install just + +# Linux (using cargo) +cargo install just + +# Or download from GitHub releases +curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin +``` + +## Quick Reference + +View all available commands: +```bash +just +# or +just --list +``` + +## Setup Commands + +### `just setup` +Complete development environment setup - runs the full initialization process. + +```bash +just setup +``` + +**What it does:** +- Copies environment files (`.env.example` → `.env`, etc.) +- Installs all dependencies (root, API, dashboard) +- Sets up development environment + +**Use when:** +- First time setting up the project +- After a fresh clone +- When you want to reset your development environment + +### `just install` +Install all project dependencies across all services. + +```bash +just install +``` + +**What it does:** +- Installs root Node.js dependencies (`bun install`) +- Installs Python development dependencies (`uv pip install -r requirements-dev.txt`) +- Installs API dependencies (`cd api && uv pip install -e .`) +- Installs dashboard dependencies (`cd dashboard && bun install`) + +**Use when:** +- After pulling changes that modify dependencies +- When `package.json`, `pyproject.toml`, or requirements files change + +## API Development Commands + +### `just api-native` +Run the API server natively (fastest for development). + +```bash +just api-native +``` + +**What it does:** +- Starts the FastAPI server using `uv run python run.py` +- Runs on `http://localhost:8000` +- Provides fastest reload times for development + +**Use when:** +- Active API development +- You need fastest iteration cycles +- Debugging API code + +### `just api-build` +Build the API Docker image. + +```bash +just api-build + +# With Stripe support +just api-build stripe +``` + +**What it does:** +- Builds Docker image for the API service +- Uses `./scripts/just-api-build.sh` +- Optional Stripe integration support + +**Use when:** +- Preparing for Docker-based deployment +- Testing Docker build process +- Before running `just api-run` + +### `just api-run` +Run the API server in a Docker container. + +```bash +just api-run + +# With Stripe support +just api-run stripe +``` + +**What it does:** +- Runs the API service using Docker +- Uses `./scripts/just-api-run.sh` +- Includes all necessary environment variables +- Optional Stripe integration + +**Use when:** +- Testing Docker deployment locally +- You need isolated environment +- Production-like testing + +### `just api-test` +Run API tests using pytest. + +```bash +just api-test +``` + +**What it does:** +- Changes to `api/` directory +- Runs `pytest` with all configured tests +- Includes unit and integration tests + +**Use when:** +- Before committing API changes +- Validating API functionality +- Continuous integration + +## Frontend Development Commands + +### `just fe-run` +Run the dashboard development server. + +```bash +just fe-run +``` + +**What it does:** +- Changes to `dashboard/` directory +- Installs dependencies (`bun install`) +- Starts development server (`bun run dev`) +- Available at `http://localhost:3000` + +**Use when:** +- Active dashboard development +- Testing frontend changes +- Full-stack development + +### `just fe-build` +Build the dashboard for production. + +```bash +just fe-build +``` + +**What it does:** +- Changes to `dashboard/` directory +- Builds optimized production bundle (`bun run build`) +- Generates static assets + +**Use when:** +- Preparing for production deployment +- Testing production build locally +- Performance optimization + +### `just fe-test` +Run frontend tests. + +```bash +just fe-test +``` + +**What it does:** +- Changes to `dashboard/` directory +- Runs test suite (`bun test`) +- Includes unit and component tests + +**Use when:** +- Before committing frontend changes +- Validating UI functionality +- Continuous integration + +## Code Quality Commands + +### `just lint` +Run all linting checks across the project. + +```bash +just lint +``` + +**What it does:** +- Runs `bun run lint` from project root +- Checks JavaScript/TypeScript files with ESLint +- Checks Python files with Ruff +- Validates code style and quality + +**Use when:** +- Before committing changes +- Code review preparation +- Maintaining code quality + +### `just format` +Format all code using project standards. + +```bash +just format +``` + +**What it does:** +- Runs `ruff format` for Python files +- Applies consistent code formatting +- Fixes automatically correctable issues + +**Use when:** +- Before committing changes +- Standardizing code style +- Preparing for code review + +### `just test` +Run all tests across the project. + +```bash +just test +``` + +**What it does:** +- Runs `just api-test` (API tests) +- Runs `just fe-test` (frontend tests) +- Comprehensive test suite execution + +**Use when:** +- Before major releases +- Validating entire system +- Continuous integration + +## Docker Management Commands + +### `just up` +Start all services with Docker Compose. + +```bash +just up +``` + +**What it does:** +- Runs `docker-compose up -d` +- Starts all defined services in detached mode +- Creates networks and volumes as needed + +**Use when:** +- Starting development environment +- Testing full system integration +- Docker-based development + +### `just down` +Stop all Docker services. + +```bash +just down +``` + +**What it does:** +- Runs `docker-compose down` +- Stops and removes containers +- Preserves volumes and networks + +**Use when:** +- Stopping development environment +- Switching between development modes +- Cleaning up running services + +### `just logs` +View Docker logs for all services. + +```bash +just logs +``` + +**What it does:** +- Runs `docker-compose logs -f` +- Shows real-time logs from all services +- Useful for debugging and monitoring + +**Use when:** +- Debugging service issues +- Monitoring application behavior +- Troubleshooting problems + +### `just clean` +Clean up Docker resources. + +```bash +just clean +``` + +**What it does:** +- Runs `docker-compose down -v` (stops services and removes volumes) +- Runs `docker system prune -f` (removes unused Docker resources) +- Frees up disk space + +**Use when:** +- Cleaning up development environment +- Freeing disk space +- Resolving Docker issues +- Fresh start needed + +## Command Combinations and Workflows + +### Full Development Setup +```bash +# First time setup +just setup + +# Start development +just api-native # Terminal 1 +just fe-run # Terminal 2 +``` + +### Docker Development +```bash +# Setup and start with Docker +just setup +just up +just logs +``` + +### Testing Workflow +```bash +# Run quality checks before committing +just lint +just format +just test +``` + +### Production Preparation +```bash +# Build and test production assets +just api-build +just fe-build +just test +``` + +## Environment-Specific Usage + +### Development Environment +```bash +# Fast iteration cycle +just api-native # Native API for speed +just fe-run # Frontend dev server +``` + +### Integration Testing +```bash +# Full Docker environment +just up # All services in Docker +just test # Run full test suite +``` + +### Production Testing +```bash +# Production-like environment +just api-build # Build production API image +just fe-build # Build production frontend +just up # Run with Docker +``` + +## Troubleshooting Just Commands + +### Command Not Found +```bash +# Verify Just is installed +just --version + +# Install if missing +brew install just # macOS +``` + +### Permission Issues +```bash +# Make sure justfile is executable +chmod +x justfile + +# Check file permissions +ls -la justfile +``` + +### Environment Issues +```bash +# Verify environment files exist +ls -la .env api/.env dashboard/.env.local + +# Run setup to create missing files +just setup +``` + +### Docker Issues +```bash +# Clean Docker environment +just clean + +# Restart Docker service +sudo systemctl restart docker # Linux +``` + +## Custom Commands and Extensions + +You can extend the `justfile` with your own commands. Add to the bottom of the file: + +```bash +# Custom command example +my-command: + @echo "Running my custom command" + # Your commands here + +# Command with parameters +deploy env: + @echo "Deploying to {{env}}" + # Deployment commands +``` + +Use custom commands: +```bash +just my-command +just deploy staging +``` + +## Best Practices + +### Daily Development +1. `just api-native` for API development (fastest) +2. `just fe-run` for frontend development +3. `just lint && just test` before commits + +### Integration Testing +1. `just up` for full environment +2. `just logs` for monitoring +3. `just clean` when issues arise + +### Production Preparation +1. `just api-build && just fe-build` for production builds +2. `just test` for validation +3. `just up` for final testing + +## Related Documentation + +- [Backend Setup Guide](/v2/self-hosting/backend-setup) - Complete setup instructions +- [Docker Guide](/v2/self-hosting/docker-guide) - Docker-specific commands +- [Development Workflow](/v2/self-hosting/development) - Development best practices \ No newline at end of file diff --git a/docs/v2/self-hosting/native-development.mdx b/docs/v2/self-hosting/native-development.mdx new file mode 100644 index 000000000..477ae8bc6 --- /dev/null +++ b/docs/v2/self-hosting/native-development.mdx @@ -0,0 +1,532 @@ +--- +title: "Native Development Guide" +description: "Complete guide for running AgentOps backend services natively without Docker" +--- + +# Native Development Guide + +This guide covers how to run AgentOps backend services natively on your local machine without Docker. Native development provides the fastest iteration cycles and is ideal for active development work. + +## Overview + +Running natively means: +- **Faster startup times** - No container overhead +- **Direct file system access** - Immediate code changes +- **Native debugging** - Use your preferred IDE debugger +- **Resource efficiency** - Lower memory and CPU usage + +## Prerequisites + +### System Requirements +- **Python 3.12+** with pip or uv +- **Node.js 18+** with npm, yarn, or bun +- **Git** for version control +- **Just** (optional) for convenience commands + +### External Services +You'll need these external services configured: +- **Supabase** - Database and authentication +- **ClickHouse** - Analytics database +- **Stripe** (optional) - Payment processing + +## Quick Start + +### 1. Clone and Setup +```bash +git clone https://github.com/AgentOps-AI/AgentOps.Next.git +cd AgentOps.Next/app + +# Copy environment files +cp .env.example .env +cp api/.env.example api/.env +cp dashboard/.env.example dashboard/.env.local +``` + +### 2. Install Dependencies + +#### Root Dependencies +```bash +# Install shared tools (linting, formatting) +bun install + +# Install Python development tools +uv pip install -r requirements-dev.txt +``` + +#### API Dependencies +```bash +cd api + +# Using uv (recommended) +uv pip install -e . + +# Or using pip +pip install -e . + +cd .. +``` + +#### Dashboard Dependencies +```bash +cd dashboard + +# Using bun (recommended) +bun install + +# Or using npm +npm install + +cd .. +``` + +### 3. Configure Environment Variables +Update your environment files with your service credentials. See [External Services Setup](#external-services-setup) below. + +### 4. Start Services +```bash +# Terminal 1: API Server +cd api && uv run python run.py + +# Terminal 2: Dashboard (in a new terminal) +cd dashboard && bun dev + +# Terminal 3: Landing Page (optional, in a new terminal) +cd landing && bun dev +``` + +### 5. Verify Setup +- **API Health**: http://localhost:8000/health +- **API Documentation**: http://localhost:8000/redoc +- **Dashboard**: http://localhost:3000 +- **Landing Page**: http://localhost:3001 + +## External Services Setup + +### Supabase Configuration +1. Create a new project at [supabase.com](https://supabase.com) +2. Get your project credentials from Settings → API +3. Set up the database schema: + ```bash + cd supabase + npx supabase db push + ``` +4. Update `api/.env` and `dashboard/.env.local`: + ```env + # API environment + SUPABASE_URL=https://your-project-id.supabase.co + SUPABASE_KEY=your-service-role-key + + # Dashboard environment + NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co + NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key + ``` + +### ClickHouse Configuration +1. Sign up for [ClickHouse Cloud](https://clickhouse.com/cloud) or self-host +2. Create a database and get connection details +3. Apply the schema: + ```bash + # Use the schema from clickhouse/schema_dump.sql + clickhouse-client --host your-host --query "$(cat clickhouse/schema_dump.sql)" + ``` +4. Update `api/.env`: + ```env + CLICKHOUSE_HOST=your-host.clickhouse.cloud + CLICKHOUSE_PORT=8123 + CLICKHOUSE_USER=default + CLICKHOUSE_PASSWORD=your-password + CLICKHOUSE_DATABASE=your-database + CLICKHOUSE_SECURE=true + ``` + +## API Server Setup + +### Environment Configuration +Key variables in `api/.env`: + +```env +# Database Connections +SUPABASE_URL=https://your-project.supabase.co +SUPABASE_KEY=your-service-role-key +CLICKHOUSE_HOST=your-clickhouse-host +CLICKHOUSE_PASSWORD=your-password + +# Application Settings +APP_URL=http://localhost:3000 +LOGGING_LEVEL=INFO +JWT_SECRET_KEY=your-jwt-secret-key + +# Optional Integrations +SENTRY_DSN=your-sentry-dsn +SENTRY_ENVIRONMENT=development +``` + +### Running the API Server + +#### Using Just (Recommended) +```bash +just api-native +``` + +#### Manual Command +```bash +cd api +uv run python run.py +``` + +#### Alternative Methods +```bash +# Using pip and python directly +cd api +pip install -e . +python run.py + +# Using uvicorn directly +cd api +uvicorn agentops.main:app --host 0.0.0.0 --port 8000 --reload +``` + +### API Development Features +- **Auto-reload** on file changes +- **Interactive API docs** at http://localhost:8000/docs +- **ReDoc documentation** at http://localhost:8000/redoc +- **Health check** at http://localhost:8000/health + +## Dashboard Setup + +### Environment Configuration +Key variables in `dashboard/.env.local`: + +```env +# Supabase Configuration +NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co +NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key +SUPABASE_SERVICE_ROLE_KEY=your-service-role-key + +# Application URLs +NEXT_PUBLIC_APP_URL=http://localhost:8000 +NEXT_PUBLIC_SITE_URL=http://localhost:3000 + +# Feature Flags +NEXT_PUBLIC_ENVIRONMENT_TYPE=development +NEXT_PUBLIC_PLAYGROUND=true + +# Optional Services +NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key +NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn +``` + +### Running the Dashboard + +#### Using Just (Recommended) +```bash +just fe-run +``` + +#### Manual Commands +```bash +cd dashboard + +# Using bun +bun install +bun dev + +# Using npm +npm install +npm run dev + +# Using yarn +yarn install +yarn dev +``` + +### Dashboard Development Features +- **Hot reload** on file changes +- **Fast Refresh** for React components +- **Development tools** integration +- **Source maps** for debugging + +## Development Workflow + +### Daily Development Routine +1. **Start services**: + ```bash + # Terminal 1 + just api-native + + # Terminal 2 + just fe-run + ``` + +2. **Make changes** to your code +3. **Test changes** - services auto-reload +4. **Run tests** before committing: + ```bash + just test + ``` + +### Code Quality Workflow +```bash +# Format code +just format + +# Run linting +just lint + +# Run tests +just test + +# All-in-one quality check +just format && just lint && just test +``` + +### Database Development +```bash +# Apply Supabase migrations +cd supabase +npx supabase db push + +# Reset database (development only) +npx supabase db reset + +# Generate TypeScript types +npx supabase gen types typescript --local > types/database.types.ts +``` + +## Testing + +### API Testing +```bash +cd api + +# Run all tests +pytest + +# Run with coverage +pytest --cov=agentops + +# Run specific test file +pytest tests/test_auth.py + +# Run with verbose output +pytest -v +``` + +### Dashboard Testing +```bash +cd dashboard + +# Run all tests +bun test + +# Run tests in watch mode +bun test --watch + +# Run tests with coverage +bun test --coverage +``` + +### Integration Testing +```bash +# Run full test suite +just test + +# Test API and dashboard separately +just api-test +just fe-test +``` + +## Debugging + +### API Debugging +1. **Set breakpoints** in your IDE +2. **Run with debugger**: + ```bash + cd api + python -m debugpy --listen 5678 --wait-for-client run.py + ``` +3. **Attach your IDE debugger** to port 5678 + +### Dashboard Debugging +1. **Use browser dev tools** (F12) +2. **Next.js debugging**: + ```bash + cd dashboard + NODE_OPTIONS='--inspect' bun dev + ``` +3. **Attach debugger** at chrome://inspect + +### Log Debugging +```bash +# API logs with debug level +cd api +LOGGING_LEVEL=DEBUG uv run python run.py + +# Dashboard logs +cd dashboard +DEBUG=* bun dev +``` + +## Performance Optimization + +### API Performance +- **Use native Python** for fastest development +- **Enable hot reload** with uvicorn +- **Profile with py-spy**: + ```bash + pip install py-spy + py-spy top --pid $(pgrep -f "python run.py") + ``` + +### Dashboard Performance +- **Use bun** for faster package management +- **Enable Fast Refresh** (enabled by default) +- **Analyze bundle size**: + ```bash + cd dashboard + ANALYZE=true bun run build + ``` + +## Troubleshooting + +### Common Issues + +**Python import errors:** +```bash +# Reinstall in editable mode +cd api +uv pip install -e . +``` + +**Node.js module not found:** +```bash +# Clear and reinstall +cd dashboard +rm -rf node_modules package-lock.json +bun install +``` + +**Port already in use:** +```bash +# Find and kill process +lsof -i :8000 # API port +lsof -i :3000 # Dashboard port +kill -9 +``` + +**Database connection issues:** +- Verify credentials in `.env` files +- Check network connectivity +- Ensure external services are running + +### Performance Issues + +**Slow API startup:** +```bash +# Use uv for faster Python package management +uv pip install -e . +``` + +**Slow dashboard reload:** +```bash +# Use bun instead of npm +cd dashboard +rm -rf node_modules +bun install +``` + +### Development Environment Reset +```bash +# Clean everything and start fresh +rm -rf api/.venv dashboard/node_modules node_modules +just setup +``` + +## IDE Configuration + +### VS Code +Recommended extensions: +- Python +- Pylance +- ES7+ React/Redux/React-Native snippets +- Tailwind CSS IntelliSense +- Prettier - Code formatter + +Settings (`.vscode/settings.json`): +```json +{ + "python.defaultInterpreterPath": "./api/.venv/bin/python", + "python.linting.enabled": true, + "python.linting.ruffEnabled": true, + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.eslint": true + } +} +``` + +### PyCharm +1. **Set Python interpreter** to `./api/.venv/bin/python` +2. **Enable Ruff** for Python linting +3. **Configure Node.js** interpreter for dashboard +4. **Set up run configurations** for API and dashboard + +## Advanced Configuration + +### Custom Environment Variables +Add custom variables to your `.env` files: + +```env +# Custom API settings +CUSTOM_FEATURE_FLAG=true +DEBUG_SQL_QUERIES=false + +# Custom dashboard settings +NEXT_PUBLIC_CUSTOM_FEATURE=enabled +``` + +### Development Proxy +Set up a proxy for API calls in development: + +```javascript +// dashboard/next.config.js +module.exports = { + async rewrites() { + return [ + { + source: '/api/:path*', + destination: 'http://localhost:8000/:path*', + }, + ] + }, +} +``` + +### Hot Reload Configuration +Fine-tune hot reload behavior: + +```python +# api/run.py +if __name__ == "__main__": + import uvicorn + uvicorn.run( + "agentops.main:app", + host="0.0.0.0", + port=8000, + reload=True, + reload_dirs=["agentops"], # Only watch specific directories + reload_excludes=["*.pyc", "*.log"], # Exclude certain files + ) +``` + +## Next Steps + +Once your native development environment is running: + +1. **Explore the codebase** - Start with `api/agentops/main.py` and `dashboard/pages/index.tsx` +2. **Make your first changes** - Try modifying a simple component or API endpoint +3. **Set up testing** - Write tests for your changes +4. **Configure your IDE** - Set up debugging and linting +5. **Join the community** - Connect with other developers + +For production deployment, see our [Deployment Guide](/v2/self-hosting/deployment). \ No newline at end of file diff --git a/docs/v2/self-hosting/overview.mdx b/docs/v2/self-hosting/overview.mdx new file mode 100644 index 000000000..f0ca385a2 --- /dev/null +++ b/docs/v2/self-hosting/overview.mdx @@ -0,0 +1,302 @@ +--- +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)! \ No newline at end of file