40 lines
3.8 KiB
Markdown
40 lines
3.8 KiB
Markdown
# Identity setup and release
|
||
|
||
## Database and owner bootstrap
|
||
|
||
1. Set DATABASE_URL for the intended development PostgreSQL database.
|
||
2. Install with the lockfile, run `pnpm db:generate`, then `pnpm db:deploy`.
|
||
3. Run `pnpm check` and `pnpm build`.
|
||
4. Supply ORGANIZATION_NAME, OWNER_NAME, OWNER_EMAIL and OWNER_PASSWORD through environment variables. The password must be 15–128 characters. Do not pass secrets in CLI arguments or commit them.
|
||
5. Run `pnpm bootstrap:owner`. It prints only organizationId and userId. Remove bootstrap environment secrets after use.
|
||
6. Start the application and use the returned organizationId to log in.
|
||
|
||
Bootstrap is a one-time installation operation protected by a transaction advisory lock and a unique owner index. A repeat invocation fails without creating partial records. Never bootstrap a production owner using test credentials. There is no default password.
|
||
|
||
## Optional recovery email
|
||
|
||
Set all of SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM and RECOVERY_URL together. SMTP_PORT defaults to 587; port 465 uses implicit TLS. TLS is mandatory. RECOVERY_URL must be an HTTPS frontend reset page without credentials, a query string or a fragment.
|
||
|
||
Until SMTP is configured, recovery requests return 503 for every account. The rest of identity remains usable. SESSION_TTL_MINUTES defaults to 480 (5–10080 allowed); RECOVERY_TTL_MINUTES defaults to 15 (5–60 allowed). SMTP settings are validated at startup but connectivity is only exercised on delivery.
|
||
|
||
No production SMTP account, reset frontend page, deployment environment or live owner was provisioned in this development task.
|
||
|
||
## Migrations and release checks
|
||
|
||
- 202609080002_identity_access adds users, roles, organization-safe assignments, sessions, recovery tokens, audit events and durable rate-limit buckets.
|
||
- 202609080003_identity_integrity adds normalized-email and single-owner constraints plus append-only audit triggers.
|
||
- Existing organization rows are retained. The migrations add no default user or credential.
|
||
- Custom SQL constraints/triggers are intentional and cannot all be represented in the Prisma model. Their migration tests must remain enabled.
|
||
- Run `node scripts/verify-migrations.mjs` against a disposable PostgreSQL database to verify deploy, status and model drift.
|
||
- Back up the target database, run deploy once per release, then verify readiness and the identity smoke flow. Do not use destructive down migrations to remove identity data. Roll back application binaries only when schema-compatible; otherwise apply a forward fix.
|
||
|
||
## Automated checks
|
||
|
||
`pnpm check` runs formatting, schema validation, strict type checks, unit tests, integration tests with coverage and production compilation. Tests use an embedded PostgreSQL engine by default and apply every checked-in migration, including upgrading a seeded foundation organization.
|
||
|
||
For native PostgreSQL tests, set TEST_DATABASE_URL to a disposable PostgreSQL administrator connection. Each fixture creates and drops a randomly named test database. Never supply production credentials. The concurrent recovery test runs only on native PostgreSQL because the embedded engine does not reproduce independent PostgreSQL connection concurrency.
|
||
|
||
The Gitea workflow targets a Docker-capable act runner labelled ubuntu-latest, with Actions enabled and internet access for dependency installation. It provides PostgreSQL 17, runs native tests and verifies migrations. Runner availability, remote CI results and branch-protection rules must be checked on the repository host; committing a workflow does not enable these settings automatically.
|
||
|
||
Before public launch, complete the reset frontend, SMTP smoke test, queued notification delivery, trusted proxy policy, operational housekeeping, and native database CI. Customer self-registration is separate from staff provisioning.
|