docs: quickstart for fresh clones + CLAUDE.md #46

Merged

longjacksonle merged 1 commit from docs/quickstart into main

2026-05-28 19:11:57 +02:00

longjacksonle commented

2026-05-28 19:11:05 +02:00

Owner

Summary

Fresh clones cannot follow README's quickstart because .env.dev is gitignored and not in the tree; just dev fails at ensure-env. Adds dev-docs/quickstart.md covering: prereq tooling (docker compose v2 plugin, rustup, sqlx-cli, all installable user-level), the .env.dev seed contents with locally-generated secrets, the 16-byte INFISICAL_ENCRYPTION_KEY trap (32 bytes crashes Infisical's boot migration with RangeError: Invalid key length), the Infisical bootstrap one-off, and the routine just commands.

Also lands CLAUDE.md so future Claude Code sessions pick up the dual-auth layout (legacy HS256 + mokosh-auth OIDC subsystem in crates/), the ad-hoc multi-tenancy enforcement (no middleware-level scoping; every service method threads tenant_id itself), and the 14-of-18 stub-module status without re-reading dev-docs/codebase-state.md from scratch.

Files

dev-docs/quickstart.md (new)
dev-docs/README.md (index row pointing at quickstart)
CLAUDE.md (new)

Test plan

Followed the doc end-to-end on a fresh clone. Stack came up; GET /api/v1/health returns OK; POST /api/v1/auth/login with admin@example.com / devpassword12 returns a super_admin access token.
Reviewer eyeball on defaults committed in the seed file: ports 4301/5433/28002/8025, placeholder Google OAuth credentials, 16-byte INFISICAL_ENCRYPTION_KEY length. Push back if any of those should differ from what the rest of the team uses.

## Summary Fresh clones cannot follow README's quickstart because `.env.dev` is gitignored and not in the tree; `just dev` fails at `ensure-env`. Adds `dev-docs/quickstart.md` covering: prereq tooling (`docker compose` v2 plugin, rustup, sqlx-cli, all installable user-level), the `.env.dev` seed contents with locally-generated secrets, the 16-byte `INFISICAL_ENCRYPTION_KEY` trap (32 bytes crashes Infisical's boot migration with `RangeError: Invalid key length`), the Infisical bootstrap one-off, and the routine `just` commands. Also lands `CLAUDE.md` so future Claude Code sessions pick up the dual-auth layout (legacy HS256 + `mokosh-auth` OIDC subsystem in `crates/`), the ad-hoc multi-tenancy enforcement (no middleware-level scoping; every service method threads `tenant_id` itself), and the 14-of-18 stub-module status without re-reading `dev-docs/codebase-state.md` from scratch. ## Files - `dev-docs/quickstart.md` (new) - `dev-docs/README.md` (index row pointing at quickstart) - `CLAUDE.md` (new) ## Test plan - [x] Followed the doc end-to-end on a fresh clone. Stack came up; `GET /api/v1/health` returns `OK`; `POST /api/v1/auth/login` with `admin@example.com` / `devpassword12` returns a `super_admin` access token. - [ ] Reviewer eyeball on defaults committed in the seed file: ports `4301`/`5433`/`28002`/`8025`, placeholder Google OAuth credentials, 16-byte `INFISICAL_ENCRYPTION_KEY` length. Push back if any of those should differ from what the rest of the team uses.

longjacksonle added 1 commit

2026-05-28 19:11:05 +02:00

docs: add quickstart for fresh clones, plus CLAUDE.md

Check / fmt + clippy + compile + tests (pull_request) Successful in 29s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

a05771affc

A fresh clone cannot follow README's quickstart because `.env.dev` is gitignored and not checked in; running `just dev` fails at the `ensure-env` step. Captures the seed file contents (with random JWT/encryption secrets generated locally), flags the 16-byte INFISICAL_ENCRYPTION_KEY trap (32 bytes crashes Infisical's boot migration with "Invalid key length"), documents the Mailpit/Postgres ports and Infisical bootstrap one-off, and lists the routine `just` commands for day-to-day work.

Also adds CLAUDE.md for future Claude Code sessions so they pick up the dual-auth (legacy HS256 + mokosh-auth OIDC) layout, multi-tenancy gotcha (no middleware-level scoping), and the fact that 14 of 18 modules are HTTP 501 stubs without re-reading dev-docs from scratch.

- dev-docs/quickstart.md: new
- dev-docs/README.md: index row
- CLAUDE.md: new

Signed-off-by: David Randall <David@NiceGuyIT.biz>