Skip to main content

Deployment Overview

ForgeX uses a microservices architecture deployed on Google Cloud Platform (GCP) with subdomain-based routing. This guide covers the complete deployment workflow for production and local development.

Architecture​

┌─────────────────────────────────────────────────────────────┐
│  Cloud Load Balancer (Subdomain-Based Routing)              │
│  Static IP: 34.160.139.39                                    │
└────────────────┬────────────────────────────────────────────┘
                 │
      ┌──────────┼──────────┬──────────────┐
      │          │          │              │
      ▼          ▼          ▼              ▼
┌─────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐
│Portal   │ │Bids    │ │Projects  │ │Field     │
│forge.*  │ │bids.*  │ │projects.*│ │field.*   │
│✅ LIVE  │ │✅ LIVE │ │⏳ Phase 2 │ │⏳ Phase 3│
└─────────┘ └────────┘ └──────────┘ └──────────┘

Service URLs​

Production:

Local Development:

GCP Infrastructure​

ServiceRegionCloud Run ServiceImage
Bids Backendus-south1forge-bids-backendgcr.io/forge-475221/bids-backend:latest
Projects Backendus-south1forge-projects-backendgcr.io/forge-475221/projects-backend:latest
Field Backendus-south1forge-field-backendgcr.io/forge-475221/field-backend:latest
SuperTokens Coreus-south1forge-supertokenssupertokens/supertokens-postgresql:9.3

GCP Project: forge-475221
Cloud SQL Instance: forge-postgres-prod (Public IP: 34.174.7.92)

Quick Decision Tree​

Use this flowchart to determine what needs to be deployed:

First deployment?       → Scenario D (SuperTokens) then C (DB) then B (Backend) then A (Frontend)
Changed database schema? → Scenario C (DB) then B (Backend)
Changed backend code?    → Scenario B (Backend)
Changed frontend only?   → Scenario A (Frontend)

Deployment Scenarios​

Scenario A: Frontend-Only Deployment​

When to use:

  • UI changes
  • Frontend configuration updates
  • No API or database changes

What happens:

  • Build frontend with production environment variables
  • Upload to Google Cloud Storage bucket
  • Invalidate CDN cache
  • No backend restart required

Time: ~5 minutes (+ 3-5 min CDN propagation)

💻

Frontend Deployment

Step-by-step frontend deployment guide

Scenario B: Backend Deployment​

When to use:

  • API changes
  • Backend code updates
  • Dependency updates (package.json)
  • No schema changes

What happens:

  • Build Docker image via Cloud Build
  • Deploy to Cloud Run with environment variables
  • Backend automatically restarts
  • Database schema unchanged

Time: ~10-15 minutes

🖥️

Backend Deployment

Step-by-step backend deployment guide

Scenario C: Database Schema Changes​

When to use:

  • Prisma schema modifications
  • New tables or columns
  • Migrations

What happens:

  • Connect via Cloud SQL Proxy
  • Run npx prisma db push or migrations
  • Deploy backend (Scenario B)
  • Frontend may need rebuild if types changed

Time: ~20 minutes

warning

Always backup the database before schema changes!

🗄️

Database Migrations

Prisma migration workflow

Scenario D: SuperTokens Core Deployment​

When to use:

  • First-time setup
  • SuperTokens upgrades

What happens:

  • Create supertokens_db in Cloud SQL
  • Deploy SuperTokens Docker image to Cloud Run
  • Configure PostgreSQL connection via TCP
  • Note SuperTokens URL for backend env vars

Time: ~30 minutes (one-time setup)

🔒

SuperTokens Setup

Complete SuperTokens deployment guide

Why Subdomain Routing?​

ForgeX uses subdomain-based routing (not path-based) for several reasons:

⭐

Industry Standard

Netflix, Stripe, Slack, and GitHub all use subdomain architecture

🛡️

True Service Isolation

Independent deployment, scaling, and monitoring per service

🔒

Better Security

XSS isolation and independent CSP policies

🚀

Future-Proof

Never need to change domain structure

📖

Architecture Decision

Read the full ADR on subdomain routing

Deployment Checklist​

First-Time Deployment​

  • SuperTokens Core deployed to Cloud Run
  • SuperTokens database created
  • Google OAuth redirect URIs configured
  • Resend domain verified
  • All backend env vars set
  • Frontend built with production URLs
  • CDN cache invalidated
  • SSL certificate includes all subdomains

Regular Deployment​

  • Code changes committed and pushed
  • Backend rebuilt and deployed (if changed)
  • Frontend rebuilt with production URLs (if changed)
  • CDN cache invalidated
  • Health check passes: curl https://bids.precisionsiteservices.com/api/health
  • Login flow tested in incognito window

Rollback Strategy​

If a deployment causes issues:

Frontend:

# Restore previous bucket version
gcloud storage ls -a gs://forge-475221-bids
gcloud storage cp -r gs://forge-475221-bids#<timestamp> gs://forge-475221-bids
gcloud compute url-maps invalidate-cdn-cache forge-lb --path "/*" --async

Backend:

# Rollback to previous revision
gcloud run services update-traffic forge-bids-backend --to-revisions=PREVIOUS_REVISION=100

Database:

# Restore from automated backup
gcloud sql backups restore <BACKUP_ID> --backup-instance=forge-postgres-prod

Monitoring​

After deployment, verify these indicators:

  • Cloud Run Logs: Check for startup errors
  • Health Endpoint: curl https://bids.precisionsiteservices.com/api/health
  • Authentication: Test OAuth login flow
  • Browser Console: Check for API errors
  • Response Time: Verify acceptable latency
📈

Monitoring Setup

Complete monitoring and observability guide

Next Steps​

☁️

GCP Setup

Complete GCP Cloud Run configuration

🔑

Environment Variables

Required environment variable reference

🌐

Subdomain Routing

Multi-tenant subdomain architecture

🗄️

Database Backups

Backup and restore procedures