# Uploadable deployment bundles

Run `powershell -ExecutionPolicy Bypass -File management/deployment/package-release.ps1` from the repository root. It creates two folders under `management/deployment/releases/`:

- `frontend/`: Next.js standalone server, compiled application, static assets, and package manifests. It does not contain the project source tree, source maps, or Windows `node_modules`.
- `backend/`: compiled Nest application, generated Prisma client, Prisma schema/migrations, and package manifests. It does not contain `src/`, tests, source maps, local databases, or secrets.

The bundle builder runs the frontend production environment check and both production builds. It is safe to rerun; it replaces only the two generated release folders. The local build machine is Windows, so **never upload its `node_modules`**. Install dependencies on the target Linux VM using the included lockfiles. This app supports Node.js 22.13+ (22.x) and 24.14+ (24.x); select the latest available 22.x in cPanel if 24.x is not offered.

## cPanel Node.js hosting

For cPanel Node.js Selector / Application Manager, create two production applications using these settings:

| App | Domain | Application root | Startup file |
| --- | --- | --- | --- |
| Frontend | `transportapp.storenest.pk` | Uploaded `frontend/` bundle | `app.js` |
| Backend | `transportapi.storenest.pk` | Uploaded `backend/` bundle | `app.js` |

Choose Node.js 22.13+ (22.x) or 24.14+ (24.x) if your provider offers it. Install dependencies for each app from cPanel's application controls. Passenger supplies `PORT`; do not define it yourself. The frontend release is built with `https://transportapi.storenest.pk/api/v1` by default. To rebuild for a different API URL, pass `-ApiBaseUrl` to the package script.

Set the backend application environment to `FRONTEND_URL=https://transportapp.storenest.pk` and `CORS_ORIGINS=https://transportapp.storenest.pk`, plus the required backend values from `backend.env.example`. Keep secrets in cPanel's environment settings and never upload a populated `.env` file. Both hostnames must have valid HTTPS certificates. Since the frontend and API are HTTPS subdomains of `storenest.pk`, browser requests with credentials can use the API's secure host-only session cookie under the configured `SameSite=Strict` policy.

If your cPanel Node selector offers only versions older than 22.13, ask the host to enable a supported Node version. cPanel applies environment/configuration changes when the application is redeployed.

## First deployment

1. Upload `frontend/` and `backend/` to separate versioned release directories on the Linux VM. Set ownership so the app user can read the files; allow writes only where Next.js needs cache storage.
2. Copy `backend.env.example` to a protected runtime env file such as `/etc/transport/backend.env`. Replace all examples. Keep it root-owned and mode `0640`; do not upload it with the release.
3. Copy `migration.env.example` to `/etc/transport/migration.env`, use a separate non-root migration account, and protect it the same way.
4. In the backend release directory run `bash ./migrate-production.sh /etc/transport/migration.env`. The script checks the expected schema name and non-root migration user, installs the locked dependencies, reports current migration status, deploys only pending committed migrations, then reports final status. It does not reset or drop the database. Review migration SQL and take a verified backup first.
5. After migrations, run `npm prune --omit=dev` in the backend release directory. Install frontend runtime dependencies with `npm ci --omit=dev` in the frontend release directory.
6. Inject `/etc/transport/backend.env` into the backend service and copy `frontend.env.example` to `/etc/transport/frontend.env`. Set the bundled shell scripts executable with `chmod 750 backend-start.sh frontend-start.sh`. The systemd examples use the release paths `/opt/transport/current/backend` and `/opt/transport/current/frontend`; adapt the symlink target to your release directory. The scripts bind to loopback ports 3001 and 3000.
7. Configure Nginx for the same public HTTPS hostname: `/api/` to `127.0.0.1:3001`, all other paths to `127.0.0.1:3000`. The app must be accessed through that one HTTPS origin. Open only 80/443 publicly; never expose Node ports.
8. Confirm `https://transportapp.storenest.pk/`, `https://transportapi.storenest.pk/api/v1/health/live`, `https://transportapi.storenest.pk/api/v1/health/ready`, tenant login, email links and QR verification. Production Swagger stays disabled.

## Origin and CORS values

For the cPanel domains in this release, use `https://transportapp.storenest.pk` as both `FRONTEND_URL` and the sole `CORS_ORIGINS` value. CORS values are origins only: scheme + hostname + optional non-default port, without a path or trailing slash. The frontend bundle points to `https://transportapi.storenest.pk/api/v1`. If deploying to the Linux VM with same-origin Nginx routing instead, rebuild with `-ApiBaseUrl /api/v1` and use the VM's public origin for `FRONTEND_URL` and `CORS_ORIGINS`.

## Database migration safety

The API runtime uses `DATABASE_URL` with a non-root account and ordinary data privileges. The one-shot migration script reads only `MIGRATION_DATABASE_URL` from its separate protected file. Grant the migration account DDL privileges only on the application schema. Never run `prisma migrate reset`, `migrate dev`, `db push`, or a destructive SQL script against hosted data. For each release: review the new migration SQL, back up, run the migration script, deploy the matching app release, and verify readiness. Keep the prior app release for rollback; schema rollback requires a reviewed recovery plan.

The cPanel frontend build embeds `NEXT_PUBLIC_API_URL=https://transportapi.storenest.pk/api/v1`; changing this requires rebuilding the frontend bundle. No populated `.env`, database, email credentials, user data, or full repository source should be uploaded.