NuklearRabbit
108b5d04fc
Automated migrations on container startup (backend/entrypoint.sh), scripted n8n workflow activation (make n8n-setup), Playwright E2E test covering the full 9-step demo script (verified passing against the live stack, including the previously-unverified 360px responsive layout), evidence screenshots of all main pages, architecture diagram, and artifacts/evidence/final-summary.md with commit/commands/test counts/RAGcore and n8n evidence/MCP sample calls/known limitations/portfolio wording. Verified the complete clean-checkout path from a genuinely wiped-volumes state: automatic migrations, seed, 66 backend tests passing, and a live S1 return round-tripped through a freshly-activated n8n instance. Added .gitattributes to force LF line endings on shell scripts, preventing a real cross-platform breakage of entrypoint.sh's shebang.
88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# PoC runbook
|
||
|
||
## Bootstrap (clean checkout)
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
make demo
|
||
```
|
||
|
||
`make demo` runs `docker compose up --build -d` (migrations run automatically on API
|
||
container startup, see `backend/entrypoint.sh`) and then seeds the deterministic dataset.
|
||
Equivalently, without `make`:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
docker compose up --build -d
|
||
docker compose exec api python -m app.cli seed --reset
|
||
```
|
||
|
||
Verify:
|
||
|
||
```bash
|
||
curl http://localhost:8128/health # {"status":"ok",...}
|
||
curl -o /dev/null -w "%{http_code}\n" http://localhost:1228/ # 200
|
||
docker compose run --rm api pytest -q # all tests pass
|
||
docker compose run --rm api ruff check . # clean
|
||
```
|
||
|
||
## n8n automation (one-time per environment)
|
||
|
||
The n8n image used here (n8nio/n8n:latest, 2.x) requires an owner account before any
|
||
workflow — including webhook registration — works reliably; `N8N_BASIC_AUTH_ACTIVE` no
|
||
longer gates this. This is a one-time step per fresh `docker compose down -v`:
|
||
|
||
1. Open `http://localhost:5678/setup` and create an owner account (any email/password
|
||
meeting the 8+ characters / 1 number / 1 capital rule — no email verification is
|
||
required). Skip the optional survey/license-key dialogs that follow.
|
||
2. Import and activate the return-processing workflow:
|
||
|
||
```bash
|
||
make n8n-setup
|
||
```
|
||
|
||
which runs:
|
||
|
||
```bash
|
||
docker compose exec n8n n8n import:workflow --input=//imports/mobilityops-return-processing.json
|
||
docker compose exec n8n n8n publish:workflow --id=mobilityops-return-processing
|
||
docker compose restart n8n
|
||
```
|
||
|
||
(`n8n import:workflow` always leaves the workflow deactivated regardless of its
|
||
`"active"` field; `publish:workflow` + a restart is what actually activates it.)
|
||
|
||
Verify the full round trip:
|
||
|
||
```bash
|
||
# after logging in and registering any return via the UI or API
|
||
curl -b cookies.txt http://localhost:8128/api/v1/workflows | grep succeeded
|
||
```
|
||
|
||
A failed/offline n8n does not roll back the return — the outbox event simply stays
|
||
`pending`/`failed` and is safely retryable from the Automation page.
|
||
|
||
## Required operational checks
|
||
|
||
- API and web health (`GET /health`, web root `200`);
|
||
- database migration level (`docker compose exec api alembic current`);
|
||
- pending/failed outbox count (Automation page, or `GET /api/v1/workflows?status=failed`);
|
||
- RAGcore provider state (`GET /api/v1/knowledge/status`; demo provider is always
|
||
`available`, RAGcore adapter reports `unavailable` when unreachable);
|
||
- n8n connectivity (`docker compose logs n8n`, or submit a return and watch `/automation`);
|
||
- MCP provider endpoint authorization (`curl` the four `/api/v1/integrations/mcp/*`
|
||
routes with and without a valid `X-Service-Token` — see
|
||
`artifacts/evidence/final-summary.md` for sample calls);
|
||
- deterministic demo reset (`POST /api/v1/demo/reset` as Operations Manager, or `make seed`).
|
||
|
||
## Recovery expectations
|
||
|
||
- database restart: application reconnects (SQLAlchemy connection pool, `pool_pre_ping=True`);
|
||
- n8n outage: events remain `pending` and are retried with exponential backoff, then
|
||
`failed` after 5 attempts and safely retryable from `/automation`;
|
||
- RAGcore outage: `/knowledge` shows `unavailable`, all operational pages continue working;
|
||
- MCP Hub outage: the web application is unaffected — MCP endpoints are a separate,
|
||
independently-authenticated API surface;
|
||
- failed demo experiment: Operations Manager reset (`POST /api/v1/demo/reset`) restores
|
||
the deterministic seed, including all named S1–S6 demo scenarios.
|