# Deployment to Vercel

Import this repository as one Vercel project with **Root Directory** set to the repository root (not `apps/app` or `apps/api`). Select **Other** as the framework and Node.js **22.x**. The commands and output directory are defined in `vercel.json`.

`pnpm build` builds the shared package, generates Prisma Client and compiles the API, then builds the React app. The ordinary build does not modify the database. Vercel uses `pnpm build:vercel`: it first builds all packages, then runs `prisma migrate deploy`, then seeds admin, Pilot Plant, inventory, and maintenance sparepart data. Any failure stops deployment.

## Routing

- `/api/*` is handled by the Express function in `api/index.js` (including `/api/v1/docs`).
- Existing frontend static files are served directly.
- Other URLs fall back to `index.html`, allowing React Router pages to be refreshed directly.

## Environment variables

Set these in Vercel before deploying:

- `DATABASE_URL`: the MySQL connection URL for a database reachable from Vercel.
- `JWT_SECRET`: a strong secret for signing authentication tokens.
- `APP_ORIGIN`: the exact frontend origin, for example `https://maintenance.example.com`. Authentication checks this origin; configure Preview environments separately when needed.
- `NODE_ENV`: `production`.
- `AUTH_ADMIN_EMAIL`: email of the administrator to create or preserve.
- `AUTH_ADMIN_NAME`: administrator name (1-150 characters).
- `AUTH_ADMIN_PASSWORD`: initial administrator password (8-128 characters). Existing accounts and passwords are preserved; these variables must remain valid for subsequent seed runs.

The deployment seed uses this administrator for demo records unless `PILOT_SEED_REPORTER_EMAIL`, `INVENTORY_SEED_ACTOR_EMAIL`, or `MAINTENANCE_SEED_ACTOR_EMAIL` is supplied. The selected account must be active and eligible for the corresponding seeder.

Leave `VITE_API_BASE_URL` unset for this same-origin deployment. Set it only when intentionally hosting the API separately; it must be the origin without `/api/v1`. `API_PROXY_TARGET` is only used by the local Vite development server.

## Database updates during deployment

Every Vercel build applies pending migration files and runs all seeders. Applied migrations are not rerun and the database is not reset. Seeders preserve existing records and add missing demo records using stable IDs. Manual edits and existing admin passwords are preserved.

Set a separate `DATABASE_URL` for Preview deployments so a preview build does not modify the production database. The configured database must be reachable during the build and allow migrations.

The migration and seed steps are not one transaction. If a later seeder or deployment fails, earlier committed database changes remain. A subsequent build can rerun the seeders; identity conflicts must be resolved without deleting production data.

To run the same deployment pipeline manually against the configured database:

```sh
pnpm build:vercel
```

## Photo storage limitation

The photo service defaults to `apps/api/src/public/uploads`; `MEDIA_ROOT` optionally overrides this directory. Express exposes uploaded WebP files publicly at `/public/uploads/<photoKey>`. Existing authenticated API photo endpoints continue working. If moving from an old `MEDIA_ROOT`, copy the existing files with their original names to the new directory before removing the override.

Vercel Functions do not provide persistent writable local storage. This default folder works on a local server or a host with persistent disk, but does not enable persistent uploads on Vercel. Use an object-storage implementation (such as S3 or Vercel Blob), or host the API on a server with persistent disk. `/tmp` is not persistent storage.

Scheduled maintenance generation and media cleanup scripts must be scheduled separately; this configuration only deploys the web app and HTTP API.