Chapter 1
Getting Started
Run the stack on your machine with native MySQL, Redis, Python, and Node.js — then verify with pytest and optional Playwright smoke tests.
Prerequisites
- MySQL 8 and Redis 7 (local install or managed)
- Node.js 20+ and npm
- Python 3.11+
make(repo root Makefile)
Local setup
1. Clone and configure env
Copy
.env.example → .env. Set SECRET_KEY. OAuth keys are optional for dev (login flows need them).2. Install backend
cd backend && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/alembic upgrade head3. Start API + frontend
API:
.venv/bin/uvicorn app.main:app --reload --port 8000. Frontend: cd frontend && npm ci && npm run dev (:3000).4. Worker (prod required)
.venv/bin/arq app.workers.settings.WorkerSettings — scheduled publish and async AI jobs.💡
AI and payments off by default
Leave
AI_ENABLED=false and PAYMENTS_ENABLED=false until you configure OpenAI or Stripe. The app must remain usable without them.Tests
make test— backend pytest (unit + integration)make smoke-e2e— Playwright smoke on ports 3010/8010- CI runs backend, frontend lint/build, prod config validation, and smoke-e2e
Next steps
Read Architecture, browse Data flows, and use the searchable Configuration reference when tuning production env.