89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# Demo runbook
|
||
|
||
## Starting the demo (any environment)
|
||
|
||
Open the deployed URL (Unraid review: `http://192.168.10.150:1236`; local:
|
||
`http://localhost:1228`). The login screen names the fictional organisation, states that
|
||
all data is synthetic and all workflows are really implemented, and offers:
|
||
|
||
- **Start begeleide demo** — logs in as Operations Manager and opens the Demo Guide at
|
||
step 1.
|
||
- **Verken als Operations Manager** / **Verken als Rental Employee** — free exploration,
|
||
no guide.
|
||
|
||
No password is shown or required for either path.
|
||
|
||
## Five-minute demo (guided)
|
||
|
||
1. Click **Start begeleide demo**.
|
||
2. Follow steps 1–3: dashboard → the booking needing attention → confirm the pre-filled
|
||
odometer-anomaly return.
|
||
3. Step 4: resolve the data-quality issue the return just created (any decision is fine
|
||
for a quick pass — "Retain canonical" is the fastest).
|
||
4. Step 6: ask a suggested knowledge question and show the cited source.
|
||
5. Step 7: show the automation/audit trail link-through.
|
||
6. Close with step 8, the About page's honest real/synthetic/not-connected breakdown.
|
||
|
||
## Ten-minute demo (guided + one extra scenario)
|
||
|
||
Do the five-minute path above, then from `/scenarios`:
|
||
|
||
- Run **scenario 2** (duplicate customer merge) if not already done via the guide's own
|
||
step 5.
|
||
- Run **scenario 3** (booking overlap) — `/data-quality`, resolve `DQ-DEMO-OVERLAP`.
|
||
- Run **scenario 4** (failed automation retry) — `/automation`, filter to failed, retry.
|
||
|
||
All five scenarios can be run in any order and are independent of each other.
|
||
|
||
## Resetting the environment
|
||
|
||
Any Operations Manager can reset from: the sidebar ("Reset demo data"), the Demo Guide
|
||
panel ("Demo opnieuw voorbereiden"), or the About page (points to the sidebar control).
|
||
Reset requires confirmation, rebuilds the deterministic dataset with a fresh date anchor,
|
||
runs a server-side scenario-integrity check, and signs the acting session out (the server
|
||
invalidates the session as part of reset). It only ever touches MobilityOps's own tables
|
||
— never shared n8n, RAGcore, or MCP data, other containers, or volumes. It can be
|
||
disabled entirely via `DEMO_ALLOW_RESET=false` if an environment must not be rebuildable.
|
||
|
||
## Redeploying to Unraid
|
||
|
||
```bash
|
||
# From a clean local checkout on the exact commit:
|
||
git archive --format=tar.gz -o /tmp/mobilityops-source.tar.gz HEAD
|
||
sha256sum /tmp/mobilityops-source.tar.gz
|
||
scp /tmp/mobilityops-source.tar.gz unraid:/mnt/user/appdata/mobilityops/.deploy/
|
||
ssh unraid "/mnt/user/appdata/mobilityops/deploy/unraid/deploy-release.sh \
|
||
/mnt/user/appdata/mobilityops/.deploy/mobilityops-source.tar.gz \
|
||
<archive-sha256> <full-git-sha>"
|
||
```
|
||
|
||
The deployer verifies the archive checksum, extracts into a new commit-named release
|
||
directory, builds revision-labelled immutable images, promotes without reseeding, and
|
||
checks application, backup and observability health. Reset demo data only as a separate,
|
||
deliberate demo-preparation action.
|
||
|
||
## Rollback
|
||
|
||
`.deploy/source-revision` and `.deploy/release-history.log` record the live commit and
|
||
image tags. A failed readiness check automatically restores the previous image IDs.
|
||
Database rollback remains a separate, explicitly guarded restore operation.
|
||
|
||
## Server safety (Unraid)
|
||
|
||
Only touch the `mobilityops` Compose project's own `api`/`web` services (and `db` only
|
||
via migrations, never manually). Never stop other containers, run `docker system prune`,
|
||
delete unrecognised images/networks/volumes, delete the MobilityOps database, overwrite
|
||
the server `.env`, print secrets, start a second permanent n8n instance, or activate
|
||
guessed RAGcore/MCP URLs. PostgreSQL is never exposed externally.
|
||
|
||
## Troubleshooting
|
||
|
||
- **A scenario shows "Niet beschikbaar" on `/scenarios`**: it has already been resolved
|
||
since the last reset (expected once you've worked through it) — reset to restore it.
|
||
- **Knowledge question returns "insufficient evidence"**: use a suggested question in
|
||
NL, EN or FR and inspect provider health/citations; the adapter refuses ungrounded
|
||
answers when RAGcore is slow, unavailable or lacks evidence.
|
||
- **n8n shows a failed delivery that isn't the seeded demo one**: check `/automation`'s
|
||
filter and retry — bounded retries mean it should self-heal within
|
||
`n8n_max_attempts` attempts, or can be retried manually by an Operations Manager.
|