Deployment Guide

Owner(s): CrowdPM team | Last updated: 2026-03-08 | Status: Production

Deployment Guide

Purpose

This page summarizes deployment across local, demo, and production contexts. The canonical operational runbooks remain:

• docs/development.md
• docs/demo.md
• docs/prod.md

Use this page as the wiki-level overview and decision guide.

Deployment contexts

1. Local development

Use local deployment when:

• developing features;
• validating route behavior;
• testing ingest changes;
• preparing for demos without cloud dependencies.

Primary command:

pnpm dev

This launches:

• frontend dev server;
• Firebase Emulator Suite;
• functions build watcher.

Local deployment prerequisites:

• .firebaserc seeded from example;
• frontend/.env.local configured;
• functions/.env.local configured;
• functions/.secret.local configured for secret-backed functions.

2. Demo environment

Use the demo deployment when:

• code has been reviewed;
• CI is green;
• a shared hosted environment is needed for presentation or team validation.

High-level demo deployment requirements:

• access to the demo Firebase project;
• demo runtime secrets configured;
• Firestore API enabled in the project if it is a first-time setup;
• Firestore database created;
• default Storage bucket created;
• GitHub Actions secret DEMO_SERVICE_ACCOUNT_JSON configured if using the documented GitHub deployment workflow.

3. Production environment

Use production deployment only for controlled releases.

High-level production requirements:

• release window and approval confirmed;
• demo validation complete;
• correct project context selected;
• production secrets verified;
• fresh build artifacts generated;
• release notes prepared.

Local deployment checklist

1. pnpm install
2. copy env examples into .env.local
3. create functions/.secret.local
4. run pnpm dev
5. verify /health
6. verify frontend and smoke test

Demo deployment checklist

Before deployment

• all relevant changes merged to main;
• CI green;
• local repo clean and up to date;
• Firebase CLI authenticated;
• demo project access confirmed.

Demo secrets and service account

The documented demo runbook includes a GitHub Actions secret named:

• DEMO_SERVICE_ACCOUNT_JSON

If using GitHub-based deployment, ensure that secret exists and corresponds to the intended demo project.

Demo project first-run preparation

For a new or freshly prepared demo Firebase project, confirm:

• Firestore API is enabled;
• Firestore database exists;
• default Firebase Storage bucket exists.

Without these, functions and ingest smoke tests can fail even when code is correct.

Demo release flow

1. check out main and pull latest changes;
2. confirm correct demo project context and secrets;
3. build fresh artifacts if required by the runbook;
4. deploy using the documented demo procedure;
5. validate hosted frontend and core API behavior;
6. run or verify a smoke-test-like path in the hosted environment if appropriate.

Production deployment checklist

Preconditions

• demo environment already validated;
• production release manager is identified;
• release notes drafted;
• rollback/backups verified.

Critical project selection step

The documented production runbook explicitly switches Firebase context to production before continuing. This step must be treated as a hard stop / confirmation point.

Production release flow

1. ensure the local checkout matches the intended release commit;
2. switch Firebase context to production;
3. verify required secrets such as DEVICE_TOKEN_PRIVATE_KEY;
4. run fresh lint/build steps;
5. deploy only after the project context is re-verified;
6. perform post-deploy validation and record the release.

What belongs in the wiki vs repo docs

Keep in this wiki page

• deployment context overview;
• environment distinctions;
• contributor guidance on when to use local/demo/production;
• high-level checklists.

Keep in repo docs

• exact command sequences;
• secret-management commands;
• first-run cloud-console steps;
• release-manager operational details.

Common deployment mistakes

• using the local/demo alias for a real deploy;
• forgetting functions/.secret.local during local startup;
• forgetting to provision Firestore or Storage in a new demo project;
• leaving VITE_API_BASE pointed at the wrong environment;
• deploying without confirming the active Firebase project;
• documenting deployment in the wiki but not updating /docs.

Required companion pages

Any deployment-process change should usually update all of the following:

• Developer Setup & Project Conventions
• Demo Scripts
• Release Plan & Notes (milestones---demos)
• Handoff, Reflection, and Future Work