Self-hosting

You can self-host Rhesis on your own infrastructure.

This guide covers two deployment scenarios:

1. Zero-Configuration Local Deployment - Get started immediately with pre-configured defaults
2. Production Deployment - Full configuration for production environments

Important: This guide uses Docker Compose V2 syntax (docker compose without hyphen). If you’re using an older version of Docker, you may need to install Docker Compose V2 or use the legacy docker-compose command.

Zero-Configuration Local Deployment

Perfect for quickly testing Rhesis locally without any configuration hassles. This setup includes:

• ✅ No Auth0 setup required - Local authentication bypass enabled
• ✅ Pre-configured database - PostgreSQL with automatic setup
• ✅ Auto-login enabled - Access the dashboard immediately
• ✅ Default admin user - admin@local.dev created automatically
• ✅ All secrets included - Development-safe defaults provided

Prerequisites

• Docker Desktop installed and running
• Git (to clone the repository)
• Ports 3000, 8080, 8081, 5432, and 6379 available on your system

Quick Start

Get Rhesis running in under 5 minutes:

# 1. Clone the repository
git clone https://github.com/rhesis-ai/rhesis.git
cd rhesis

# 2. Start all services with one command
./rh start

# That's it! The platform will automatically:
# - Generate database encryption key
# - Create .env.docker.local with local configuration
# - Start all services (backend, frontend, database, worker)
# - Create default admin user and example data
# - Enable auto-login

# 3. Access the platform
# Frontend: http://localhost:3000 (auto-login enabled)
# Backend API: http://localhost:8080/docs
# Worker Health: http://localhost:8081/health/basic

# 4. (Optional) Enable test generation
# Get your API key from https://app.rhesis.ai/
# Edit .env.docker.local and update RHESIS_API_KEY=your-actual-key

That’s it! The ./rh start command automatically:

• Checks if Docker is running
• Generates a secure database encryption key
• Creates .env.docker.local with all required configuration
• Enables local authentication bypass (auto-login)
• Starts all services
• Creates the database and runs migrations
• Creates the default admin user (Local Admin)
• Loads example test data

Configuration Files

The zero-configuration setup uses these files:

├── 

├── 

└── 

What’s Auto-Generated

When you run ./rh start, the .env.docker.local file is automatically created with:

Auto-Generated Keys:

• Database encryption key (using Python cryptography.fernet)
• Local authentication bypass flags:
  • QUICK_START=true (enables backend auto-login endpoint)
  • NEXT_PUBLIC_QUICK_START=true (enables frontend auto-login detection)

You can add (optional):

• Rhesis API key (for test generation)
• AI provider keys (Gemini, OpenAI, Azure)
• SMTP credentials (for email notifications)

Default Services:

• Backend API on port 8080
• Frontend on port 3000
• Worker on port 8081
• PostgreSQL on port 5432
• Redis on port 6379

Default Access

Once running, access the platform at:

Optional: Configure AI Providers

The local setup works out-of-the-box, but to enable test generation, you need an AI provider. Two options:

Option 1: Use Rhesis API (Recommended)

1. Get your API key from https://app.rhesis.ai/ 
2. Edit .env.docker.local and add:

RHESIS_API_KEY=your-actual-rhesis-api-key-here

Option 2: Use Your Own AI Provider

Add your provider’s credentials to .env.docker.local:

# Google Gemini
GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL_NAME=gemini-2.0-flash-001
GOOGLE_API_KEY=your-google-api-key

# Or Azure OpenAI
AZURE_OPENAI_ENDPOINT=your-endpoint
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=your-version

# Or OpenAI
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL_NAME=gpt-4o

After updating, restart services:

./rh restart

Managing Services

Use the ./rh CLI for easy service management:

Stop services:

# Stop all services
./rh stop

View logs:

# All services (follow in real-time)
./rh logs

# Specific service
./rh logs backend
./rh logs frontend
./rh logs worker

Restart services:

# Restart all services
./rh restart

Delete everything (fresh start):

# Remove all containers, volumes, images, and data
./rh delete

# Then start fresh
./rh start

Troubleshooting

Docker not running:

# The ./rh start command checks automatically
# If you see this error:
# ❌ Error: Docker is not running
# 💡 Please start Docker Desktop and try again

# Start Docker Desktop, then run:
./rh start

Port already in use:

# Check what's using a port (e.g., port 3000)
lsof -i :3000

# Kill the process
kill -9 

Need a fresh start:

# Delete everything and start fresh
./rh delete
./rh start

Check service health:

# View all running containers
docker compose ps

# Check backend health
curl http://localhost:8080/health

# Check worker health
curl http://localhost:8081/health/basic

Python cryptography package missing:

# If you see this error:
# ❌ Error: Failed to generate encryption key
# 💡 Make sure Python 3 and cryptography package are installed

# Install the package:
pip install cryptography

# Then run:
./rh start

Auto-login not working (still seeing login page):

# Check if Quick Start variables are set correctly
cat .env.docker.local | grep QUICK_START

# Should show:
# QUICK_START=true
# NEXT_PUBLIC_QUICK_START=true

# If missing, add them:
echo "QUICK_START=true" >> .env.docker.local
echo "NEXT_PUBLIC_QUICK_START=true" >> .env.docker.local

# Then restart:
./rh restart

Note: The ./rh start command automatically sets both variables. If you’re manually configuring, ensure both QUICK_START=true (for backend) and NEXT_PUBLIC_QUICK_START=true (for frontend) are set in your .env.docker.local file. If you add these variables after the frontend container was already built, you may need to rebuild it: docker compose --env-file .env.docker.local build frontend && ./rh restart

Production Deployment

For production environments, you need to configure authentication, security, and other production concerns properly.

Prerequisites

• Docker Desktop installed and running
• Git (to clone the repository)
• Ports 3000, 8080, 8081, 5432, and 6379 available on your system

System Requirements

Local Deployment Environment

For local deployment, testing, and evaluation:

Local Deployment Notes:

• Includes hot-reload and development tools
• Lower concurrent user load
• Smaller dataset for testing
• Debug logging enabled

Production Environment

For production deployment with real users:

Production Notes:

• Optimized builds without development overhead
• Higher concurrent user capacity
• Production logging levels
• Database connection pooling

Detailed Resource Breakdown

Memory Usage by Environment:

Storage Requirements:

Performance Characteristics

CPU Usage Patterns:

• High Load: AI processing, bulk data operations, migrations
• Normal Load: API requests, background tasks, web serving
• Idle: Minimal CPU during low activity periods

Scaling Factors:

• AI Operations: Memory spikes during model inference
• Concurrent Users: ~50-100 MB RAM per active user
• Database Growth: Storage scales with user data and analytics
• Background Tasks: CPU-intensive during batch processing

Docker Compose Version Note

Why docker compose instead of docker-compose?

• docker-compose (V1): The original standalone tool written in Python, deprecated as of June 2023
• docker compose (V2): The modern version integrated into Docker CLI, written in Go with better performance

If you encounter errors with docker-compose, you’re likely using the deprecated V1. Switch to docker compose (V2) for:

• Better performance and reliability
• Active maintenance and security updates
• Support for newer Docker features
• Improved integration with Docker CLI

Quick Start

1. Clone the repository

git clone 
cd rhesis

2. Copy environment variables

cp .env.example .env.docker

3. Configure environment variables

   Edit the .env.docker file and update the following configurations:

   • Auth0 configuration
   • JWT configuration
   • Azure OpenAI configuration
   • Gemini configuration
   • SMTP configuration
   • NextAuth.js configuration
   • Any other environment variables as needed

4. Start all services

docker compose --env-file .env.docker up -d

5. Access the applications
   • Frontend: http://localhost:3000 
   • Backend API: http://localhost:8080/docs 
   • Worker Health: http://localhost:8081/health/basic 

Architecture Overview

Services

The Rhesis platform consists of several interconnected services:

Service Dependencies

Frontend → Backend → PostgreSQL
           ↓
         Redis ← Worker

Automated Database Setup

No manual database setup required! The system automatically handles:

• PostgreSQL database and user creation
• Database ownership and permissions setup
• Automatic Alembic migration execution
• Table and relationship creation
• Migration status checking (prevents duplicate migrations)

The backend container startup process:

1. Waits for PostgreSQL to be ready
2. Sets proper database ownership
3. Runs all pending migrations
4. Starts the FastAPI application

Environment Configuration

Required Environment Variables

Update your .env.docker file with the following configurations:

Authentication & Security:

These variables configure user authentication and security for the platform:

# Auth0 Configuration
# Used for user authentication and authorization
AUTH0_DOMAIN=your-auth0-domain
AUTH0_AUDIENCE=your-auth0-audience
AUTH0_CLIENT_ID=your-auth0-client-id
AUTH0_CLIENT_SECRET=your-auth0-client-secret
AUTH0_SECRET_KEY=your-auth0-secret-key

# JWT Configuration

# Used for secure token generation and validation

JWT_SECRET_KEY=your-jwt-secret-key
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=10080

# NextAuth Configuration

# Required for Next.js authentication integration

NEXTAUTH_SECRET=your-nextauth-secret
NEXTAUTH_URL=http://localhost:3000

# Frontend Configuration

# Public variables accessible in the browser for Auth0 integration

NEXT_PUBLIC_AUTH0_DOMAIN=your-auth0-domain
NEXT_PUBLIC_AUTH0_CLIENT_ID=your-auth0-client-id

OAuth Providers (Optional):

Additional authentication providers for user login options:

# Google OAuth (Optional)
# Enables Google sign-in for users
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Email Configuration (Optional):

Required for sending system emails, notifications, and user communications:

# SMTP Configuration (Optional)
# Used for sending emails (notifications, invitations, etc.)
SMTP_HOST=your_smtp_host
SMTP_PORT=465
SMTP_USER=your_smtp_user
SMTP_PASSWORD=your_smtp_password
FROM_EMAIL=your_from_email

AI Model Configuration (Optional):

Configure AI providers for natural language processing and content generation:

# Gemini AI Configuration (Optional)
# Google's Gemini AI for advanced language processing
GEMINI_API_KEY=your-gemini-api-key
GOOGLE_API_KEY=your-google-api-key
GEMINI_MODEL_NAME=gemini-2.0-flash-001

# Azure OpenAI Configuration (Optional)

# Microsoft Azure's OpenAI service for GPT models

AZURE_OPENAI_ENDPOINT=YOUR_AZURE_OPENAI_API_ENDPOINT
AZURE_OPENAI_API_KEY=YOUR_AZURE_OPENAI_API_KEY
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=YOUR_AZURE_OPENAI_API_VERSION

# OpenAI Configuration (Optional)

# Direct OpenAI API integration for GPT models

OPENAI_API_KEY=YOUR_OPENAI_API_KEY
OPENAI_MODEL_NAME=gpt-4o

Note: At least one AI provider configuration is recommended for full platform functionality. You can choose between Gemini, Azure OpenAI, or OpenAI based on your preferences and requirements.

📊 Telemetry & Privacy

Telemetry Status

For self-hosted deployments: Telemetry is ENABLED by default (opt-out). For cloud deployments: Telemetry is ALWAYS enabled (user consent via Terms & Conditions).

Telemetry helps us improve Rhesis by understanding:

• Which features are most valuable
• Performance bottlenecks
• Common error patterns

What We Collect

✅ Anonymous usage data:

• Feature usage patterns (which features are used, how often)
• API performance metrics (response times, error rates)
• Deployment information (self-hosted vs cloud, version)
• Hashed user/org IDs (SHA-256, irreversible, 16-char truncated)

What We DON’T Collect

❌ Your private data is NEVER collected:

• Your prompts, responses, or generated content
• Document contents or uploaded files
• API keys, passwords, or credentials
• Personal information (names, emails, etc.)
• IP addresses or organization names
• Any identifiable or sensitive data

Data Usage

• Usage: Only by Rhesis team for product improvement
• Sharing: Never sold or shared with third parties
• Storage: Separate analytics database (isolated from your data)

How to Disable Telemetry (Opt-Out)

Telemetry is enabled by default. To opt-out, add to your .env file:

# Disable telemetry (opt-out)
OTEL_RHESIS_TELEMETRY_ENABLED=false

Then restart your services:

docker-compose restart
# or
./rh backend start

Telemetry Configuration (Optional)

If telemetry is enabled (default), you can optionally configure these settings:

# Telemetry configuration (optional - these are the defaults)
OTEL_DEPLOYMENT_TYPE=self-hosted
OTEL_EXPORTER_OTLP_ENDPOINT=https://rhesis-otel-collector-dev-235yqdecwq-uc.a.run.app/
OTEL_SERVICE_NAME=rhesis

Management Commands

Service Management

Start services:

# Start all services in detached mode
docker compose --env-file .env.docker up -d

# Start with logs visible

docker compose --env-file .env.docker up

Stop services:

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes all data)

docker compose down -v

Restart services:

# Restart all services
docker compose --env-file .env.docker restart

# Restart specific service

docker compose --env-file .env.docker restart backend

Monitoring and Logs

View logs:

# All services
docker compose logs

# Specific service

docker compose logs backend
docker compose logs frontend
docker compose logs worker

# Follow logs in real-time

docker compose logs -f backend

Check service status:

# View running containers and their status
docker compose ps

Building and Updates

Rebuild services:

# Rebuild all services
docker compose --env-file .env.docker build

# Rebuild specific service

docker compose --env-file .env.docker build backend

# Rebuild and restart

docker compose --env-file .env.docker up -d --build

Database Operations

The database is automatically managed, but you can access it directly if needed:

# Connect to PostgreSQL
docker exec -it rhesis-postgres psql -U rhesis-user -d rhesis-db

# Check current migration status

docker exec rhesis-backend bash -c "cd src/rhesis/backend && alembic current"

# Run migrations manually (if needed)

docker exec rhesis-backend bash -c "cd src/rhesis/backend && alembic upgrade head"

# View migration history

docker exec rhesis-backend bash -c "cd src/rhesis/backend && alembic history"

Troubleshooting

Common Issues

Database Migration Problems:

1. Check migration status:

docker exec rhesis-backend bash -c "cd src/rhesis/backend && alembic current"

2. View migration logs:

docker compose logs backend | grep -i migration

3. Reset database (WARNING: deletes all data):

docker compose down -v
docker compose --env-file .env.docker up -d

Service Health Issues:

1. Check service status:

docker compose ps

2. Verify environment variables:

docker exec rhesis-backend env | grep AUTH0

3. Check resource usage:

docker stats

Port Conflicts:

If you encounter port conflicts, you can modify the ports in docker compose.yml or stop conflicting services:

# Check what's using a port (e.g., port 3000)
lsof -i :3000

# Kill process using the port

kill -9 

Performance Optimization

Resource Allocation:

• Ensure Docker has at least 4GB RAM allocated
• Monitor disk space usage with docker system df
• Clean up unused resources with docker system prune

Database Performance:

• Monitor PostgreSQL logs: docker compose logs postgres
• Check connection counts and slow queries

Security Considerations

• Change default passwords in production
• Use strong JWT secrets
• Configure proper firewall rules
• Keep environment variables secure
• Regularly update Docker images

Backup and Recovery

Database Backup

# Create database backup
docker exec rhesis-postgres pg_dump -U rhesis-user rhesis-db > backup.sql

# Restore from backup

docker exec -i rhesis-postgres psql -U rhesis-user -d rhesis-db < backup.sql

Full System Backup

# Stop services
docker compose down

# Backup volumes

docker run --rm -v rhesis_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz -C /data .
docker run --rm -v rhesis_redis_data:/data -v $(pwd):/backup alpine tar czf /backup/redis_backup.tar.gz -C /data .

# Restart services

docker compose --env-file .env.docker up -d

Support and Resources

Getting Help

If you encounter issues:

1. Check the logs: docker compose logs
2. Verify environment variables are set correctly
3. Ensure Docker has sufficient resources
4. Check if ports are available and not in use
5. Review the main documentation  for additional guidance

Additional Resources

• Backend Documentation 
• Frontend Documentation 
• Worker Documentation 
• Environment Setup Guide 

For local development setup without Docker (for contributing to Rhesis), see the 🔧 Environment Setup Guide .