Skip to Content
ContributeDevelopment Setup

Development setup

Two approaches: local mixed stack (./rh dev …) for day-to-day work, or all-in-one Docker (./rh start) for a full environment without local service wiring.

Prerequisites

  • Git
  • Docker (for ./rh dev up, ./rh start, and related commands)
  • uv  — Python tooling at the repo root and under apps/backend
  • Node.js 18+ and npm — frontend and docs dev servers

Optional: pyenv to pin Python 3.10+ if your machine needs it.

Default ports

WhatPort
Backend API / OpenAPI8080
Frontend / Next.js3000
Documentation site3001
Dev PostgreSQL (./rh dev up)11000
Dev Redis (./rh dev up)11001

Clone the repo

Terminal
git clone https://github.com/YOUR_USERNAME/rhesis.git
cd rhesis
git remote add upstream https://github.com/rhesis-ai/rhesis.git

From the repo root:

Terminal
./rh dev init         # env files (one-time; see note below)
./rh dev up             # postgres and redis (see table above)
./rh dev backend        # terminal 1 — migrations via apps/backend/start.sh
./rh dev frontend       # terminal 2

./rh dev init writes apps/backend/.env and apps/frontend/.env.local for local infrastructure. If those files already exist and were not created by init, the script may prompt before overwriting.

Run ./rh help or ./rh dev for the full command list (./rh dev worker, ./rh dev docs, ./rh dev status, etc.).

Path 2: Full stack with Docker

Terminal
./rh start

Typical URLs: frontend http://localhost:3000 , API http://localhost:8080/docs . Use ./rh logs, ./rh stop, ./rh restart, and ./rh delete to manage the stack.

This mode is aimed at local testing (including convenient sign-in behavior). For production-style deployment, see the deployment documentation on this site.

Backend-only workflows

For database access, environment configuration, make targets, and advanced setups (including cloud database proxies when your team uses them), see the Backend section — especially Development workflow and Environment config.

From apps/backend, common entrypoints are ./start.sh, or from the repo root ./rh dev backend, or running uvicorn directly once the venv is active.

Documentation site locally

Terminal
./rh dev docs

This runs docs/src/start.sh (default port 3001).

Quick checks

Terminal
curl -s http://localhost:8080/health

Branching, commits, and checks

  • Use feature branches and Conventional Commits 
  • uvx pre-commit install before your first commit
  • Run make format, make lint, and make test from apps/backend/, sdk/, or apps/frontend/ as appropriate for your change

Troubleshooting

  • ./rh dev up fails: ensure Docker is running; confirm nothing else is bound to the dev Postgres/Redis ports in the table above
  • Backend database errors: run ./rh dev up after ./rh dev init; for non-local database setups, see Environment config
  • Stale Python env: from apps/backend, run uv sync again and use apps/backend/.venv

Still stuck? Ask on Discord .

OverviewCoding Standards