shad0w/pelagia-portal
1
0
Fork 0
Code Issues 10 Pull requests 2 Projects Releases 2 Packages Wiki Activity Actions
Page: Environment Variables
Pages
Architecture Changelog Crewing Architecture Crewing Data Model Crewing Design Document Crewing Implementation Spec Crewing Module Crewing Roles and Permissions Crewing Use Cases Crewing User Stories Crewing Workflows Data Model Deployment and Operations Design System E2E Test Framework E2E Test Plan Environment Variables Feature Catalogue File Storage Getting Started Glossary Home Inventory and Catalogue Inventory on Approval Issue to Deploy Pipeline Notifications Open Questions PO Lifecycle Pages and Navigation Planned Features Playwright Test Design Purchase Orders Reports Mockup Reports Roles and Permissions Tech Debt Test Plan Test Testing Vendors and GST Lookup Workflows
5 Environment Variables
shad0w edited this page 2026-06-24 10:03:03 +00:00
Table of Contents

Environment Variables

The required set differs between development and production; the switch is automatic, driven by NODE_ENV (next dev → development, next build/start → production). In dev the app needs only a DB and an auth secret — R2 and Resend fall back to local disk and console email.

Server-side env on pms1 lives in ~/pms/App/.env; locally in App/.env.local (git-ignored). Copy App/.env.example to start.

Reference

Variable Dev Prod Notes
NEXTAUTH_SECRET ✓ ✓ 32-char random (openssl rand -base64 32)
NEXTAUTH_URL ✓ ✓ Full app URL (e.g. http://localhost:3000)
DATABASE_URL ✓ ✓ PostgreSQL connection string
AZURE_AD_CLIENT_ID placeholder ✓ Microsoft Entra SSO
AZURE_AD_CLIENT_SECRET placeholder ✓ auth.ts reads these at module load — set placeholders in non-SSO/dev so the app boots
AZURE_AD_TENANT_ID placeholder ✓
R2_ACCOUNT_ID — ✓ Cloudflare R2 (file storage)
R2_ACCESS_KEY_ID — ✓
R2_SECRET_ACCESS_KEY — ✓
R2_BUCKET_NAME — ✓ e.g. pelagia-portal
R2_PUBLIC_URL — ✓ Public bucket URL
RESEND_API_KEY — ✓ Email delivery (re_…)
EMAIL_FROM — ✓ Sender address
EMAIL_FROM_NAME — — Display name (default "Pelagia Portal")
FORGEJO_URL optional optional Report-Issue button → Forgejo API
FORGEJO_REPO optional optional owner/repo
FORGEJO_TOKEN optional optional Token scope write:issue
GST_SERVICE_URL optional optional GstService base (default http://localhost:3003)
EPFO_SERVICE_URL optional optional EpfoService base (default http://localhost:3004) — crewing UAN/EPFO lookup
EPFO_LIVE optional optional EpfoService navigates the real portal when "true"; otherwise stubbed (deterministic)
PDF_SERVICE_URL optional optional PdfService base (default http://localhost:3005)
PDF_SERVICE_TOKEN optional optional Shared secret app↔PdfService; both PDF_SERVICE_URL + PDF_SERVICE_TOKEN set = “Email to vendor” enabled
APP_INTERNAL_URL optional optional URL PdfService fetches the PO export page at (falls back to NEXTAUTH_URL)
NEXT_PUBLIC_INVENTORY_ENABLED optional optional Inventory flag — off only when "false"
NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED optional optional Submitter view-all flag — on only when "true". Lets TECHNICAL/MANNING read & export every PO and open History
NEXT_PUBLIC_ENV_LABEL optional unset When set, shows the non-prod banner (EnvBanner). Leave unset in production
PORT optional optional App port (default 3000; staging 3200; autofix 3100)

Notes

  • SSO at module load — auth.ts evaluates the AZURE_AD_* vars when the module loads, so they must be present (even as placeholders) for the app to start in non-SSO environments. See Architecture.
  • Storage / email auto-toggle — with R2/Resend unset in dev, uploads go to .dev-uploads/ and emails print to the terminal. See File Storage and Notifications.
  • Inventory flag — INVENTORY_ENABLED = NEXT_PUBLIC_INVENTORY_ENABLED !== "false", i.e. enabled unless explicitly "false".
  • Submitter view-all flag — SUBMITTER_VIEW_ALL_ENABLED = NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED === "true", i.e. off unless explicitly "true" (opt-in, since it widens read access). When on, submitter roles (TECHNICAL/MANNING) can read & export every PO and reach the History page; it grants no approval/payment/edit rights. See Roles and Permissions.
  • Env banner — EnvBanner renders nothing when NEXT_PUBLIC_ENV_LABEL is unset, so production is unaffected; staging sets it to the "INTERNAL DEV / STAGING - NOT PRODUCTION" string.
  • GstService has its own PORT (default 3003); the portal reaches it via GST_SERVICE_URL. See Vendors and GST Lookup.
  • EpfoService / PdfService have their own PORT (3004 / 3005). PdfService powers Email PO to vendor: enabled only when both PDF_SERVICE_URL and PDF_SERVICE_TOKEN are set, and the same token must reach pdf-service (the deploy exports it from App/.env). See Deployment and Operations.

Pelagia Portal (PPMS)

Overview

Build & Run

System

Product

Planned

Quality

Ops

Engineering

Pelagia Portal (PPMS) — internal purchase-order management. Self-hosted on pms1, live at pms.pelagiamarine.com. This wiki tracks the shipped product; authoritative sources are the repo code, App/CLAUDE.md, Docs/, and CHANGELOG.md.