205 lines
7.3 KiB
Markdown
205 lines
7.3 KiB
Markdown
# Control Plane (MT-0 → MT-3)
|
|
|
|
Tenant registry, plans, domains, provisioning state, and superadmin accounts
|
|
for multi-tenant JQC. Self-contained and decoupled from `app/` — imports
|
|
nothing from the data-plane application.
|
|
|
|
See `../MULTI_TENANT_PLAN.md` for the full phased roadmap.
|
|
|
|
## Layout
|
|
|
|
```
|
|
control/
|
|
├── __init__.py # package docs
|
|
├── base.py # ControlBase + engine/session (CONTROL_DATABASE_URL)
|
|
├── crypto.py # Fernet encrypt/decrypt for tenant DB passwords (CONTROL_FERNET_KEY)
|
|
├── time_utils.py # now_eastern() mirror (no app import)
|
|
├── models.py # Plan, PlanFeature, Tenant, TenantDomain,
|
|
│ # Superadmin, ProvisioningJob, TenantAudit
|
|
├── seed.py # idempotent baseline-plan seeder (Free/Starter/Pro/Enterprise)
|
|
├── cli.py # seed / create-superadmin / list-plans
|
|
├── tenant_migrate.py # MT-2 — upgrade_tenant / bootstrap_tenant / chain_head + CLI
|
|
├── provision.py # MT-3 — create_tenant / register_tenant_zero / delete_tenant + CLI
|
|
└── migrations/ # standalone Alembic chain (control{N}_…)
|
|
└── versions/
|
|
└── control0001_init.py ← HEAD (7 tables)
|
|
```
|
|
|
|
## Environment variables
|
|
|
|
All must live in `/etc/jqc/control.env` (see §3 below). Never hard-code.
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `CONTROL_DATABASE_URL` | e.g. `mysql+pymysql://jqc_control:pw@127.0.0.1/jqc_control` |
|
|
| `CONTROL_FERNET_KEY` | Fernet key for encrypting tenant DB passwords. Generate once, never rotate without re-encrypting all tenant rows. |
|
|
| `PROVISION_DB_URL` | MySQL account with `CREATE DATABASE` / `CREATE USER` / `GRANT` rights. |
|
|
| `TENANT_BASE_DOMAIN` | Apex for subdomains, e.g. `jqc.app`. Builds `<slug>.jqc.app`. |
|
|
|
|
Generate a Fernet key (run once, store permanently):
|
|
|
|
```bash
|
|
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
|
```
|
|
|
|
## Canonical env file (required — prevents Fernet key mismatch)
|
|
|
|
The `CONTROL_FERNET_KEY` used at provisioning time must be identical to the key
|
|
the running app uses to decrypt tenant creds. A mismatch causes
|
|
`cryptography.fernet.InvalidToken` at request time. One file prevents this:
|
|
|
|
```bash
|
|
# /etc/jqc/control.env (chmod 640, chown root:jqc)
|
|
CONTROL_DATABASE_URL=mysql+pymysql://jqc_control:<pw>@127.0.0.1/jqc_control
|
|
CONTROL_FERNET_KEY=<key — no quotes, no trailing space>
|
|
PROVISION_DB_URL=mysql+pymysql://jqc_provisioner:<pw>@127.0.0.1/
|
|
TENANT_BASE_DOMAIN=jqc.app
|
|
MULTI_TENANT_ENABLED=true
|
|
```
|
|
|
|
```ini
|
|
# systemd unit [Service]
|
|
EnvironmentFile=/etc/jqc/control.env
|
|
```
|
|
|
|
```bash
|
|
# any CLI session that provisions tenants
|
|
set -a; . /etc/jqc/control.env; set +a
|
|
```
|
|
|
|
## MySQL accounts required
|
|
|
|
```sql
|
|
-- Control DB user
|
|
CREATE DATABASE jqc_control CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
CREATE USER 'jqc_control'@'localhost' IDENTIFIED BY '<pw>';
|
|
GRANT ALL PRIVILEGES ON jqc_control.* TO 'jqc_control'@'localhost'; FLUSH PRIVILEGES;
|
|
|
|
-- Provisioner (creates per-tenant DBs + users)
|
|
CREATE USER 'jqc_provisioner'@'localhost' IDENTIFIED BY '<pw>';
|
|
GRANT ALL PRIVILEGES ON *.* TO 'jqc_provisioner'@'localhost' WITH GRANT OPTION;
|
|
GRANT CREATE USER ON *.* TO 'jqc_provisioner'@'localhost'; FLUSH PRIVILEGES;
|
|
```
|
|
|
|
## Bootstrap — MT-0 (run once per environment)
|
|
|
|
```bash
|
|
set -a; . /etc/jqc/control.env; set +a
|
|
|
|
# 1. Apply control schema (7 tables)
|
|
alembic -c control/migrations/alembic.ini upgrade head
|
|
|
|
# 2. Seed Free / Starter / Pro / Enterprise plans
|
|
python -m control.cli seed
|
|
|
|
# 3. First superadmin
|
|
python -m control.cli create-superadmin --username admin --email you@example.com
|
|
|
|
# Verify
|
|
alembic -c control/migrations/alembic.ini current # → control0001_init (head)
|
|
python -m control.cli list-plans # → 4 plans
|
|
```
|
|
|
|
## Tenant-zero — register existing LT in place (MT-3)
|
|
|
|
No DB creation, no data movement, no schema changes to the live LT database.
|
|
|
|
```bash
|
|
python -m control.provision register-tenant-zero \
|
|
--slug lts --name "LT Services" --plan enterprise \
|
|
--db-host 127.0.0.1 \
|
|
--db-name <LT_DATABASE_NAME> \
|
|
--db-user <LT_DB_USER> \
|
|
--db-password '<LT_DB_PASSWORD>' \
|
|
--custom-domain jqc.ltservicesinc.com \
|
|
--base-domain jqc.app
|
|
```
|
|
|
|
Output includes `alembic_head` (read from the existing `alembic_version` table)
|
|
and both domain mappings (`lts.jqc.app` + `jqc.ltservicesinc.com` as verified).
|
|
|
|
## Provisioning a new tenant (MT-3)
|
|
|
|
```bash
|
|
python -m control.provision create-tenant \
|
|
--slug acme \
|
|
--name "Acme Corp" \
|
|
--plan pro \
|
|
--admin-email ops@acme.com \
|
|
--base-domain jqc.app
|
|
```
|
|
|
|
Steps executed automatically:
|
|
1. `CREATE DATABASE jqc_acme` + `CREATE USER jqc_acme_u` + `GRANT` (scoped to that DB)
|
|
2. Insert `tenants` row with Fernet-encrypted password
|
|
3. `bootstrap_tenant()` → baseline schema + `stamp head` (phase migrations skipped)
|
|
4. Insert first admin into tenant DB with a set-password token
|
|
5. Register `acme.jqc.app` (verified) + optional custom domain (unverified)
|
|
6. Set tenant `status = active`
|
|
|
|
Output includes the **admin setup link** — send to the admin's email:
|
|
`https://acme.jqc.app/customers/set-password/<token>`
|
|
|
|
On failure, a best-effort rollback drops the DB/user and removes the tenant row
|
|
so a retry starts clean.
|
|
|
|
## Per-tenant migrations (MT-2)
|
|
|
|
```bash
|
|
# New fresh DB (empty → full schema + stamp head; phase migrations skipped)
|
|
python -m control.tenant_migrate bootstrap --tenant acme
|
|
|
|
# Incremental upgrade (phase33+ — must be INFORMATION_SCHEMA-guarded)
|
|
python -m control.tenant_migrate upgrade --tenant all
|
|
python -m control.tenant_migrate upgrade --tenant acme # by slug
|
|
python -m control.tenant_migrate upgrade --tenant 3 # by id
|
|
|
|
# Status check
|
|
python -m control.tenant_migrate current --tenant all
|
|
python -m control.tenant_migrate heads
|
|
```
|
|
|
|
**Rule:** every new migration (phase33+) MUST use INFORMATION_SCHEMA existence
|
|
checks (`_table_exists`, `_column_exists`, `_index_exists`) — the same pattern
|
|
used by the squashed baseline. Unguarded migrations break idempotency and cannot
|
|
be re-run safely across the fleet.
|
|
|
|
## Delete / deregister a tenant
|
|
|
|
```bash
|
|
# Provisioned tenant — delete DB + control records
|
|
python -m control.provision delete-tenant --slug acme --drop-db --yes
|
|
|
|
# Adopted DB (tenant-zero) — remove control records only; NEVER --drop-db
|
|
python -m control.provision delete-tenant --slug lts --yes
|
|
```
|
|
|
|
`--drop-db` is guarded: it only proceeds when the stored `db_name` matches the
|
|
provisioner convention (`jqc_<slug>`). This prevents accidental drops of
|
|
externally-named databases like LT's production DB.
|
|
|
|
## Rollback
|
|
|
|
```bash
|
|
# Drop all 7 control tables (destructive)
|
|
alembic -c control/migrations/alembic.ini downgrade base
|
|
```
|
|
|
|
## Plan tier matrix
|
|
|
|
| Axis | Free | Starter | Pro | Enterprise |
|
|
|---|---|---|---|---|
|
|
| Max users | 3 | 15 | 50 | unlimited |
|
|
| Max facilities | 2 | 10 | 50 | unlimited |
|
|
| Inspections / month | 50 | 500 | 5 000 | unlimited |
|
|
| Issues / month | 50 | 500 | 5 000 | unlimited |
|
|
| Mobile API | ✗ | ✓ | ✓ | ✓ |
|
|
| Scheduled reports | ✗ | ✗ | ✓ | ✓ |
|
|
| Branding | ✗ | ✗ | ✓ | ✓ |
|
|
| Custom domain | ✗ | ✗ | ✓ | ✓ |
|
|
| Subdomain | ✓ | ✓ | ✓ | ✓ |
|
|
|
|
Quota-exceed: **soft warn** — allow submit, flag for upgrade, never reject.
|
|
Plans are seeded idempotently; re-running `python -m control.cli seed` updates
|
|
in-place without creating duplicates.
|