127 lines
9.2 KiB
Markdown
127 lines
9.2 KiB
Markdown
# Upgrade Runbook
|
|
|
|
## Purpose
|
|
|
|
This entrypoint defines the safe path for dependency, runtime, database, provider, and deployment-adjacent upgrades in the boilerplate. Use it before changing package versions, Node/Corepack behavior, Prisma migrations, React Router runtime assumptions, worker Redis settings, Mailjet configuration, or security-sensitive provider boundaries.
|
|
|
|
This guide intentionally links to the deeper contracts instead of duplicating them:
|
|
|
|
- [`docs/porting-guide.md`](./porting-guide.md) for current boilerplate naming, runtime status, package-manager wording, and manual browser/E2E policy.
|
|
- [`docs/porting-verification.md`](./porting-verification.md) for the post-port documentation checklist and supported non-E2E verification posture.
|
|
- [`docs/database.md`](./database.md) for PostgreSQL, Prisma, migration status, deployment, backup, restore, and redacted database diagnostics.
|
|
- [`docs/deployment.md`](./deployment.md) for image, Coolify, rollback, health, and manual runtime verification boundaries.
|
|
- [`docs/security.md`](./security.md) for headers, CORS, authentication, Mailjet, secret redaction, and incident-response constraints.
|
|
|
|
## Package manager and runtime prerequisites
|
|
|
|
The repository is pinned to `pnpm@10.33.0` through `package.json`. Do not replace upgrade instructions with unpinned `npm`, `yarn`, or scaffold-create examples. Prepare local and CI environments with Corepack before installing or comparing dependency changes:
|
|
|
|
```sh
|
|
corepack enable
|
|
corepack prepare pnpm@10.33.0 --activate
|
|
pnpm install
|
|
```
|
|
|
|
The active web runtime is the `@toolctrl/web` React Router application in `apps/web/app`, with root scripts delegating to it. `apps/api` is the Hono API foundation, `apps/worker` is opt-in worker infrastructure, and selected `packages/*` surfaces are package boundaries with different levels of runtime wiring. Confirm those statuses against [`docs/porting-guide.md`](./porting-guide.md) before writing upgrade notes that imply extraction is complete.
|
|
|
|
## Dependency upgrade workflow
|
|
|
|
1. Read the package-manager pin in `package.json` and keep the same command family for all examples.
|
|
2. Review the dependency change set for runtime-sensitive packages: React Router, React, Prisma, PostgreSQL adapters, Mailjet/mail packages, Redis/BullMQ, Hono/API packages, security/header/CORS packages, and build tooling.
|
|
3. Install with the pinned pnpm version and keep lockfile changes tied to the reviewed package update.
|
|
4. Run focused static checks before any manual runtime inspection:
|
|
|
|
```sh
|
|
pnpm run typecheck
|
|
pnpm run lint
|
|
pnpm run verify:production-docs
|
|
pnpm run verify:docs-links
|
|
pnpm exec vitest run scripts/verify-production-docs.test.mjs scripts/docs-link-check.test.ts
|
|
```
|
|
|
|
Use additional scoped Vitest files when the upgraded package has direct test coverage. Do not replace these checks with broad browser automation or live provider checks during Auto-Mode execution.
|
|
|
|
## Prisma and database migration checks
|
|
|
|
Database-affecting upgrades include Prisma packages, PostgreSQL adapter changes, generated-client changes, and schema or migration edits. Follow [`docs/database.md`](./database.md) for the detailed operations contract.
|
|
|
|
Safe upgrade expectations:
|
|
|
|
- Confirm `DATABASE_URL` and `DIRECT_URL` only as environment key names; never paste raw values into documentation, tickets, logs, screenshots, or verification summaries.
|
|
- Use `pnpm run typecheck` when generated types or Prisma client artifacts could drift.
|
|
- Use `pnpm run verify:production-docs` and `pnpm run verify:docs-links` after documentation changes that describe database behavior.
|
|
- Treat `pnpm run db:migrate:deploy` as the approved migration deployment command, not as a local authoring command.
|
|
- Confirm backup or restore-point readiness through the environment-owned process before production migration deployment.
|
|
|
|
Local Prisma authoring commands documented in [`docs/database.md`](./database.md) remain local-only and must not be copied into production automation.
|
|
|
|
## React Router and runtime checks
|
|
|
|
React Router, React, Vite/build tooling, route behavior, headers, or server-runtime upgrades require explicit attention to the current `@toolctrl/web` runtime:
|
|
|
|
- Keep `apps/web/app` as the authoritative web source tree, with root scripts as command entrypoints, unless a later verified extraction changes that fact.
|
|
- Keep `apps/web` described as the runtime boundary and package owner for web code.
|
|
- Use `pnpm run typecheck`, `pnpm run lint`, and scoped Vitest commands for affected route or runtime tests.
|
|
- Use [`docs/deployment.md`](./deployment.md) for health, readiness, image, and rollback expectations.
|
|
|
|
Browser, Playwright, Cypress, and other E2E checks are manual runtime activities unless a human explicitly approves the exact focused run. Upgrade documentation may describe the manual scenario to review, but it must not claim automatic browser/E2E execution.
|
|
|
|
## Worker, Redis, and queue opt-in checks
|
|
|
|
Worker-related upgrades include BullMQ, Redis clients, queue contracts, worker build output, and packages consumed by `apps/worker`. The worker remains opt-in and Redis-backed:
|
|
|
|
- `WORKER_ENABLED=true` is required to enable worker execution.
|
|
- `BULLMQ_REDIS_URL` is the primary Redis queue configuration key; `REDIS_URL` may appear as a platform-binding fallback where documented.
|
|
- Health and readiness output may include enablement state, queue names, failed-job counts, and redacted dependency codes.
|
|
- Logs and docs must not include Redis URLs, passwords, raw job payloads, tenant identifiers, or customer data.
|
|
|
|
Use scoped package or Vitest checks for worker code changes. Keep live queue replay, live Redis inspection, and container runtime checks in the manual operations boundary unless explicitly approved.
|
|
|
|
## Mailjet and security review
|
|
|
|
Mailjet is the active transactional mail boundary. Mail or provider upgrades must preserve the contract in [`docs/security.md`](./security.md):
|
|
|
|
- `MAILJET_API_KEY` and `MAILJET_FROM_EMAIL` are configuration key names only, not values to print.
|
|
- Webhook handling must continue to verify signing before trusting provider events.
|
|
- Diagnostics may record provider category, event type label, delivery status, request ID, job ID, and whether signature verification passed.
|
|
- Documentation, tickets, and logs must not include API keys, webhook signing secrets, provider payloads, customer email addresses, message bodies, bearer tokens, cookies, or dashboard screenshots containing personal data.
|
|
|
|
Security-sensitive upgrades also require reviewing headers, CORS, API authentication, request-id correlation, and secret redaction in [`docs/security.md`](./security.md).
|
|
|
|
## Rollback notes
|
|
|
|
Rollback planning is required before production-facing upgrades:
|
|
|
|
1. Identify the previous known-good package or image state.
|
|
2. For deployable images, use immutable SHA-derived tags as described in [`docs/deployment.md`](./deployment.md); do not rely on mutable guesses.
|
|
3. For database migrations, confirm backup or restore-point availability before deployment and preserve only redacted evidence in the incident record.
|
|
4. For worker incidents, pause or drain queues through approved operational tooling before replaying jobs.
|
|
5. Record rollback evidence with target name, tag or reviewed version, status, request ID, job ID, and redacted diagnostic code only.
|
|
|
|
If rollback output exposes raw secrets, connection strings, UUID-like deployment endpoints, provider tokens, stack traces with credentials, tenant identifiers, or customer data, treat it as a secret exposure and follow the containment guidance in [`docs/security.md`](./security.md).
|
|
|
|
## Documentation verification and link safety
|
|
|
|
After changing upgrade documentation or any linked production runbook, run the non-E2E documentation gates:
|
|
|
|
```sh
|
|
pnpm run verify:production-docs
|
|
pnpm run verify:docs-links
|
|
pnpm exec vitest run scripts/verify-production-docs.test.mjs scripts/docs-link-check.test.ts
|
|
```
|
|
|
|
These checks should report file-scoped failures for missing documents, forbidden placeholders, forbidden automatic browser/E2E commands, broken local paths, and broken local anchors. They do not require external network access and must not expose secrets.
|
|
|
|
## Upgrade review checklist
|
|
|
|
- [ ] Package-manager examples use Corepack and pinned `pnpm@10.33.0`.
|
|
- [ ] Commands are limited to scripts present in `package.json` or explicit scoped Vitest examples.
|
|
- [ ] Database changes follow PostgreSQL and Prisma guidance in [`docs/database.md`](./database.md).
|
|
- [ ] React Router remains documented as the active `@toolctrl/web` runtime in `apps/web/app`.
|
|
- [ ] Worker and Redis behavior stays opt-in through documented environment key names.
|
|
- [ ] Mailjet and security-sensitive provider changes preserve signing, auth, header, CORS, and redaction boundaries.
|
|
- [ ] Rollback notes use immutable image tags, reviewed versions, backups, and redacted diagnostics.
|
|
- [ ] Browser, Playwright, Cypress, live Docker, live registry, Coolify, and provider-console checks are manual unless the exact run is explicitly approved.
|
|
- [ ] No raw secrets, production credentials, tenant identifiers, customer data, provider payloads, or secret-shaped examples were added.
|
|
- [ ] `pnpm run verify:production-docs`, `pnpm run verify:docs-links`, and relevant scoped Vitest checks pass before closing the upgrade documentation change.
|