From 042e205227163dcac5baa1a3f85f14632d9da0ba Mon Sep 17 00:00:00 2001 From: tocmo0nlord Date: Tue, 2 Jun 2026 11:52:32 +0000 Subject: [PATCH] =?UTF-8?q?Add=20GO=5FLIVE=5FRUNBOOK.md=20=E2=80=94=20prod?= =?UTF-8?q?uction=20deployment=20runbook=20for=20activeblue=5Ffamilylaw=5F?= =?UTF-8?q?v2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Environment-specific runbook covering: pre-flight checklist (incl. the non-code launch-blockers from CLAUDE.md §11), db1 backup, staging, install (Apps UI + CLI methods), post-install verification (matches the dry-run checks), system-parameter configuration (Claude / CourtListener / DocuSeal keys + which features each unlocks), the two-gate guarantees, rollback/uninstall via pre-install dump, and known non-blocking follow-ups. Coexistence with the legacy module documented throughout. Co-Authored-By: Claude Opus 4.8 --- GO_LIVE_RUNBOOK.md | 227 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 GO_LIVE_RUNBOOK.md diff --git a/GO_LIVE_RUNBOOK.md b/GO_LIVE_RUNBOOK.md new file mode 100644 index 0000000..6605d1f --- /dev/null +++ b/GO_LIVE_RUNBOOK.md @@ -0,0 +1,227 @@ +# Go-Live Runbook — `activeblue_familylaw_v2` + +Deploying the Active Blue Family Law platform (Odoo 18 Community module +`activeblue_familylaw_v2`, version `18.0.14.0.0`) into production. + +This runbook is environment-specific to the current prod stack and assumes the build +state already verified: **200 tests green in live Odoo 18**, module **staged** in the +prod addons path, and a **clean dry-run install on a clone of `db1`** with the legacy +module untouched. See `BUILD_STATUS.md` for verification details. + +> **Coexistence guarantee.** Prod already runs a *different, legacy* module named +> `activeblue_familylaw` (models `fl.*`, real data). This module is +> `activeblue_familylaw_v2` with `familylaw.*` models and its own security groups, so it +> installs **alongside** the legacy app. Verified on a `db1` clone: installing `_v2` +> left the legacy module installed and its `fl.*` data intact. + +--- + +## 0. Environment reference (current prod) + +| Thing | Value | +|---|---| +| Odoo web container | `odoo-web-1` (image `odoo:18.0`, `workers=0`) | +| Postgres container | `odoo-db-1` (image `postgres:16`) | +| Production database | `db1` | +| DB host / user (from prod env) | `db` / `odoo` (password in the container env — not in this doc) | +| Docker network | `odoo_default` | +| Addons path (host → container) | `/root/odoo/odoo-ai/addons` → `/mnt/extra-addons` | +| Config (host → container) | `/root/odoo/config` → `/etc/odoo` | +| Module location (staged) | `/root/odoo/odoo-ai/addons/activeblue_familylaw_v2` | + +Other modules on the path: `activeblue_ai` (unrelated), `activeblue_familylaw` (legacy). + +--- + +## 1. Pre-flight checklist + +**Code / install (all ✅ as of this runbook):** +- [x] Steps 1–14 implemented; `python3 scripts/validate_module.py` passes. +- [x] Full suite green in live Odoo 18 (`--test-tags familylaw` → 200/0/0). +- [x] Module staged in prod addons path. +- [x] Dry-run install on a `db1` clone: clean, legacy intact. + +**Non-code LAUNCH-BLOCKERS — do NOT run a real client matter until these are closed** +(see `CLAUDE.md` §11; #1–#6 gate the venture, and most are not coding tasks): +- [ ] **Named, engaged, licensed Florida family-law attorney** who validates the legal + logic and is the reviewing/signing attorney. +- [ ] **Ownership/business model** settled (no nonlawyer firm ownership / fee-split). +- [ ] **Malpractice insurance** contemplating AI-assisted work. +- [ ] **Engagement-letter framework** with an AI-disclosure clause. +- [ ] **Security review + breach-response plan** (privileged data; internet-facing + DocuSeal host). +- [ ] **UPL guardrails** for the non-lawyer operator (no legal positions to clients). +- [ ] **Legal content validated** for the Tier-3 pieces; `VERIFY`-flagged volatile + values confirmed (deadline day-counts, $50k 12.902(b)/(c) threshold, 15%/$50 + modification presumption, Rule 12.410 subpoena (eff. 2025-10-01), AO 14-13, + retention periods). + +> Installing the software is safe and reversible. **Operating it on a real matter is +> what the blockers above govern.** You can install and configure now; gate real use +> behind the attorney. + +--- + +## 2. Back up `db1` first (always) + +```bash +# Custom-format dump (fast restore); writes inside the db container, then copy out. +docker exec odoo-db-1 sh -c "pg_dump -U odoo -Fc db1 -f /tmp/db1_preinstall_$(date +%F).dump" +docker cp odoo-db-1:/tmp/db1_preinstall_$(date +%F).dump ./ +# also snapshot the filestore volume if you keep attachments on disk +# (volume: odoo_odoo-web-data → /var/lib/odoo) +``` +Keep the dump until the install is confirmed good. + +--- + +## 3. Stage the module (already done) + +The folder is already at `/root/odoo/odoo-ai/addons/activeblue_familylaw_v2`. If +re-staging from the repo: +```bash +docker cp activeblue_familylaw_handoff/activeblue_familylaw_build/activeblue_familylaw_v2 \ + odoo-web-1:/mnt/extra-addons/ +# optional: consistent ownership with the other modules (run on the HOST as root) +sudo chown -R root:root /root/odoo/odoo-ai/addons/activeblue_familylaw_v2 +``` +Files only — staging never installs or touches a database. + +--- + +## 4. Install into `db1` + +Pick ONE method. + +### Method A — Apps UI (recommended, no downtime) +1. Log into prod Odoo as an administrator. +2. **Apps → Update Apps List** (this refreshes `ir.module.module`; installs nothing). +3. Remove the "Apps" filter, search **"Active Blue Family Law v2"**. +4. Click **Activate / Install**. + +### Method B — CLI (requires stopping the web container to avoid two Odoo processes on `db1`) +```bash +docker stop odoo-web-1 +docker run --rm --network odoo_default \ + -e HOST=db -e PORT=5432 -e USER=odoo -e PASSWORD= \ + -v /root/odoo/odoo-ai/addons:/mnt/extra-addons:ro \ + -v /root/odoo/config:/etc/odoo:ro \ + odoo:18.0 \ + odoo -d db1 -i activeblue_familylaw_v2 --stop-after-init --no-http +docker start odoo-web-1 +``` +> Do **not** run Method B while `odoo-web-1` is up — two processes installing on the +> same DB can corrupt state. + +The module depends only on `base`, `mail`, `calendar` (all standard) — no OCA deps. + +--- + +## 5. Post-install verification + +```bash +# module states — v2 installed, legacy untouched +docker exec odoo-db-1 psql -U odoo -d db1 -tc \ + "SELECT name,state,latest_version FROM ir_module_module + WHERE name IN ('activeblue_familylaw','activeblue_familylaw_v2') ORDER BY name;" + +# legacy data still intact (spot check) +docker exec odoo-db-1 psql -U odoo -d db1 -tAc "SELECT count(*) FROM fl_caselaw;" + +# v2 artifacts created +docker exec odoo-db-1 psql -U odoo -d db1 -tAc \ + "SELECT count(*) FROM ir_model WHERE model LIKE 'familylaw.%';" # expect 30 +docker exec odoo-db-1 psql -U odoo -d db1 -tAc \ + "SELECT count(*) FROM ir_model_data + WHERE module='activeblue_familylaw_v2' AND model='res.groups';" # expect 2 +docker exec odoo-db-1 psql -U odoo -d db1 -tAc \ + "SELECT to_regclass('public.familylaw_case') IS NOT NULL;" # expect t +``` +Expected (matches the dry run): `activeblue_familylaw_v2 installed 18.0.14.0.0`, +`activeblue_familylaw installed 18.0.1.0.0`, 30 `familylaw.*` models, 2 groups, +2 crons (overdue-deadline + retention), `familylaw_case` table present. + +**UI smoke test (5 min):** +1. **Family Law (v2) → New Intake** → run a standard child-support-modification intake + → confirms a draft case + initial proceeding are created; conflict screening runs. +2. Open the case → assign attorney → **Clear Conflict Check** (attorney only) → + **Engage**. +3. **Documents** → create a manual doc → confirm it cannot be filed until approved + (Gate 1). +4. Assign two security groups to a test staff user and a test attorney user; confirm + staff see only assigned matters (matter-scoped access). + +--- + +## 6. Configuration (after install) + +Set as **System Parameters** (Settings → Technical → System Parameters), readable by +the attorney group only. Without these, the AI / verification / e-signature features +are **inert but harmless** — the spine (intake, cases, deadlines, disclosure, +documents, the gates) works fully without them. + +| Key | Purpose | Needed for | +|---|---|---| +| `familylaw.anthropic_api_key` | Claude API key | AI drafting/research (Steps 6/7/9) | +| `familylaw.model` | pinned model id (default `claude-sonnet-4-6`) | AI tasks | +| `familylaw.token_ceiling` | per-task max_tokens (default 4096) | AI cost cap | +| `familylaw.anthropic_endpoint` | override (default `api.anthropic.com/v1/messages`) | AI tasks | +| `familylaw.courtlistener_token` | CourtListener API token | citation verification (Gate 2) | +| `familylaw.courtlistener_endpoint` | override default v4 citation-lookup URL | citation verification | +| `familylaw.docuseal_url` | DocuSeal **Pro** base URL | e-signature (Step 11) | +| `familylaw.docuseal_api_key` | DocuSeal API token | e-signature | +| `familylaw.docuseal_template_id` | default template | e-signature | +| `familylaw.docuseal_webhook_secret` | shared secret for the webhook | e-signature callbacks | + +**DocuSeal note:** the API needs **DocuSeal Pro (~$200/yr)**, and its signing host must +be **internet-facing + isolated/hardened** (its Postgres not exposed). Webhook endpoint: +`POST /familylaw/docuseal/webhook` (set `X-Docuseal-Secret` to the shared secret). + +**The two sacred gates work regardless of config:** +- Gate 1 (review) — AI/draft docs born unapproved; only an attorney approves; nothing + files/sends unapproved. +- Gate 2 (citation) — citations born unverified; verification fails CLOSED (down / + no-record ⇒ stays blocked); filing blocked on any unverified cite. + +--- + +## 7. Rollback / uninstall + +If anything looks wrong, the fastest clean rollback is the pre-install dump: +```bash +# restore db1 from the backup (DESTRUCTIVE: drops current db1) +docker stop odoo-web-1 +docker exec odoo-db-1 psql -U odoo -d postgres -c "DROP DATABASE db1;" +docker exec odoo-db-1 psql -U odoo -d postgres -c "CREATE DATABASE db1 OWNER odoo;" +docker cp ./db1_preinstall_.dump odoo-db-1:/tmp/restore.dump +docker exec odoo-db-1 pg_restore -U odoo -d db1 /tmp/restore.dump +docker start odoo-web-1 +``` +Alternative (no restore): **Apps → Active Blue Family Law v2 → Uninstall**. Because the +module is isolated (`familylaw.*` models, own groups), uninstalling removes only its +tables/records and leaves the legacy app intact. The pre-install dump is still the +safest path. + +To remove the staged files: `rm -rf /root/odoo/odoo-ai/addons/activeblue_familylaw_v2` +(host, as root) — only after it is uninstalled from `db1`. + +--- + +## 8. Known follow-ups (non-blocking) + +- **Tier-3 legal content is unvalidated** until the attorney signs off (Steps 6/7/9). + Build is structural; do not present its legal reasoning as authoritative. +- **Failed-AI-call logging** is durable via an independent transaction; the in-flight + `running` task row still rolls back on failure (one durable `failed` row results). +- **Legacy `activeblue_familylaw` data** (`fl.*`: ~174 support-schedule entries, 26 + statutes, 25 caselaw, etc.) is *not* migrated into `_v2`. If any is worth carrying + over, do a separate data-migration pass — it is orthogonal to this install. +- **Real external integrations** (CourtListener coverage for FL DCA/Supreme Court, + Claude prompts/evals, DocuSeal Pro host) per `CLAUDE.md` §11 #8–#10. + +--- + +## 9. One-line summary for the change log + +> Installed `activeblue_familylaw_v2` 18.0.14.0.0 on `db1` (coexists with legacy +> `activeblue_familylaw`; pre-install dump taken; post-install checks green).