cloudinit-bot
a8ec7b80de
---ci--- project: inboxos phase: 1 milestone: v1.4 status: execute wave: 2 tasks: [T3, T4, T5, T6, T7, T8] ---/ci---
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# InboxOS — Operator Tutorial (30-minute walkthrough)
|
|
|
|
A guided tour for the new operator. Read top-to-bottom; each chapter takes ~5-10 minutes.
|
|
|
|
## Chapter 1: Setup (5 min)
|
|
|
|
Goal: get a working InboxOS instance on your laptop.
|
|
|
|
1. Clone the repo: `git clone https://git.cloudinit.dev/jc-capital/inboxos.git && cd inboxos`
|
|
2. Run `scripts/quickstart.sh` (REQ-INB-40). The script pulls Docker images, generates `.env`, brings up the stack, and runs a 1-message smoke test.
|
|
3. Login to NocoDB at http://localhost:8080.
|
|
4. See the 4 module tables in the left-nav: `finance`, `crm`, `intel`, `promotions`.
|
|
|
|
Next: see `docs/operations-runbook.md §3.1` (Live pipeline) for the production setup.
|
|
|
|
## Chapter 2: First run (5 min)
|
|
|
|
Goal: process a real .mbox file end-to-end.
|
|
|
|
1. Get a sample .mbox (or use `tests/fixtures/single.mbox` from the repo).
|
|
2. Run `python pipelines/historical_pipeline.py --mbox /path/to/file.mbox`.
|
|
3. Watch the JSONL events stream to stderr.
|
|
4. In NocoDB, look for the row in the appropriate module table.
|
|
5. Check the 4 curated views (REQ-INB-41) in the left-nav.
|
|
|
|
Next: see `docs/extraction-contract.md` for the prompt contract.
|
|
|
|
## Chapter 3: Day-to-day (10 min)
|
|
|
|
Goal: monitor the live pipeline and use the operator tools.
|
|
|
|
1. The live pipeline runs on `cron */5 * * * *` via `.gitea/workflows/live-pipeline.yml`. Check Gitea Actions for the last run.
|
|
2. Run `scripts/dashboard.py` (REQ-INB-50) for an at-a-glance terminal view.
|
|
3. To find a specific email, use `scripts/find_email.py --mid <Message-ID>` (REQ-INB-43) or `--sender`.
|
|
4. To inspect a recent run in detail, use `scripts/explain_run.py` (REQ-INB-42) or `scripts/explain_run.py --json | jq`.
|
|
5. To see monthly costs, run `scripts/cost_report.py --month 2026-06` (REQ-INB-54).
|
|
|
|
Next: see `docs/operations-runbook.md §4` (Observability).
|
|
|
|
## Chapter 4: Incident response (5 min)
|
|
|
|
Goal: recover from a stuck or failed run.
|
|
|
|
1. If something is broken, start at the ERROR-NN catalog (REQ-INB-46) at `docs/operations-runbook.md §5`.
|
|
2. The 10 ERROR-NN codes map 1:1 to the §5.X subsections.
|
|
3. To replay failed/skipped MIDs, use `scripts/replay.py --status errored --confirm` (REQ-INB-45).
|
|
4. To reclassify a MID into a different module, use `scripts/reclassify.py --mid <MID> --new-module crm --confirm` (REQ-INB-44).
|
|
5. If the smoke test fails on a fresh install, the runbook §5 has the recovery procedure per failure mode.
|
|
|
|
Next: see `docs/operations-runbook.md §5.7` (Backup and restore).
|
|
|
|
## Chapter 5: Hardening (5 min)
|
|
|
|
Goal: understand the v1.4 product-grade security posture.
|
|
|
|
1. Container hardening (REQ-INB-55): all 6 services run with `read_only: true` (or `tmpfs: [/tmp]` for write-required services), `cap_drop: [ALL]`, and `security_opt: no-new-privileges`. See `docker/docker-compose.yml`.
|
|
2. PII-scrub (REQ-INB-57): SSN, credit-card, IBAN, and phone numbers are masked before the email body is sent to Ollama. The audit trail is in `_artifacts/pii_scrub.jsonl`.
|
|
3. Secret redaction (REQ-INB-56): all 9 secret env vars are auto-masked in CI logs via `::add-mask::`.
|
|
4. DPIA (REQ-INB-58): see `docs/security/dpia.md` for the GDPR Art. 35 data protection impact assessment.
|
|
5. Threat model (REQ-INB-59): see `docs/security/threat-model.md` for the STRIDE-per-component decomposition.
|
|
|
|
Next: see `docs/security/dpia.md` and `docs/security/threat-model.md`.
|