gcp-deployment

What this skill does

# GCP Deployment & Server Management

**Purpose**: Guide for finding GCP Cloud Run services and deploying WorldArchitect.AI

⚠️ **IMPORTANT**: This skill is **ONLY** for the WorldArchitect.AI repository and GCP project. The deployment scripts, service names, and configurations are specific to this project and will not work for other repositories or GCP projects.

## Project Overview

**Repository**: https://github.com/jleechanorg/worldarchitect.ai
**Project**: WorldArchitect.AI
**GCP Project ID**: `worldarchitecture-ai` (specific to this project only)
**Region**: `us-central1`
**Platform**: Google Cloud Run (containerized deployments)

**Scope**: All commands, scripts, and service references in this document are specific to the `worldarchitecture-ai` GCP project and will not work with other GCP projects or repositories.

---

## 🎯 Quick Reference

### Service URLs

| Environment | Service Name | URL |
|-------------|--------------|-----|
| **Production** | mvp-site-app-stable | https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app |
| **Staging** | mvp-site-app-staging | https://mvp-site-app-staging-i6xf2p72ka-uc.a.run.app |
| **Development** | mvp-site-app-dev | https://mvp-site-app-dev-i6xf2p72ka-uc.a.run.app |
| **PR Preview** | mvp-site-app-s1 through s10 | Rotating pool (see PR Preview section below) |

### Health Check Endpoints

Add `/health` to any service URL:
- Production: https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app/health
- Staging: https://mvp-site-app-staging-i6xf2p72ka-uc.a.run.app/health
- Dev: https://mvp-site-app-dev-i6xf2p72ka-uc.a.run.app/health

---

## 🔍 Finding GCP Services

### Method 1: Cloud Console (Web UI)

1. **Navigate to Cloud Run**:
   ```
   https://console.cloud.google.com/run?project=worldarchitecture-ai
   ```

2. **Filter by service name**: Look for `mvp-site-app*` services

3. **View service details**: Click on any service to see:
   - Service URL
   - Revisions
   - Configuration
   - Logs
   - Metrics

### Method 2: gcloud CLI

```bash
# List all Cloud Run services
gcloud run services list \
  --project=worldarchitecture-ai \
  --region=us-central1

# Get specific service details
gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --format=yaml

# Get service URL
gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --format="value(status.url)"
```

### Method 3: From Repository

The deployment script automatically determines the correct service:

```bash
# Check what will be deployed
cat scripts/deploy_common.sh | grep -A 10 "SERVICE_NAME="
```

Service naming pattern:
- Dev: `mvp-site-app-dev`
- Staging: `mvp-site-app-staging`
- Production: `mvp-site-app-stable`

---

## 🚀 Deployment Methods

### Deployment Decision Tree

```
Need to deploy?
├─ Production/Stable? → Use GitHub Actions (Required)
├─ Staging? → Use ./deploy.sh staging (local deployment)
└─ Development? → Use ./deploy.sh (local) OR auto-deploys on push to main
```

### Method 1: Local Deployment (Dev/Staging Only)

**Development (Default)**:
```bash
./deploy.sh
# OR explicitly
./deploy.sh mvp_site
```

**Staging**:
```bash
./deploy.sh mvp_site staging
```

**Production** (BLOCKED locally):
```bash
./deploy.sh mvp_site stable
# ❌ This will fail with safety message directing you to GitHub Actions
```

**Auto-detection**:
The script automatically detects deployable apps if run from project root:
```bash
# If current directory has Dockerfile, uses current directory
# Otherwise shows interactive menu of available apps
./deploy.sh
```

### Method 2: GitHub Actions (Production & Development)

#### Production/Stable Deployment (Required Method)

**Via CLI**:
```bash
# Trigger production deployment
gh workflow run deploy-production.yml \
  -f confirm_production="DEPLOY TO PRODUCTION"

# Check deployment status
gh run list --workflow=deploy-production.yml --limit 1
gh run view <run-id>
```

**Via GitHub Web UI**:
1. Go to: https://github.com/jleechanorg/worldarchitect.ai/actions/workflows/deploy-production.yml
2. Click "Run workflow"
3. Type "DEPLOY TO PRODUCTION" in confirmation field
4. Click "Run workflow"
5. Wait for approval (protected environment)
6. Deployment proceeds after approval

**Why GitHub Actions Required for Production**:
- ✅ Proper approval process
- ✅ Full audit trail
- ✅ Prevents accidental deployments
- ✅ Team visibility
- ✅ Protected environment with manual approval gate

#### Auto-Deploy on Push to Main (Development)

Development environment auto-deploys when code is pushed to `main` branch:

**Workflow**: `.github/workflows/auto-deploy-dev.yml`

**Trigger**:
```bash
git push origin main
# Automatically triggers deployment to dev environment
```

**Check auto-deploy status**:
```bash
gh run list --workflow=auto-deploy-dev.yml --limit 3
```

---

## 📋 Deployment Script Details

### Main Script: `./deploy.sh`

**Location**: Project root
**Purpose**: Context-aware deployment with auto-detection

**Usage**:
```bash
./deploy.sh [TARGET_DIR] [ENVIRONMENT]
```

**Examples**:
```bash
# Deploy from current directory to dev (if Dockerfile exists)
./deploy.sh

# Deploy specific app to dev
./deploy.sh mvp_site

# Deploy to staging
./deploy.sh mvp_site staging

# Attempt production (will be blocked)
./deploy.sh mvp_site stable
```

**Environment Mapping**:
- `dev` (default): Development environment
- `staging`: Staging environment
- `stable`, `prod`, `production`: Production (GitHub Actions only)

### Helper Script: `scripts/deploy_common.sh`

**Purpose**: Shared deployment logic
**Contains**:
- Service name mapping
- GCP configuration
- Cloud Build submission
- Autoscaling settings

**Service Name Logic**:
```bash
if [[ "$ENVIRONMENT" == "stable" ]]; then
    SERVICE_NAME="mvp-site-app-stable"
elif [[ "$ENVIRONMENT" == "staging" ]]; then
    SERVICE_NAME="mvp-site-app-staging"
else
    SERVICE_NAME="mvp-site-app-dev"
fi
```

---

## 🔧 Configuration Details

### Autoscaling

**Current Settings** (all environments):
- **Max Instances**: 6
- **Min Instances**: 0 (scales to zero when not in use)

**Why 6 instances**:
- Sanity-check threshold to prevent runaway costs
- Adequate for current traffic patterns
- Can be adjusted in `deploy.sh` (MAX_INSTANCES variable)

### Environment Variables

**Set via GCP Console**:
1. Navigate to service in Cloud Run
2. Click "Edit & Deploy New Revision"
3. Go to "Variables & Secrets" tab
4. Add/modify environment variables

**Common variables**:
- `GEMINI_API_KEY`: Google Gemini API key
- `FIREBASE_CREDENTIALS`: Firebase service account JSON
- Environment-specific configs

### Cloud Build

**Build timeout**: 10 minutes (configurable)
**Build logs**: Streamed to terminal during deployment
**Build configuration**: Defined in `Dockerfile` in target directory

---

## 📊 Monitoring & Logs

### View Logs

**Via Console**:
```
# Production logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-stable%22

# Staging logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-staging%22

# Dev logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-dev%22
```

**Via gcloud CLI**:
```bash
# Stream production logs
gcloud run services logs read mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --limit=50

# Follow logs in real-time
gcloud run services logs tail mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1
```

### Check Service Health

```bash
# Production health check
curl https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app/health

# Staging health check
curl https://mvp-site-app-stag