Local Development

Set up the full Opentrace stack locally for development and testing.

Prerequisites

Node.js 20+ — for the Next.js client
Python 3.12+ — for the FastAPI server
Docker — for Redis (and optionally Supabase local)
Supabase CLI — for local Supabase (PostgreSQL + pgvector)

Setup Steps

Clone the repository

bash

git clone https://github.com/your-org/opentrace.git
cd opentrace

Start Supabase locally

bash

supabase start

This starts a local PostgreSQL instance with pgvector on port 54322. Apply the schema from notes/schema.sql.

Start Redis

bash

docker run -d --name redis -p 6379:6379 redis:7-alpine

Set up the server

bash

cd server
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env  # fill in your API keys

See Environment Variables for the complete .env reference.

Start the FastAPI server

bash

uvicorn src.main:app --reload --port 8000

Start the Celery worker

In a separate terminal:

bash

cd server
source .venv/bin/activate
python -m celery -A src.services.celery:celery_app worker --loglevel=info --pool=threads --concurrency=4

Set up the client

bash

cd client
npm install
cp .env.local.example .env.local  # fill in Clerk keys + API URL

Start the Next.js client

bash

npm run dev

Tip

The client runs on http://localhost:3000 and the server on http://localhost:8000. Set NEXT_PUBLIC_API_URL=http://localhost:8000 in the client's .env.local.

Verify Setup

Client: visit http://localhost:3000 — you should see the landing page
Server: visit http://localhost:8000/docs — you should see the FastAPI Swagger UI
Redis: redis-cli ping should return PONG

Was this page helpful?

PreviousArchitecture Overview NextDocker Deployment