Skip to main content

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:41Z against equa-web commit 3131f1699ae9df3dcf3655611bc8fb247afbb33e

Deployment History Timeline

Era 1: AWS (Prior Deployment)

Unconfirmed — Requires Google Drive/Confluence AuditThe Equa platform was previously deployed on AWS. Evidence of AWS services that remain active in the codebase:
  • AWS S3 — File storage via aws-sdk/clients/s3 in equa-server/modules/file-storage/src/s3.d.ts
  • AWS SES — Email sending via equa-server/modules/notifications/src/nodemailer/email-notifier.ts
The full AWS deployment architecture (compute service, database, networking, and migration details) is documented in Google Drive and Confluence but has not yet been audited or exported locally. This section will be completed after that audit.Items to confirm:
  • Compute: EC2, ECS, Elastic Beanstalk, or Lambda?
  • Database: RDS PostgreSQL instance details
  • Networking: VPC, load balancer, SSL certs
  • Migration timeline: When and why moved to GCP

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 in equa-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-29
  • equa-web/Dockerfile, Lines: 44-49

Era 4: Spec 040 Target

Spec 040 still targets equa.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-29
  • equa-web/Dockerfile, Lines: 44-49

Live_edge_baseline

The live edge must be treated as a separate measurement layer. The following snapshot was captured at 2026-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 for equa-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 canonical equa.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 in equa-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

Unconfirmed — Requires GCP Console Access
  • GCP Project ID ($PROJECT_ID in cloudbuild.yaml)
  • Cloud SQL instance details (type, tier, version, connection method)
  • Load balancer name and configuration specifics
  • Static IP reservation details
  • Monthly cost breakdown by SKU
The GCP cost check runbook at stacks-ranking-priorities/runbooks/EQUA_CC_COST_CHECK.md identifies Cloud SQL as the #1 cost driver.

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 direct node_modules/.bin/webpack in PR #501)
  • A post-install verification step checks for the webpack binary and fails fast with a clear error if missing
Required environment variables for build:
The build requires GH_PATTERNLIB_TOKEN to be set as a Railway service variable. Without it, yarn install silently fails to fetch equa-patternlib (SSH clone fails on Alpine), leaving node_modules corrupt. PR #501 added a verification step that catches this early.
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-46

Reverse Proxy (Nginx)

In the committed interim config, equa-web’s nginx container handles both host redirect behavior and the same-origin API path:
Headers set on the backend hop: 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).
Unconfirmed: S3 bucket name, region, and whether this is the same AWS account as the prior full AWS deployment.

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
Unconfirmed: SES region, verified sender domains/emails, and sending limits.

Database Infrastructure

PostgreSQL (Confirmed from Code)

Connection environment variables:
Source: equa-server/README.md lines 14-23.

Production Database

Unconfirmed — Requires GCP Console AccessThe production database is likely a managed PostgreSQL service, with Cloud SQL as the leading historical candidate, based on:
  • stacks-ranking-priorities/runbooks/EQUA_CC_COST_CHECK.md identifies Cloud SQL as the #1 cost driver
  • The wind-down runbook at equabot/threads/wind-down-equa-cc-public-instance/WIND-DOWN-RUNBOOK.md explicitly marks the database type as unknown (“Cloud SQL? Firestore? both?”)
Items to confirm:
  • Managed database provider, instance name, tier, and PostgreSQL version
  • Connection method (provider proxy, direct IP, Unix socket, or equivalent)
  • Backup configuration and retention
  • Storage size and IOPS

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

Partially VerifiedPublic TLS termination is currently split by host. The 2026-05-03 baseline saw equa.cc reply through Google-managed infrastructure while app.equa.cc replied with Railway headers, so certificate ownership and edge termination must be re-verified per host before treating any DNS/HTTP prose as authoritative.

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

  1. Node.js 18+ for equa-web / equa-server; Node 22+ for equabot-gateway (see Developer Setup for per-repo version table)
  2. Yarn (equa-server and equa-web use Yarn workspaces)
  3. npm (command-center-so, equa-patternlib use npm)
  4. PostgreSQL (local or Docker: docker run -e POSTGRES_PASSWORD=password -p 5432:5432 postgres)
  5. Git (all repos cloned to /Users/shawnowen/Documents/repos/)

Setup Steps

Source: 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

  1. Feature-complete local version (Mac/iOS desktop app)
  2. Paying customer pipeline ready
  3. Funding available for hosting
  4. Hosting platform decision finalized (GCP vs Railway vs other)

Wind-Down Runbook

A detailed runbook exists at equabot/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 at stacks-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

  1. Pull code
  2. Bump versions
  3. Push frontend staging code
  4. Push backend staging code
  5. Notify team that deployment has started
  6. Push frontend production code
  7. Push backend production code
  8. Restart backend server
  9. Migrate database
  10. Watch for frontend to finish deploying
  11. Check production site
  12. 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