62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# Onboarding Walkthrough (90 seconds)
|
|
|
|
A scripted demo that takes a fresh clone to a running dev server with a logged-in admin in 90 seconds, recorded once and embedded as an [asciinema](https://asciinema.org/) cast in the README. The script below doubles as a manual sanity check after every major release.
|
|
|
|
## Recording the cast
|
|
|
|
```sh
|
|
# 1. Install asciinema (one-time)
|
|
brew install asciinema # or: pipx install asciinema
|
|
|
|
# 2. Start a clean recording in a fresh terminal session
|
|
asciinema rec docs/assets/onboarding.cast \
|
|
--title "Boilerplate onboarding: clone to logged-in admin in 90s" \
|
|
--command 'bash docs/scripts/onboarding-walkthrough.sh'
|
|
|
|
# 3. Upload (optional, for embedding)
|
|
asciinema upload docs/assets/onboarding.cast
|
|
```
|
|
|
|
Cast files are tracked in git as plain JSON; binary terminal output is not committed.
|
|
|
|
## The 90-second script
|
|
|
|
The recording follows this exact sequence so the timings match the README claim:
|
|
|
|
| t (s) | Action | Expected output |
|
|
| --- | --- | --- |
|
|
| 0-5 | `pnpm install` (assumes a warm pnpm cache; on a cold cache add ~60s) | `Done in 5s` |
|
|
| 5-10 | `cp .env.example .env` + open `.env` and set `SESSION_SECRET`, `CRYPTO_SECRET`, `DATABASE_URL` | three new key/value pairs |
|
|
| 10-30 | `pnpm exec prisma migrate dev --skip-seed` | "All migrations have been successfully applied" |
|
|
| 30-45 | `SEED_DEMO_DATA=true pnpm seed` | "Seed completed" |
|
|
| 45-50 | `pnpm run permissions:sync` | "Role permissions in sync" |
|
|
| 50-55 | `pnpm dev` (background) | "Local: http://localhost:3000" |
|
|
| 55-70 | Open `http://app.localhost:3000` in browser; login as `admin@email.com` / `password` | tenant dashboard |
|
|
| 70-90 | Tour: tenant switcher, settings, create a row, observe i18n DE/EN switch | feature breadth visible |
|
|
|
|
## Speaking outline (for a screen-cast voiceover)
|
|
|
|
> "This is the ToolCTRL boilerplate. One command installs dependencies, one applies migrations, one seeds demo data. Sixty seconds later we have a multi-tenant SaaS shell with two demo tenants, two demo users, full i18n in German and English, a built-in audit log, and the admin surface on a separate host. The whole thing is RR7-server-rendered, with Pino structured logging, a hardened Docker stack that drops to non-root, an SBOM in every image, and 30+ verify gates protecting the contract you fork from."
|
|
|
|
## Embedding in README
|
|
|
|
The README's "Installation" section already links to this walkthrough. After uploading the cast, add the asciinema badge:
|
|
|
|
```md
|
|
[](https://asciinema.org/a/<id>)
|
|
```
|
|
|
|
placed between sections 4 (env setup) and 5 (database setup).
|
|
|
|
## Failure modes the walkthrough also exposes
|
|
|
|
If any of the following surface during the recording, fix them before pushing the cast — the walkthrough is also a release health check:
|
|
|
|
- `pnpm install` takes >2 minutes on warm cache → lockfile bloat
|
|
- `prisma migrate dev` fails → missing shadow database privilege
|
|
- `pnpm seed` fails → SEED_DEMO_DATA contract regression
|
|
- Login flow does not land on tenant dashboard → tenant-context regression
|
|
- DE/EN switch leaves untranslated strings → i18n parity drift
|
|
|
|
When the recording is clean, the boilerplate is genuinely shippable.
|