Self-Hosting

Deploy Rhesis on your own infrastructure with proper security, authentication, and production configuration.

Overview

This guide covers deploying Rhesis for production use with:

• Secure authentication - Auth0 integration with JWT token management
• Database encryption - Field-level encryption for sensitive data
• Email notifications - SMTP configuration for system emails
• AI model providers - Gemini, OpenAI, and Azure OpenAI configuration
• Service monitoring - Health checks, logging, and status management
• Automated setup - Database initialization and migrations

Prerequisites

• Docker Desktop installed and running (Docker Compose V2)
• Git (to clone the repository)
• Ports 3000, 8080, 8081, 5432, and 6379 available on your system
• Auth0 account (or another OAuth provider)
• AI provider account (Gemini, OpenAI, or Azure OpenAI)

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.

System Requirements

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 Service:

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

Quick Start

1. Clone the repository

git clone https://github.com/rhesis-ai/rhesis.git
cd rhesis

2. Copy environment variables

cp .env.example .env.docker

3. Configure environment variables

Edit the .env.docker file and update all required configurations (see Environment Configuration below).

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

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=https://your-domain.com

# 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

Database Encryption

# Database Field Encryption
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
DB_ENCRYPTION_KEY=your-generated-encryption-key

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

Configure AI providers for natural language processing and content generation:

# Gemini AI Configuration
# 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
# 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
# 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 required 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.docker file:

# Disable telemetry (opt-out)
OTEL_RHESIS_TELEMETRY_ENABLED=false

Then restart your services:

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

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://telemetry.rhesis.ai
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 <PID>

Performance Optimization

Resource Allocation:

• Ensure Docker has at least 8GB RAM allocated for production
• 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
• Consider PostgreSQL tuning for production workloads

Security Considerations

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 documentation  for additional guidance

Additional Resources

• Backend Documentation
• Frontend Documentation
• Worker Documentation
• Environment Setup Guide
• Running Locally - For local development and testing

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