04. Infrastructure Ops: Environments & Deployment

Status: Active / Golden Version: 1.0 (Consolidated Jan 2026)

"The Plumbing: How code travels from the IDE to Production."

1. The Environment Rings

We treat the platform as a Single Logical Application existing in three states.

Ring	Environment	Alias	Description	Stack
1	Local	"The Workbench"	Fast & Fake. Rapid iteration.	`localhost` + Firebase Emulator
2	Staging	"The Lab"	Real but Safe. Integration testing.	Vercel Preview + Doppler `stg` + Firebase `singular-dream-stg`
3	Production	"The Show"	Live & Dangerous. Real Data.	Vercel Prod + Doppler `prd` + Firebase `singular-dream`

Context Switching

Developers can simulate Ring 2/3 locally using environment files:

# Switch to staging
cp .env.stg .env.local

# Switch to production
cp .env.prd .env.local

See 3-Tier Architecture Guide for details.

1.5 Remote Development Environment (Elastic Muscle)

Elastic Muscle is our GCP-based remote development server for parallel processing and heavy workloads.

Property	Value
Instance Name	`antigravity-muscle`
Machine Type	`e2-highcpu-32`
vCPUs	32
RAM	32GB
Zone	`us-central1-a`
Provisioning	SPOT (cost-optimized)
IP Address	34.29.247.230 (static)

SSH Configuration

Host antigravity-muscle
    HostName 34.29.247.230
    User michaelhiggins
    IdentityFile ~/.ssh/id_rsa
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

Health Check

The scripts/check-elastic-muscle.ts script verifies instance status and auto-restarts if preempted.

Integrated into: Sunrise Protocol (pnpm sunrise)

Use Cases

✅ Parallel testing (unit, integration, e2e)
✅ Multi-app builds (marketing + platform simultaneously)
✅ Heavy compilation tasks
✅ Multi-agent browser testing
✅ Database migrations
✅ Large-scale validation scripts

Context Awareness

Always verify execution context before heavy operations:

# Check if running locally or on Elastic Muscle
hostname  # Returns "antigravity-muscle" if on remote server

2. Secret Management (Doppler)

Doppler is the Single Source of Truth for secrets. * Rule: No .env files in git (except templates: .env.dev, .env.stg, .env.prd). * Rule: No manual hacking of keys. * Local Usage: Copy appropriate .env.* to .env.local and restart dev server.

Authentication: * Production: Uses firebase-adminsdk-fbsvc service account. * Rotation: Service Account Keys rotated Annually. * 3-Tier Isolation: Each environment has dedicated service account and Firebase project.

3. The Automaton Script Catalog

The scripts/ directory contains the "Nervous System" of our operations. These are not optional helpers; they are the primary interface for developing Single Dream.

Lifecycle Scripts

Command	Script	Purpose
`pnpm sunrise`	`sunrise.ts`	The Morning Protocol. Wakes up the system, checks health, updates deps.
`pnpm ghostbuster`	`ghostbuster.ts`	The Exorcist. Hunts and kills zombie node processes/ports (3000, 8080).
`switch:context`	`switch-context.ts`	The Portal. Swaps `.env` keys to teleport between Local/Testing/Prod.
`pnpm dev`	`dev-mode.ts`	The Engine. Orchestrates Turbo + Emulators based on current context.

Verification & Auditing

Command	Script	Purpose
`audit:routes`	`audit-routes.ts`	Scans `app/` directory and generates an inventory of all accessible URLs.
`audit:imports`	`depcruise`	Detects "Toxic Barrel" circular dependencies in Server Actions.
`verify:*`	`verify-*.ts`	A suite of 30+ domain-specific logic tests (e.g., `verify-finance.ts`). See Book 06 Section 9.

Seeding (Hydration)

Command	Script	Purpose
`seed:golden`	`seed-golden-integrated.ts`	Resets the DB to a "Perfect State" with 1 Tower, 50 Units, and clean ledgers.
`seed:chaos`	`seed-chaos.ts`	Injects random entropy (broken workflows, late payments) for stress testing.

4. The 3-Tier Promotion Pipeline

We follow a professional Development → Staging → Production flow to ensure absolute stability.

6.2 CI/CD Pipeline Standards (Standard 14.3)

Parallel Check Strategy: Verification jobs (Lint, TSC, Vitest) MUST run in parallel.
Memory Limits: The monorepo requires NODE_OPTIONS: "--max-old-space-size=4096" for the type-check (TSC) job to prevent OOM errors.
Frozen Lockfile: Use pnpm install --frozen-lockfile in all CI environments.

A. Phase 1: Development (`dev`)

Purpose: Sandbox for active coding and feature integration.
Triggers: Commits to dev or PRs targeting it.
CI/CD: Triggers Verification (Lint, Type-Check, Audit).
Deploy: Vercel Development. Firebase Rules synced to singular-dream-dev.
Environment: Uses Doppler dev configuration.

B. Phase 2: Staging (`stg`)

Purpose: Testing & QA. Real environment for stakeholder review.
Triggers: Merges from dev → stg.
CI/CD: Triggers Deployment Checks + Cloud Testing.
Deploy: Vercel Preview deployment. Firebase Rules synced to singular-dream-stg.
Environment: Uses Doppler stg configuration (Staging Ring).

C. Phase 3: Production (`main`)

Purpose: The Live Platform.
Triggers: Merges from stg → main.
CI/CD: Full verification pass.
Deploy: Vercel Production deployment. Firebase Rules synced to singular-dream.
Environment: Uses Doppler prd configuration.

5. The Deployment Matrix

Env	Branch	Doppler	Vercel Env	Firebase Project
Local	N/A	`dev`	N/A	Emulator
Development	`dev`	`dev`	Development	`singular-dream-dev`
Staging	`stg`	`stg`	Preview	`singular-dream-stg`
Production	`main`	`prd`	Production	`singular-dream`

Migration Completed: 2026-01-16 - Full 3-tier Firebase isolation implemented.

1.6 The Control Room (SysOps/DevOps)

The Control Room (singular-dream-ops) is the central nerve center for the Sovereign Factory. It hosts the SysOps platform which orchestrates builds, tests, and AI auto-fixes across all environment rings.

Property	Value
Instance Name	`sysops`
Project	`singular-dream-ops`
Machine Type	`e2-standard-4`
Zone	`us-central1-a`
IP Address	`34.46.38.7` (static)
Role	Deployment, Monitoring, AI Analysis, Scheduler

Access & Deployment

SSH: gcloud compute ssh sysops@sysops --project=singular-dream-ops
Port: 3001 (SysOps API)
Deployment: apps/sysops/deploy.sh handles remote updates via gcloud scp.

4.1 Deployment Standards

Standard 144: Vercel Project Drift Prevention

The Problem: Vercel's CLI "auto-detect" feature often creates duplicate projects (e.g., creating marketing when the repo is singular-dream-marketing) if the local folder name doesn't match the remote project name exactly. This separates the code from its Environment Variables, causing silent build failures.

The Solution: Strict Enforcement Scripts.

Canonical Identity: We rely on immutable ORG_ID and PROJECT_ID (hardcoded in scripts/link-vercel-canonical.sh), not project names.
The Command: Engineers MUST use the strict linker command, never vercel link manually.

# CORRECT WAY to link Vercel:
pnpm vercel:link

Implementation Details: This command executes npx vercel link --scope <ORG_ID> --project <PROJECT_ID> --yes, forcefully altering the complete .vercel/project.json to match the canonical production source.