ThatAIguyA world of ideas

THE CONSCIOUSNESS ATLAS
Read. Experiment. Follow the evidence.

ConsciousnessLearn · Explore · Joseph Anady

Janady13/missionmatch / docs/RUNBOOK_ONBOARDING.md

Source identity, revision, and recovered contents.

GitHub sourceSource text recovered

Source identity

FieldRecorded value
Source typeGitHub source
Original recordJanady13/missionmatch / docs/RUNBOOK_ONBOARDING.md
DateNot specified in source
RepositoryJanady13/missionmatch
Revision9bde0f9a74b89d01980fa658e5253acda7528d0c
Branchper-tenant-routing
Path or archive memberdocs/RUNBOOK_ONBOARDING.md
Original SHA-2560053d7f07fcfcc8fb9194fc9f39aec4c114737489de661230302ac7b33cf18db
Git blob SHA317b2c612f074d5b4e709cff10e1582e06d09757
Reading-copy SHA-2560053d7f07fcfcc8fb9194fc9f39aec4c114737489de661230302ac7b33cf18db

Original source ↗

Every recorded occurrence

These 3 records contain identical original source bytes. Their paths and revisions remain part of the archive.

Original recordBranch or archiveRevision / identifierOriginal location
Janady13/missionmatch / docs/RUNBOOK_ONBOARDING.mdper-tenant-routing9bde0f9a74b89d01980fa658e5253acda7528d0cOpen original
Janady13/missionmatch / docs/RUNBOOK_ONBOARDING.mddeploy-and-opsbdacd9d0b4d5998d25fc74bf4007f4c3ec538c7aOpen original
Janady13/missionmatch / docs/RUNBOOK_ONBOARDING.mdper-tenant-routing9bde0f9a74b89d01980fa658e5253acda7528d0cOpen original

Recovered source transcript

Download complete source text ↓116 lines · 5.9 KB
# Runbook: onboard a new client under the database per tenant model This is the exact, repeatable sequence to bring a new client live on its own isolated database. It is the flow proven on M4 staging in BUILD_REPORT (Mission A). Run it as the operator. Every step has a rollback. Prerequisites: the platform is in per_tenant mode (`MM_TENANCY=per_tenant`), the control plane database is up and migrated to head, and you have the superuser (admin) DSN and the migrator DSN to the cluster. Conventions used below: - `ADMIN` = a superuser DSN to the maintenance database (CREATE DATABASE plus roles). - `MIG` = the migrator DSN to the maintenance database (the migrations run as the migrator so it owns the tables). - `CP_MIG` = the migrator DSN to the CONTROL PLANE database. - `DBNAME` = the new tenant database name (lowercase identifier, for example `tenant_acme`). - `ORG` = the organization id (a uuid), created in the control plane in step 2. - `REF` = the secret reference stored in the directory (for example `tenant_acme`); it is NOT a credential. ## Step 1: provision the tenant database Creates a fresh, schema identical, isolated database with RLS forced, the eeo schema segregated to the compliance role, vector(384) ready, and the tables owned by the migrator. ``` provision-tenant -admin-dsn "$ADMIN" -migrator-dsn "$MIG" -name "$DBNAME" ``` Verify: the command prints DONE and its own checks (vector column, RLS forced, eeo present, app has no eeo grant). Rollback: `DROP DATABASE "$DBNAME"` (it has no data yet). ## Step 2: create the org and owner in the control plane Identity is authoritative in the control plane (global unique email, sessions, MFA). Create the org and its first owner there, exactly as in shared mode. ``` provision-org -name "Acme Cleared Staffing" -slug acme -owner-email owner@acme.example -owner-name "Acme Owner" ``` Record the printed organization id as `ORG`. Verify: a row exists in `organizations` and `users` in the control plane. Rollback: delete the org and owner from the control plane (no tenant data references them yet). ## Step 3: store the tenant's database credential under the secret reference The directory holds only a reference, never a credential. Store the tenant's APP role DSN (and its COMPLIANCE role DSN) in the configured secrets backend under `REF` and `REF` plus `-compliance`. - env backend (dev and staging): set the root owned environment file so the API resolves them. For `REF=tenant_acme` the keys are upper cased with non identifier characters folded to underscore: ``` MM_TENANT_DSN_TENANT_ACME=postgres://missionmatch_app:[REDACTED, rotated 29 Jul 2026]@<host>:5432/tenant_acme?sslmode=disable MM_TENANT_DSN_TENANT_ACME_COMPLIANCE=postgres://missionmatch_compliance:[REDACTED, rotated 29 Jul 2026]@<host>:5432/tenant_acme?sslmode=disable ``` - government cloud backend (production): put the same two DSNs in AWS Secrets Manager or Azure Key Vault under the names the deploy time adapter resolves from `REF`. Verify: the secret resolves (a dev check is that the env var is set and 0600). Rollback: remove the secret. ## Step 4: register the tenant in the directory (control plane) Map the org to its database. The directory is migrator owned; register with the migrator. ``` psql "$CP_MIG" -v ON_ERROR_STOP=1 -c "INSERT INTO tenant_directory (organization_id, db_name, db_host, db_port, connection_secret_ref, status, cloud) VALUES ('$ORG', '$DBNAME', '<host>', 5432, '$REF', 'provisioning', '<local|aws_govcloud|azure_gov>');" ``` Leave the status `provisioning` for now (the API will not route to it until it is `active`). Verify: `SELECT status FROM tenant_directory WHERE organization_id='$ORG';` returns `provisioning`. Rollback: `DELETE FROM tenant_directory WHERE organization_id='$ORG';`. ## Step 5: seed identity into the tenant database Copy the org and its users from the control plane into the tenant database, so the tenant's business tables can reference them (requirements.created_by, candidate_evaluations.evaluated_by, and so on). ``` sync-tenant-identity -control-dsn "$CP_MIG" -org "$ORG" ``` Re run this whenever a new user is invited and activated for this org. Verify: it prints the org and user count seeded. Rollback: not usually needed (idempotent), but the rows can be deleted from the tenant database if abandoning the onboarding. ## Step 6: load the client's data and embed its vectors Load the client's candidates, requirements, and skills into the tenant database (import tools, a data load, or the client's own ingestion). Then populate that tenant's vectors: ``` embed-backfill -dsn "$MIG_to_tenant" -megamind "$MM_MEGAMIND_URL" -model qllama/bge-small-en-v1.5 -what all -batch 64 ``` where `MIG_to_tenant` is the migrator DSN with the database name set to `$DBNAME`. Verify: the backfill prints the skills and candidate counts embedded. Rollback: the data load is the client's; vectors can be re embedded. ## Step 7: confirm isolation before enabling - The migration head matches: `migrate-all-tenants -check` reports the tenant at head (no pending). - The app role cannot read demographics in this database: `psql <app DSN to tenant> -c "SELECT 1 FROM eeo.candidate_demographics;"` must fail with permission denied. - RLS is forced: a query without the org GUC returns zero candidate rows. If any check fails, do NOT enable. Rollback to step 4 (leave status provisioning) and fix. ## Step 8: enable Flip the directory status to active so the API routes live requests to it. ``` psql "$CP_MIG" -c "UPDATE tenant_directory SET status='active', updated_at=now() WHERE organization_id='$ORG';" ``` Verify: a request authenticated as a user in this org returns the org's own data, and a different org's request never sees it. Rollback (offboard or suspend): set the status back to `suspended` or `offline`, which makes the API refuse to serve the tenant with a typed error while you investigate, then `DROP DATABASE` only after a verified backup if you are decommissioning.

Search equations, builds, manuscript text, and recovered sources.