dev/

Development Environment

Builds sercha-core from source. Use this for local development and testing.

Prerequisites: Docker, Node.js 20+, Go 1.24+.

1. Configure environment

cp .env.example .env

Generate the required secrets:

# macOS / Linux
openssl rand -hex 32  # paste as JWT_SECRET
openssl rand -hex 32  # paste as MASTER_KEY

Edit .env and fill in JWT_SECRET and MASTER_KEY. The GitHub OAuth and OpenAI fields are optional.

2. Start backend services

docker compose up -d --build

This builds sercha-core from source and starts PostgreSQL, OpenSearch, and the API server on port 8080.

3. Start the UI

cd ../../ui
cp .env.example .env.local   # if .env.example exists, otherwise create manually

Create ui/.env.local with:

NEXT_PUBLIC_API_URL=http://localhost:8080

Then install and run:

npm install
npm run dev

The UI runs at http://localhost:3000.

Services

OAuth Setup

When configuring OAuth providers for the dev environment:

Useful commands

# View API logs
docker compose logs -f sercha

# Rebuild after code changes
docker compose up -d --build sercha

# Run integration tests
go test ./tests/integration/... -v

# Stop services (preserve data)
docker compose down

# Stop and remove all data
docker compose down -v

Next Steps

• Development Guide
• Configuration Reference
• Contributing