# Release & deployment runbook — boha-app-ts

Referenced from CLAUDE.md. **Never deploy to production or restart services
without explicit user confirmation.**

## Standard release

1. Run the full gates locally: `npx vitest run` (all green), `npx tsc -b --noEmit`,
   `npm run lint` (0 errors).
2. Bump version: `npm version X.Y.Z --no-git-tag-version` (the user picks the number).
3. `npm run build`
4. Commit and tag: `git tag -a vX.Y.Z`
5. Push to Gitea: `git push origin master && git push origin vX.Y.Z`
6. Create tarball:

   ```bash
   tar -czf app-ts-X.Y.Z.tar.gz dist dist-client prisma prisma.config.ts package.json package-lock.json scripts
   ```

   ⚠️ `prisma.config.ts` is REQUIRED — Prisma 7 keeps the datasource URL there;
   without it, `prisma generate`/`migrate deploy` on prod have no datasource.

7. Deploy via SSH to production (`boha_admin@192.168.50.100`, path `/var/www/app-ts`):

   ```bash
   scp app-ts-X.Y.Z.tar.gz boha_admin@192.168.50.100:/tmp/
   ssh boha_admin@192.168.50.100
   cd /var/www/app-ts
   rm -rf dist dist-client prisma prisma.config.ts scripts package.json package-lock.json
   tar -xzf /tmp/app-ts-X.Y.Z.tar.gz
   npm install --omit=dev
   npx prisma generate        # MANDATORY — see below
   npx prisma migrate deploy
   pm2 restart app-ts --update-env
   ```

   **`npx prisma generate` is mandatory.** `npm install` skips client
   regeneration when dependencies didn't change, leaving a stale client that
   still selects dropped/renamed columns → P2022 500s in prod (this caused
   the v2.4.0 incident: every issued-orders query failed until generate ran).

8. Verify: `pm2 list` (status online, correct version, restart counter not
   climbing), `npx prisma migrate status` ("up to date"),
   `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3001/` → 200,
   and grep logs for errors from the CURRENT pid only (the out log keeps old
   errors from prior pids).
9. Clean up tarballs locally and in `/tmp/` on the server.

**nginx is NOT part of a normal release.** nginx is only a reverse proxy in
front of the pm2 app (`proxy_pass` → `127.0.0.1:3001`); a code release changes
app code, which `pm2 restart app-ts` picks up — nginx has nothing new to read.
Do **not** run `sudo nginx -t && sudo systemctl reload nginx` every deploy. Run
it ONLY when you actually edit nginx config (`/etc/nginx/…` — `server_name`,
ports, `proxy_pass` upstream, TLS cert paths, locations/redirects/headers,
`client_max_body_size`, rate limits, etc.). When you do change it, always
`nginx -t` first (validates syntax, changes nothing) THEN `systemctl reload
nginx` (graceful re-read, keeps active connections; a bad config on reload is
rejected and the old one keeps running).

Risky releases (framework jumps, FK/constraint-altering migrations) get a
read-only pre-flight first: `prisma migrate status` on prod, verify FK
constraint names the migration DROPs, check no data violates new
UNIQUE/RESTRICT constraints — and confirm with the user before the
irreversible steps. The prod DB is backed up by a cron job (no manual
mysqldump needed).

## Hotfixing a migration added after the tarball was built

A migration folder created after the release tarball shipped is not on prod,
so `prisma migrate deploy` reports "No pending migrations". Ship just the
migration folder (still tracked in git — this is NOT raw SQL on prod):

```bash
# Local
cd prisma/migrations
tar -czf /tmp/<name>_migration.tar.gz <timestamp>_<name>/
scp /tmp/<name>_migration.tar.gz boha_admin@192.168.50.100:/tmp/

# On prod
ssh boha_admin@192.168.50.100
cd /var/www/app-ts/prisma/migrations
tar -xzf /tmp/<name>_migration.tar.gz
cd /var/www/app-ts
npx prisma migrate deploy
pm2 restart app-ts --update-env
```

## Drift check / preview before deploy

```bash
# Preview what SQL would bring the dev DB (per prisma.config.ts) to the local schema
npx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script
```

Empty output = no diff. (Prisma 7 removed `--from-url`; diffs against another
DB need its URL in a config/env override.) If drift includes DROPs,
investigate before touching production.

## Baselining a database that has no migrations

If a database was synced without migration history (no `_prisma_migrations`
table): create the initial migration locally, copy `prisma/migrations` to the
server, then mark it applied without running SQL:

```bash
npx prisma migrate resolve --applied <migration_name>
```