RAGcore-Public/runbooks/LOCAL_DEVELOPMENT.md

Local Development Runbook

Prerequisites

Python 3.13, uv, Docker Engine and Docker Compose.

Bootstrap

cp .env.example .env
uv sync --all-extras --group dev
docker compose up -d postgres qdrant
uv run python scripts/wait_for_services.py
uv run pytest tests/api/test_health.py tests/unit/test_config.py
uv run uvicorn ragcore.main:app --reload

Worker in a second terminal:

uv run python -m ragcore.worker

Normal task cycle

python scripts/backlog.py next
python scripts/backlog.py start <task>
# implementation
bash scripts/codex_verify.sh  # PowerShell: .\scripts\codex_verify.ps1
python scripts/backlog.py done <task> --evidence artifacts/evidence/<task>

Reset disposable state

docker compose down -v
rm -rf .state

Never apply this reset to production paths.