---
name: project-services
description: All managed services, ports, startup commands, health checks, and env var notes for the Pelagia Portal dev environment
metadata:
  type: project
---

## Services

| Service | Port | Startup Command | Directory |
|---|---|---|---|
| pelagia-portal (Next.js) | 3000 | `node node_modules/next/dist/bin/next dev --turbopack` | `App/` |
| GstService (Express + Playwright) | 3003 | `npm run dev` (runs `tsx watch src/index.ts`) | `GstService/` |
| PostgreSQL 18 | 5432 | Windows service / already running | — |

## Startup Order

1. Verify PostgreSQL is up on port 5432 (`pg_isready -U postgres`)
2. Create DB if missing: `createdb -U postgres pelagia_portal` (PGPASSWORD=postgres)
3. Run `prisma migrate deploy` from `App/` (non-interactive, applies all pending migrations)
4. Run `prisma generate` from `App/` (generates Prisma client into node_modules)
5. Start GstService: `cd GstService && npm run dev`
6. Start pelagia-portal: `node node_modules/next/dist/bin/next dev --turbopack` from `App/`
   - DO NOT use `pnpm dev` — pnpm pre-flight runs `pnpm install` which hits ERR_PNPM_IGNORED_BUILDS and aborts
   - Call next directly via node to bypass pnpm dependency check

## Health Checks

- pelagia-portal: `http://localhost:3000` — expect 200 or 307 (auth redirect to /login)
- GstService: `http://localhost:3003/health` — expect `{"ok":true,...}`
- PostgreSQL: `pg_isready -U postgres` — `:5432 - accepting connections`

## Environment

- App is in `K:\src\pelagia-portal\App\` (NOT `App/pelagia-portal/` — that path is stale git history)
- `.env.local` in `App/` holds actual dev secrets (NEXTAUTH_SECRET, DATABASE_URL)
- Required dev vars: `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, `DATABASE_URL`
- R2 and Resend vars not needed in dev (files go to `.dev-uploads/`, emails log to console)
- DATABASE_URL: `postgresql://postgres:postgres@localhost:5432/pelagia_portal`
- NEXTAUTH_SECRET: in .env.local
- NEXTAUTH_URL: `http://localhost:3000`

## Node / Package Manager Setup

- Node.js: `C:\Program Files\nodejs` (NOT on system PATH by default — must prepend)
- pnpm: installed globally at `C:\Users\shad0w\AppData\Roaming\npm\node_modules\pnpm`
  - $env:PATH must include `$env:APPDATA\npm` to find pnpm
- PostgreSQL 18 bin: `C:\Program Files\PostgreSQL\18\bin`
- Set PATH at start of each session: `$env:PATH = "C:\Program Files\nodejs;C:\Program Files\PostgreSQL\18\bin;$env:APPDATA\npm;$env:PATH"`
- PGPASSWORD=postgres for psql/createdb commands

## pnpm ERR_PNPM_IGNORED_BUILDS Issue

- pnpm 11.1.2 blocks build scripts for: @prisma/client, @prisma/engines, esbuild, prisma, sharp, unrs-resolver
- The `pnpm.onlyBuiltDependencies` field in package.json does NOT fix this (field not recognized by pnpm 11)
- Workaround: use `node node_modules/next/dist/bin/next dev --turbopack` instead of `pnpm dev`
- Run `prisma generate` manually after install: `.\node_modules\.bin\prisma generate`
- The pnpm install itself completes (all 885 packages are installed) — only postinstall scripts are blocked

## Notes

- `prisma generate` EPERM on Windows = the DLL is locked by a running Node process (Next.js) — this is normal
- pelagia-portal 307 response = auth redirect to /login — this is healthy, not an error
- Prisma migration scripts: `pnpm db:migrate` (dev), `pnpm db:migrate:deploy` (CI/prod)
- `node_modules` was missing on first setup (fresh checkout) — both App and GstService need install
- 13 Prisma migrations as of 2026-05-18