tocmo0nlord/famlaw_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add GO_LIVE_RUNBOOK.md — production deployment runbook for activeblue_familylaw_v2

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
tocmo0nlord
2026-06-02 11:52:32 +00:00
parent 935394620b
commit 042e205227
1 changed files with 227 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
GO_LIVE_RUNBOOK.md Normal file
View File

@@ -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=<db_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_<DATE>.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).