Developer Setup¶

This runbook takes a new developer from empty machine to a working local stack.

1. Prerequisites¶

Python 3.11+
Node.js 20+ and npm
Git
uv installed and available on PATH
Optional native tools:
CMake
C++ compiler (MSVC/clang/gcc)
clang-format
cppcheck
Docker Desktop (or Docker Engine + Compose)

2. Clone and bootstrap¶

git clone https://github.com/ringxworld/story_generator.git
cd story_generator
uv sync --all-groups
npm install --prefix web

If uv is not on your shell path, use local venv module execution:

.venv\Scripts\python.exe -m ruff --version

3. Install Git hooks¶

make hooks-install

This installs both pre-commit and pre-push checks. The pre-push gate also validates Docker CI image buildability.

4. Run the local stack¶

One-command path (bootstrap + build + launch):

make stack-up

Fast path after first setup:

make dev-stack

Hot-edit path on separate frontend port:

make dev-stack-hot

Or run services separately:

Terminal 1 (API):

make api

Terminal 2 (web studio):

make web-dev

Terminal 2 (web hot-edit mode on dedicated port):

make web-hot

Default local endpoints:

API: http://127.0.0.1:8000
Web: http://127.0.0.1:5173
Web (hot mode): http://127.0.0.1:5174
API docs: http://127.0.0.1:8000/docs
ReDoc: http://127.0.0.1:8000/redoc
OpenAPI schema: http://127.0.0.1:8000/openapi.json

Default local DB:

work/local/story_gen.db
Runtime log file: work/logs/story_gen.log

Override DB path:

uv run story-api --db-path work/local/dev.db --reload

Override frontend API base URL:

# PowerShell
$env:VITE_API_BASE_URL="http://127.0.0.1:8000"
npm run --prefix web dev

Tune local observability limits:

# PowerShell
$env:STORY_GEN_LOG_LEVEL="INFO"
$env:STORY_GEN_ANOMALY_RETENTION_DAYS="30"
$env:STORY_GEN_ANOMALY_MAX_ROWS="10000"

5. Quality checks¶

Python quality:

make quality

Frontend quality:

make frontend-quality

Native quality:

make native-quality

Everything (local gate before push):

make check

6. Common workflows¶

Run tests only:

make test
make e2e
make web-test

Auto-fix Python lint/format:

make fix

Build docs locally:

make docs-serve
make build-site

Cleanup generated artifacts:

make clean
make clean-deep

Regenerate brand icon pack:

make brand-icons

7. Optional NLP dependency groups¶

Install additional groups when needed:

uv sync --group nlp
uv sync --group topic
uv sync --group advanced

7.1 Optional translation dependencies¶

Offline translation uses Argos Translate:

uv sync --group translation

8. Optional cloud compose scaffolds¶

If you want to smoke-test deployment shapes locally:

docker compose -f ops/docker-compose.droplet.yml --env-file ops/.env.example up -d
docker compose -f ops/docker-compose.aws.yml --env-file ops/.env.aws.example up -d
docker compose -f ops/docker-compose.gcp.yml --env-file ops/.env.gcp.example up -d
docker compose -f ops/docker-compose.azure.yml --env-file ops/.env.azure.example up -d

Use these as reference scaffolds only; they are not production manifests.

9. Docker local stack (optional)¶

Run the local API + web studio inside containers:

make docker-up

Endpoints:

API: http://127.0.0.1:8000
Web: http://127.0.0.1:5173

Lifecycle commands:

make docker-down
make docker-logs

Run full quality checks in the CI-equivalent container:

make docker-ci

10. Troubleshooting¶

uv: command not found

Re-open terminal after install.
Confirm with uv --version.

npm/Node version mismatch

Use Node 20+.
Delete web/node_modules and run npm install --prefix web.

cppcheck or clang-format missing

Install tooling locally, or skip native targets until installed.
CI still enforces native checks.

Web cannot reach API

Confirm API is running on 127.0.0.1:8000.
Verify VITE_API_BASE_URL.
Check CORS origins in STORY_GEN_CORS_ORIGINS if customized.

Keycloak auth issues

Set STORY_GEN_AUTH_MODE=keycloak.
Set STORY_GEN_OIDC_ISSUER to the realm issuer URL.
If JWKS discovery fails, set STORY_GEN_OIDC_JWKS_URL or inline STORY_GEN_OIDC_JWKS_JSON.