Skip to Content
DevelopmentContributingDevelopment Setup

Development Setup

This guide will walk you through setting up your development environment for Rhesis, ensuring you have everything needed to contribute effectively.

Complete Setup Guide Follow this guide step-by-step to get your Rhesis development environment up and running. This covers everything from prerequisites to running your first test.

Prerequisites

Before you begin, ensure you have the following installed on your system:

System Requirements - Operating System: macOS, Linux, or Windows (WSL recommended) - Python 3.8+: For backend development - Node.js 18+: For frontend development - Git: For version control - Docker: For containerized development (optional) - PostgreSQL: For database development - Redis: For background task processing

Installing Prerequisites

Python Setup

We use uv  as our Python package manager for faster, more reliable dependency management.

Terminal
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Node.js Setup

We recommend using nvm  for Node.js version management:

Terminal
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your terminal or run
source ~/.bashrc

# Install Node.js 18
nvm install 18
nvm use 18

# Verify installation
node --version
npm --version

Database Setup

PostgreSQL:

Terminal
# macOS (using Homebrew)
brew install postgresql
brew services start postgresql

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# Create database
createdb rhesis_dev

Redis:

Terminal
# macOS (using Homebrew)
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis-server

Environment Setup

1. Clone the Repository

Terminal
# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/rhesis.git
cd rhesis

# Add the upstream repository
git remote add upstream https://github.com/rhesis-ai/rhesis.git

2. Install Dependencies

Terminal
# Install Python dependencies
uv sync

# Install frontend dependencies
cd apps/frontend
npm install

# Install documentation dependencies
cd ../docs
npm install

# Return to root
cd ../..

3. Environment Configuration

Terminal
# Copy the example environment file
cp .env.example .env

# Edit the environment file with your configuration
# You'll need to set up database URLs, API keys, etc.

Key Environment Variables:

.env
# Database Configuration
DATABASE_URL=postgresql://username:password@localhost/rhesis_dev
TEST_DATABASE_URL=postgresql://username:password@localhost/rhesis_test

# Redis Configuration
REDIS_URL=redis://localhost:6379

# Authentication
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# External Services
OPENAI_API_KEY=your-openai-api-key
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Development Settings
DEBUG=true
ENVIRONMENT=development

4. Database Setup

Terminal
# Navigate to backend directory
cd apps/backend

# Run database migrations
uv run alembic upgrade head

# Create initial data (if needed)
uv run python -m rhesis.backend.scripts.create_initial_data

# Return to root
cd ../..

Starting Development Servers

Using the CLI Tool

We provide a convenient CLI tool for managing services:

Terminal
# Start all services
./rh backend start
./rh frontend start
./rh docs start

# Or start them all at once (if configured)
./rh start all

Manual Startup

If you prefer to start services manually:

Terminal
# Backend (FastAPI)
cd apps/backend
uv run uvicorn rhesis.backend.app.main:app --reload --port 8080

# Frontend (Next.js)
cd apps/frontend
npm run dev

# Documentation (Nextra)
cd apps/documentation
npm run dev

# Worker (Celery)
cd apps/worker
uv run celery -A rhesis.worker worker --loglevel=info

Verification

Check Service Status

Once all services are running, verify they’re working correctly:

Backend API

Visit http://localhost:8080/docs  for API documentation

Frontend App

Visit http://localhost:3000  for the main application

Documentation

Visit http://localhost:3001  for the documentation site

Health Check

Visit http://localhost:8080/health  for backend status

Database

Check database connection and migrations

Redis

Verify Redis connection for background tasks

Quick Health Check

# Test backend health
curl http://localhost:8080/health
 
# Test database connection
cd apps/backend
uv run python -c "from rhesis.backend.database import get_db; print('Database OK')"
 
# Test Redis connection
uv run python -c "import redis; r = redis.Redis(); print('Redis OK')"

Development Tools

Code Quality Tools

We use several tools to maintain code quality:

Python Tools

Ruff for linting and formatting

TypeScript Tools

ESLint and Prettier for code quality

Testing Tools

pytest for Python, Jest for JavaScript

Pre-commit Hooks

Automated checks before commits

Setting Up Pre-commit Hooks

# Install pre-commit hooks
uvx pre-commit install
 
# Run pre-commit on all files
uvx pre-commit run --all-files

IDE Configuration

VS Code Extensions:

  • Python
  • TypeScript and JavaScript
  • ESLint
  • Prettier
  • GitLens
  • Docker

VS Code Settings:

{
  "python.defaultInterpreter": "./.venv/bin/python",
  "python.formatting.provider": "ruff",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Testing Your Setup

Run the Test Suite

# Backend tests
cd apps/backend
uv run pytest
 
# Frontend tests
cd ../frontend
npm test
 
# All tests from root
uv run pytest tests/

Create Your First Test

# apps/backend/tests/test_example.py
def test_health_endpoint(client):
    """Test the health check endpoint."""
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json()["status"] == "healthy"

Troubleshooting

Common Issues

Port Conflicts If you get port conflicts, check what’s running on the ports: - Backend: 8080 - Frontend: 3000 - Documentation: 3001 - Database: 5432

  • Redis: 6379

Database Connection Issues:

# Check if PostgreSQL is running
sudo systemctl status postgresql
 
# Check if Redis is running
sudo systemctl status redis-server
 
# Test database connection
psql -h localhost -U your_username -d rhesis_dev

Python Environment Issues:

# Recreate virtual environment
rm -rf .venv
uv sync
 
# Check Python version
python --version

Node.js Issues:

# Clear npm cache
npm cache clean --force
 
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Getting Help

Documentation

Check our comprehensive documentation

GitHub Issues

Search existing issues or create new ones

Community

Join our GitHub Discussions

Logs

Check application logs for errors

Next Steps

Ready to Develop Now that your environment is set up, you can: - Explore the codebase structure - Run the test suite - Make your first contribution - Join our community discussions

  1. Explore the Codebase

    • Read through the project structure
    • Understand the architecture
    • Review the coding standards

  2. Run Tests

    • Ensure all tests pass
    • Understand the testing patterns
    • Add tests for new features

  3. Make Your First Contribution

    • Pick a “good first issue”
    • Create a feature branch
    • Submit a pull request

  4. Join the Community

    • Participate in discussions
    • Help other contributors
    • Share your experience

Need Help? If you encounter any issues during setup, don’t hesitate to: - Ask questions in GitHub Discussions  - Report issues on GitHub Issues 

Happy coding!

Contributing to RhesisCoding Standards