pelagia-portal/.claude/agent-memory/devops-env-manager/project_services.md

name	description	metadata
project-services	All managed services, ports, startup commands, health checks, and env var notes for the Pelagia Portal dev environment	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