Deployment Infrastructure
Last verified: 2026-05-03 | Committed routing sources:equa-web/nginx.conf,equa-web/Dockerfile,equa-web/webpack.config.js,equa-web/.github/workflows/equa-cc-domain-smoke.yml| Legacy deployment source:equa-server/cloudbuild.yaml| Live edge capture:2026-05-03T16:09:41Zagainstequa-webcommit3131f1699ae9df3dcf3655611bc8fb247afbb33e
Deployment History Timeline
Era 1: AWS (Prior Deployment)
Era 2: GCP Cloud Run / Public Cloud Legacy
The GCP-era public deployment still exists in repository automation.equa-server/cloudbuild.yaml deploys equa-backend to Cloud Run in us-central1 on port 3000, which remains relevant for cost wind-down and legacy endpoint investigations. It is no longer the authoritative browser-routing story for the SPA host.
Source: equa-server/cloudbuild.yaml, Lines: 13-46
Era 3: Railway Interim / Local-First
The current committed interim routing story lives inequa-web/nginx.conf: equa.cc and www.equa.cc return 301 to https://app.equa.cc$request_uri, the default server block accepts the active SPA host, and /api/ proxies to https://equa-server-so-production.up.railway.app/. The container defaults PORT=8080 and exposes 8080, so Railway target-port parity remains the first check if the edge regresses to 502.
Sources:
equa-web/nginx.conf, Lines: 4-29equa-web/Dockerfile, Lines: 44-49
Era 4: Spec 040 Target
Spec 040 still targetsequa.cc as the canonical marketing + app hostname with app.equa.cc eventually redirecting back to apex. Treat that as target-state planning, not as a claim about the live edge today.
Source: command-center-so/specs/040-equa-cc-landing-rebuild/spec.md, Section: 3.1
Routing Truth Layers
Committed_interim
As committed today,equa-web defines two nginx server blocks. One block catches equa.cc and www.equa.cc and issues a 301 to https://app.equa.cc$request_uri; the other block serves the SPA, proxies /api/ to https://equa-server-so-production.up.railway.app/, and inherits ${PORT} from the runtime environment. This is the authoritative routing story for documentation until the repo changes.
Sources:
equa-web/nginx.conf, Lines: 4-29equa-web/Dockerfile, Lines: 44-49
Live_edge_baseline
The live edge must be treated as a separate measurement layer. The following snapshot was captured at2026-05-03T16:09:41Z against equa-web commit 3131f1699ae9df3dcf3655611bc8fb247afbb33e; re-run it before any DNS, OAuth, or cutover decision.
Use this table to distinguish live behavior from committed intent. The runbook explains how to refresh each row and how to prepend
captured_at plus equa_web_commit headers when pasting evidence into a PR or ticket.
Source: equa-web/specs/037-docs-deploy-truth/VALIDATION-RUNBOOK.md, Sections: 1-5
Legacy_GCP_notes
The repository still contains the previous Cloud Run deploy path forequa-backend. Keep that material for cost, rollback, and historical architecture context only. Do not describe Cloud Run as the sole current browser/API path unless a direct endpoint is re-verified and explicitly labeled as an alternate endpoint.
Source: equa-server/cloudbuild.yaml, Lines: 13-46
Target_Spec040
Spec 040 is still the cutover target: the marketing site and authenticated SPA converge on canonicalequa.cc, and app.equa.cc becomes the redirect. That plan remains separate from the interim nginx story and separate from the live-edge baseline above.
Source: command-center-so/specs/040-equa-cc-landing-rebuild/spec.md, Section: 3.1
Verifying Edge Behavior
For operator captures, use the read-only validation runbook inequa-web rather than copying shell snippets out of this page. GitHub permalink: Spec 037 validation runbook
Legacy GCP Cloud Run Reference
Cloud Build Pipeline
Source:equa-server/cloudbuild.yaml
Cloud Run Service Configuration
Docker Configurations
Backend: equa-server
Source:equa-server/Dockerfile
Build dependencies: git, python3, make, g++ (for native npm module compilation)
Process manager: PM2 v5 (
pm2-runtime start ecosystem.config.js --only api)
Health check: wget --spider http://localhost:3000/ every 30s (3s timeout, 5s start period, 3 retries)
Environment variables:
Source:
equa-server/Dockerfile (full file), equa-server/README.md (database env vars), equa-server/modules/api/src/server.ts lines 53-97 (SSL and port config).
Frontend: equa-web
Source:equa-web/Dockerfile
Build settings:
NODE_OPTIONS=--openssl-legacy-provider(required for older webpack/SSL compatibility)API_URL=/api/v1(baked into the build)- Webpack runs via
npx webpack --mode production(changed from directnode_modules/.bin/webpackin PR #501) - A post-install verification step checks for the webpack binary and fails fast with a clear error if missing
Nginx configuration (
equa-web/nginx.conf):
Dynamic PORT (PR #516): Prior to 2026-04-02,
nginx.conf hard-coded listen 8080. Railway injects a $PORT env var per service instance and the hard-coded value worked only because it happened to match the Dockerfile EXPOSE. PR #516 changed the config to listen ${PORT} and runs envsubst on the template before nginx starts, so the container honours whatever port Railway assigns. Local docker run still defaults to 8080 via the Dockerfile ENV PORT=8080.
Source: equa-web/Dockerfile (full file), equa-web/nginx.conf (full file), PR #516 (2026-04-02).
Railway Deployments
Four services have Railway deployment configurations:equa-server (Railway)
Source:equa-server/railway.toml
equa-web (Railway)
Source:equa-web/railway.toml
equa-patternlib (Railway — Storybook)
Source:equa-patternlib-nextjs/railway.toml
Command Center (Railway)
Source:command-center-so/railway.toml
DNS and Networking
Host-by-Host Baseline
www.equa.cc was intentionally a soft check in the automated smoke workflow while DNS was missing. As of the 2026-05-03T16:09:41Z capture, it resolves and redirects successfully; keep the soft-check behavior until the cutover contract is explicitly tightened.Source: equa-web/.github/workflows/equa-cc-domain-smoke.yml, Lines: 31-46Reverse Proxy (Nginx)
In the committed interim config,equa-web’s nginx container handles both host redirect behavior and the same-origin API path:
Host (equa-server-so-production.up.railway.app), X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.
Source: equa-web/nginx.conf, Lines: 4-29
AWS Services (Active in Codebase)
S3 File Storage
The file-storage module uses the AWS SDK v2 for S3 operations:
Configuration via
AwsFileStorageConfig (env vars — bucket name, region, access key, secret key).
SES Email
The notifications module uses AWS SES as the primary email transport with SMTP as fallback: Source:equa-server/modules/notifications/src/nodemailer/email-notifier.ts
Database Infrastructure
PostgreSQL (Confirmed from Code)
Connection environment variables:
equa-server/README.md lines 14-23.
Production Database
SSL/TLS
Cloud Run (Automatic)
Cloud Run provides automatic HTTPS with Google-managed SSL certificates for the service URL (equa-server-333648330110.us-central1.run.app).
Custom Domains
Server-Side SSL (Optional)
The equa-server supports optional SSL termination at the application level:
When enabled, Express starts an HTTPS server instead of HTTP. This is typically not needed when running behind Cloud Run or a reverse proxy that handles TLS termination.
Source:
equa-server/modules/api/src/server.ts lines 53-80.
Local Development Setup
Service Map
Proxy Configuration (Development)
In development, the Webpack dev server handles API proxying:
Source:
equa-web/webpack.config.js (dev server proxy configuration).
Prerequisites
- Node.js 18+ for
equa-web/equa-server; Node 22+ forequabot-gateway(see Developer Setup for per-repo version table) - Yarn (equa-server and equa-web use Yarn workspaces)
- npm (command-center-so, equa-patternlib use npm)
- PostgreSQL (local or Docker:
docker run -e POSTGRES_PASSWORD=password -p 5432:5432 postgres) - Git (all repos cloned to
/Users/shawnowen/Documents/repos/)
Setup Steps
equa-server/README.md, equa-web/package.json scripts, command-center-so/package.json scripts.
Health Endpoints
Source:
equa-server/modules/api/src/server.ts lines 110-117, equa-web/nginx.conf, Lines: 54-58
Wind-Down Status
Decision Context
Redeployment Triggers
- Feature-complete local version (Mac/iOS desktop app)
- Paying customer pipeline ready
- Funding available for hosting
- Hosting platform decision finalized (GCP vs Railway vs other)
Wind-Down Runbook
A detailed runbook exists atequabot/threads/wind-down-equa-cc-public-instance/WIND-DOWN-RUNBOOK.md covering:
- Pre-flight scope confirmation
- Inventory of all billable GCP resources
- Database and config backups/exports
- Traffic cutover and service scaling
- Cost verification
Cost Analysis
The cost check runbook atstacks-ranking-priorities/runbooks/EQUA_CC_COST_CHECK.md identifies common lingering charge sources:
- Cloud SQL (often #1 cost driver)
- Cloud Load Balancing (forwarding rules, URL maps, proxies)
- Cloud NAT (if used)
- Compute Engine (disks, snapshots)
- Artifact Registry storage
- Cloud Logging ingestion/retention
Appendix: Unconfirmed Items Requiring Audit
The following items cannot be verified from source code alone and require access to external systems. Use the Phase 1 Audit Runbook for step-by-step instructions to complete these audits and then update this document.Google Drive / Confluence Audit Required
GCP Console Access Required
AWS Console Access Required
Once these audits are complete, the “Unconfirmed” sections in this document should be updated with verified details and the warning boxes removed.
Deployment Checklist
Source: Confluence KnowledgeBase — Deployment Checklist (by Christopher Johnson, v2.27.0)
Standard Deployment Procedure
- Pull code
- Bump versions
- Push frontend staging code
- Push backend staging code
- Notify team that deployment has started
- Push frontend production code
- Push backend production code
- Restart backend server
- Migrate database
- Watch for frontend to finish deploying
- Check production site
- Notify team that deployment is finished
Pre-Deploy Checks (supplementary)
- All tests passing on target branch
- Database migrations reviewed and tested on staging
- Environment variables verified for target environment
- Stakeholder sign-off obtained
Post-Deploy Verification (supplementary)
- Health endpoint responds 200
- Login flow functional
- Key API endpoints return expected data
- No new error spikes in monitoring
Rollback Procedure
- Identify the issue (logs, monitoring, user reports)
- Revert to previous Cloud Run revision or Railway deployment
- Verify rollback successful
- Investigate root cause before re-deploying