Skip to content

Deployment Guidelines

These guidelines govern deployment practices for the PSI project.

Infrastructure Principles

Cloud Portability

Services must be implemented in a way that makes shifting between cloud technologies feasible:

  • Use the adapter pattern for all external service integrations
  • At minimum, support Firebase Cloud Functions and standalone Docker deployment
  • Avoid vendor lock-in for core logic (database adapter enables Firebase RTDB or MongoDB)

Containerization

  • Every service runs in a Docker container
  • Base images should be minimal (e.g., node:22-alpine)
  • Multi-stage builds to minimize production image size
  • Health check endpoints required (/health/live)

Deployment Structure

deployments/
├── {technology}/
│   └── {environment}/
│       └── docker-compose.yml (or k8s manifests)
└── iac/
    └── terraform/ (or deployment scripts)

Repository Guidelines

Monorepo Structure

PSI uses a pnpm workspace monorepo (psi-product):

Package Purpose
client Frontend application
server Backend API
moderation-service Standalone moderation
demo-proxy Content proxy
publisher-demo/client Publisher integration demo
dashboard-data Analytics scripts
e2e-tests End-to-end tests
offline/* Offline jobs (translation, page rendering)

Version Management

  • Client and server versions are kept in sync (currently 1.67.0)
  • Dependencies managed via pnpm with workspace protocol
  • Global overrides for React version alignment

Frontend Deployment

  • Build output: static SPA in client/dist
  • Hosting: Firebase Hosting (primary) or any static file server
  • SPA routing: all routes serve index.html, client-side routing handles the rest
  • API rewrites: /api/* proxied to the backend

Backend Deployment

Firebase Cloud Functions (Primary)

(cd client && pnpm run webbuild)
(cd server && pnpm run build)
firebase deploy --project {alias}
  • Runtime: Node.js 22
  • Source: server/dist (compiled TypeScript)
  • Entry: exports api as HTTPS function

Docker / Hono Standalone (Alternative)

docker build -f Dockerfile.server -t psi-server .
docker run -p 5001:5001 --env-file .env psi-server
  • Entry: node lib/index.js (standalone Hono server via @hono/node-server)
  • Port: 5001 (configurable via PORT env var)

Environment Management

Environment Variables

  • Server configuration via .env.{environment} files
  • Client configuration via psi.config.ts (compiled into the build)
  • Sensitive values (API keys, secrets) must never be committed to the repository
  • Use Firebase Functions config or environment variables for secrets

Deployment Checklist

Before deploying to production:

  • [ ] All tests pass (unit + e2e)
  • [ ] Code reviewed and approved
  • [ ] Environment variables configured
  • [ ] Database initialized (Firebase RTDB or MongoDB)
  • [ ] Authentication provider configured (Google + SSO if needed)
  • [ ] Admin user created in database
  • [ ] SSL/TLS certificate configured for custom domains
  • [ ] Error monitoring (Sentry) DSN configured
  • [ ] Logging environment key set (LOGGING_ENVIRONMENT)

CI/CD Requirements

  • Automated checks on every PR: formatting, linting, type checking, tests
  • E2E tests must pass before merging to main
  • Staging deployment after successful E2E on main
  • PR preview deployments for client changes
  • Manual promotion from staging to production

See CI/CD Pipeline for workflow details.