Skip to main content

New Environment Provisioning Scripts

This directory contains Software Development Life Cycle (SDLC) scripts to provision new GCP environments for the Construction Code Expert project

Update Placeholder Vars in Templates​

Automated script to update placeholder values in environment configuration files by retrieving actual values from deployed Cloud Run services.

Usage (recommended - from workspace root):

cli/sdlc/new-environment-provisioning/update-placeholder-vars.sh <environment>

Examples:

# Update placeholders for test environment
cli/sdlc/new-environment-provisioning/update-placeholder-vars.sh test

# Update placeholders for dev environment  
cli/sdlc/new-environment-provisioning/update-placeholder-vars.sh dev

Note: The script automatically finds the workspace root, so it can be run from any directory within the repository.

What it does:

  1. Validates environment and workspace
  2. Loads environment configuration
  3. Retrieves deployed gRPC service URL
  4. Retrieves GCP project number
  5. Updates backend hostname placeholders
  6. Updates project number placeholders
  7. Shows remaining manual configuration steps

Reserve ESPv2 Service Name​

Automated script to reserve ESPv2 (Envoy Proxy) service hostname by deploying a dummy Cloud Run service and updating configuration files.

Usage (recommended - from workspace root):

cli/sdlc/new-environment-provisioning/reserve-espv2-servicename.sh <environment>

Examples:

# Reserve ESPv2 hostname for test environment
cli/sdlc/new-environment-provisioning/reserve-espv2-servicename.sh test

# Reserve ESPv2 hostname for prod environment
cli/sdlc/new-environment-provisioning/reserve-espv2-servicename.sh prod

Note: The script automatically finds the workspace root, so it can be run from any directory within the repository.

What it does:

  1. Validates environment and workspace
  2. Loads endpoints configuration
  3. Deploys dummy service to reserve hostname
  4. Retrieves the reserved ESPv2 hostname
  5. Updates ESPv2 hostname placeholders in config files
  6. Shows next steps for actual ESPv2 deployment

Integration with other scripts:

  • Run this before update-placeholder-vars.sh to set ESPv2 hostnames
  • Run this after gRPC service deployment
  • Prepares environment for actual ESPv2 proxy deployment

Setup Google Maps API​

Automated script to configure Google Maps JavaScript API and Places API for frontend address autocomplete and map visualization features.

Usage (recommended - from workspace root):

cli/sdlc/new-environment-provisioning/setup-google-maps-api.sh <environment>

Examples:

# Setup Google Maps API for demo environment
cli/sdlc/new-environment-provisioning/setup-google-maps-api.sh demo

# Setup Google Maps API for prod environment
cli/sdlc/new-environment-provisioning/setup-google-maps-api.sh prod

Note: The script automatically finds the workspace root, so it can be run from any directory within the repository.

What it does:

  1. Enables Google Maps JavaScript API and Places API
  2. Creates restricted API key for browser/frontend use
  3. Applies API restrictions (Maps + Places only)
  4. Applies domain restrictions (Firebase + custom domains + localhost)
  5. Stores API key in Secret Manager (for centralized management)
  6. Tests API key with sample geocoding request
  7. Displays frontend configuration instructions
  8. Shows quota setup and monitoring URLs
  9. Provides deployment next steps

Prerequisites:

  • GCP project created and configured
  • Billing account linked to project
  • Firebase hosting domain known (e.g., construction-code-expert-test-m3.web.app)
  • Custom domain configured (e.g., test.m3.codeproof.app)

Integration with other scripts:

  • Run this before frontend build and deployment
  • Does NOT require Cloud Run service (client-side API key only)
  • Required for: Address autocomplete, map widgets

Manual Steps After Script:

  1. Update frontend environment.${ENV}.ts with API key (or use build-time injection)
  2. Rebuild frontend bundle with API key
  3. Deploy to Firebase Hosting
  4. Set API quotas in GCP Console (10k req/day recommended)
  5. Enable billing alerts ($50/month recommended)
  6. Test address autocomplete and map display

Important Note: This script configures a browser API key (client-side), not a server secret. The key will be visible in the browser (this is normal). Security is enforced by domain referrer restrictions, not by hiding the key.

Related Documentation:

Provision GCS Bucket​

Automated script to provision GCS bucket with selective seed data copying using gsutil rsync.

Usage (recommended - from workspace root):

cli/sdlc/new-environment-provisioning/provision-gcs-bucket.sh <environment> <source-environment>

Examples:

# Provision test bucket with seed data from dev
cli/sdlc/new-environment-provisioning/provision-gcs-bucket.sh test dev

# Provision prod bucket with seed data from demo
cli/sdlc/new-environment-provisioning/provision-gcs-bucket.sh prod demo

# Provision demo bucket with seed data from dev
cli/sdlc/new-environment-provisioning/provision-gcs-bucket.sh demo dev

Note: The script automatically finds the workspace root, so it can be run from any directory within the repository.

What it does:

  1. Validates environment and workspace
  2. Loads environment configuration
  3. Creates GCS bucket with proper settings
  4. Configures CORS policy for frontend uploads
  5. Copies selective seed data (api/ and database/ folders only)
  6. Shows bucket verification and next steps

Benefits over manual copying:

  • Selective copying: Only copies api/ and database/ folders (not everything)
  • Efficient: Uses gsutil rsync for faster, incremental copying
  • Safe: Checks if bucket exists before creating
  • Configurable: Can specify different source environments

Deploy to New Environment​

Automated deployment script for the gRPC backend service to Google Cloud Run.

Usage:

cli/sdlc/cloud-run-grpc/deploy.sh [env] [options]

Arguments:

  • env - Environment to deploy to: dev, demo, prod, or test (default: dev)

Options:

  • --skip-build - Skip the Maven build step and deploy existing JAR
  • --skip-tests - Skip unit tests during build (faster build)
  • --help, -h - Show help message

Examples:

# Build and deploy to dev environment
cli/sdlc/cloud-run-grpc/deploy.sh dev

# Build and deploy to test environment
cli/sdlc/cloud-run-grpc/deploy.sh test

# Deploy to production without rebuilding
cli/sdlc/cloud-run-grpc/deploy.sh prod --skip-build

# Build without tests and deploy to demo
cli/sdlc/cloud-run-grpc/deploy.sh demo --skip-tests

# Show help
cli/sdlc/cloud-run-grpc/deploy.sh --help

Prerequisites:

  • Java 17+ installed
  • Apache Maven installed
  • Google Cloud SDK (gcloud) installed and authenticated
  • Environment configuration files in env/{env}/gcp/cloud-run/grpc/
    • setvars.sh - Environment variables
    • vars.yaml - Cloud Run environment variables

Features:

  • ✅ Automatic environment validation
  • ✅ Maven build with optional test skipping
  • ✅ Cloud Run deployment with proper resource allocation (4Gi memory, 8 CPU)
  • ✅ Service account configuration
  • ✅ Environment-specific configuration loading
  • ✅ Comprehensive error handling and validation
  • ✅ Deployment summary with service URL
  • ✅ Success sound notification (macOS)

Resource Configuration: The script deploys with the following Cloud Run configuration:

  • Memory: 4Gi (required for processing large PDF files)
  • CPU: 8 (required for multi-threading and concurrency)
  • Service Account: google-groups-member-checker@{project}.iam.gserviceaccount.com
  • Allow unauthenticated access
  • Environment variables loaded from vars.yaml

This configuration is based on the requirements documented in GitHub Issue #132.

Deploy WebSocket Chat Service​

Automated deployment script for the WebSocket chat service to Google Cloud Run (Issue #270).

Usage:

env/deploy-websocket.sh [env]

Arguments:

  • env - Environment to deploy to: dev, demo, prod, or test (required)

Examples:

# Deploy to test environment
cd env && ./deploy-websocket.sh test

# Deploy to production
cd env && ./deploy-websocket.sh prod

Prerequisites:

  • Java 23+ installed (auto-detected via cli/sdlc/utils/detect-java-home.sh)
  • Apache Maven installed
  • Docker installed and authenticated to GCR
  • Google Cloud SDK (gcloud) installed and authenticated
  • Environment configuration files in env/{env}/gcp/cloud-run/websocket/
    • setvars.sh - Service name and account configuration
    • vars.yaml - Cloud Run environment variables

What it does:

  1. Detects Java installation (cross-platform)
  2. Builds JAR with Maven
  3. Builds Docker image for linux/amd64 architecture
  4. Pushes image to Google Container Registry
  5. Deploys to Cloud Run with WebSocket configuration
  6. Prints WebSocket service URL

Features:

  • ✅ Automatic Java detection (dev container, macOS, Linux)
  • ✅ Cross-architecture build (ARM64 → AMD64)
  • ✅ Firebase authentication integration
  • ✅ ADK agent initialization with OpenApiToolset
  • ✅ Javalin WebSocket server (lightweight, fast)
  • ✅ Health check endpoint at /health
  • ✅ CORS configuration for browser access

Resource Configuration: The script deploys with the following Cloud Run configuration:

  • Memory: 2Gi (sufficient for chat agent and ADK)
  • CPU: 2 (handles concurrent WebSocket connections)
  • Service Account: cce-app-service@{project}.iam.gserviceaccount.com
  • Allow unauthenticated access (authentication on WebSocket connection)
  • Environment variables loaded from vars.yaml
  • Timeout: 300s (5 minutes for long agent responses)

Architecture:

Frontend → WebSocket Service (construction-code-expert-ws-{env})
              ↓
         ADK Agent (Gemini 2.5 Flash)
              ↓
         Calls tools via CHAT_API_BASE_URL
              ↓
         ESPv2 Proxy → Main gRPC Service

Post-Deployment: After deployment, update the frontend configuration with the WebSocket URL:

# File: env/{env}/firebase/m3/setvars.sh
export CODEPROOF_WS_SERVER=construction-code-expert-ws-{env}-{hash}.{region}.run.app

# Regenerate environment.ts
cd web-ng-m3 && node scripts/set-env.js {env}