Cloud Build Deployment Guide - V5 + theia Combined

Last Updated: 2025-10-13 Status: ✅ Ready to Deploy (All lessons learned applied)

---

🎯 Quick Deploy

cd /home/hal/v4/PROJECTS/t2
gcloud builds submit --config cloudbuild-combined.yaml --project=serene-voltage-464305-n2

Expected Time: 60 minutes Expected Cost: ~$0.10

---

📋 Prerequisites Checklist

Before deploying, verify these fixes are in place:

✅ Fix #1: .dockerignore Updates

# Verify these lines are commented out:
grep "# dist/" .dockerignore
grep "# theia-app/" .dockerignore

Status: ✅ APPLIED

✅ Fix #2: theia-app/package.json Dependencies

# Verify lodash and MCP SDK are present:
grep "lodash" theia-app/package.json
grep "@modelcontextprotocol/sdk" theia-app/package.json

Expected output:

"lodash": "^4.17.21",
"@modelcontextprotocol/sdk": "1.15.1"

Status: ✅ APPLIED

✅ Fix #3: Use dockerfile.local-test

# Verify Cloud Build uses correct Dockerfile:
grep "dockerfile.local-test" cloudbuild-combined.yaml

Status: ✅ APPLIED

✅ Fix #4: V5 Frontend Build

# Verify dist/ folder exists with production build:
ls -lh dist/

Expected:

• dist/index.html (~0.6 KB)
• dist/assets/index-*.js (~1.2 MB)
• dist/assets/index-*.css (~5 KB)

Status: ✅ COMPLETED (2025-10-13 06:42 UTC)

---

🚀 Deployment Process

Step 1: Verify Prerequisites (5 minutes)

# Authenticate with GCP
gcloud auth login
gcloud config set project serene-voltage-464305-n2

# Get GKE credentials
gcloud container clusters get-credentials codi-poc-e2-cluster \
  --region=us-central1-a \
  --project=serene-voltage-464305-n2

# Verify namespace exists
kubectl get namespace coditect-app

Step 2: Submit Cloud Build (1 minute)

cd /home/hal/v4/PROJECTS/t2

# Submit build
gcloud builds submit \
  --config cloudbuild-combined.yaml \
  --project=serene-voltage-464305-n2

What happens:

1. Context Upload (~5 minutes) - Uploads code to Cloud Build
2. theia Build (~25 minutes) - npm install + npm run prepare + webpack compilation
3. Image Creation (~5 minutes) - Copy dist/, theia, NGINX config
4. Push to Registry (~5 minutes) - Push to Artifact Registry
5. Deploy to GKE (~10 minutes) - Update Kubernetes deployment (3 pods)

Total: ~50-60 minutes

Step 3: Monitor Build (60 minutes)

# Get latest build ID
BUILD_ID=$(gcloud builds list --limit=1 --format='value(id)')

# Stream logs
gcloud builds log $BUILD_ID --stream

# Or watch in browser:
# https://console.cloud.google.com/cloud-build/builds?project=serene-voltage-464305-n2

Success indicators:

✓ Step #1: Docker build completed successfully
✓ Step #2: Image pushed to us-central1-docker.pkg.dev/.../coditect-combined:latest
✓ Step #3: Deployment updated (coditect-combined)

Step 4: Verify Deployment (5 minutes)

# Check pods
kubectl get pods -n coditect-app | grep coditect-combined

# Expected output:
# coditect-combined-xxxxx-yyy   1/1   Running   0   2m
# coditect-combined-xxxxx-zzz   1/1   Running   0   2m
# coditect-combined-xxxxx-www   1/1   Running   0   2m

# Check logs
kubectl logs -n coditect-app -l app=coditect-combined --tail=50

# Expected:
# ✓ NGINX running (PID: ...)
# ✓ theia running on port 3000

Step 5: Test Deployment (5 minutes)

# Test health endpoint
curl https://coditect.ai/health
# Expected: "healthy"

# Test V5 frontend
curl -I https://coditect.ai/
# Expected: HTTP/2 200

# Test theia
curl -I https://coditect.ai/theia/
# Expected: HTTP/2 200

Browser testing:

1. Open https://coditect.ai/ → V5 UI loads ✅
2. Click "workspace" tab → theia IDE loads ✅
3. Open terminal → Type commands ✅
4. Edit file → Monaco editor works ✅
5. Browse files → File explorer works ✅

---

📚 Lessons Learned from Local Build Testing

Issue #1: Missing package-lock.json

Error: npm ci requires package-lock.json Fix: Changed npm ci → npm install in Dockerfile Applied: ✅ dockerfile.local-test line 17

Issue #2: Missing lodash dependency

Error: Module not found: 'lodash/debounce' Fix: Added "lodash": "^4.17.21" to theia-app/package.json Applied: ✅ theia-app/package.json line 30

Issue #3: .dockerignore blocking files

Error: COPY failed: no source files found Fix: Commented out dist/ and theia-app/ in .dockerignore Applied: ✅ .dockerignore lines 9, 73

Issue #4: Missing MCP SDK dependency

Error: Cannot find module '@modelcontextprotocol/sdk' Fix: Added "@modelcontextprotocol/sdk": "1.15.1" to theia-app/package.json Applied: ✅ theia-app/package.json line 31

Issue #5: Python dependency conflicts

Error: Could not find any Python installation to use Solution: Use dockerfile.local-test with pre-built dist/ instead of dockerfile.combined Applied: ✅ cloudbuild-combined.yaml line 10

---

🔍 Build Timeline (from local testing)

Based on 5 local build attempts:

Stage	Duration	Caching
Context upload	2-5 min	N/A
npm install (theia)	3-5 min	Yes (node_modules)
npm run prepare	20-25 min	Partial (webpack)
Webpack compilation	5-10 min	Yes (chunks)
Image creation	2-5 min	Partial (layers)
Push to registry	3-5 min	N/A
Total	35-55 min	First build: ~55 min, Subsequent: ~35 min

Expected Cloud Build time: 50-60 minutes (slightly slower due to network overhead)

---

🐛 Troubleshooting

Build Fails at "npm install"

# Error: EACCES or permission denied
# Fix: Check .dockerignore doesn't block theia-app/
grep "^theia-app/" .dockerignore  # Should return nothing (line should be commented)

Build Fails at "webpack compilation"

# Error: Module not found
# Fix: Ensure lodash is in theia-app/package.json
grep "lodash" theia-app/package.json

Container Fails to Start

# Error: Cannot find module '@modelcontextprotocol/sdk'
# Fix: Ensure MCP SDK is in theia-app/package.json
grep "@modelcontextprotocol/sdk" theia-app/package.json

# Check pod logs
kubectl logs -n coditect-app <POD_NAME>

Build Timeout (>60 minutes)

# Increase timeout in cloudbuild-combined.yaml:
timeout: '7200s'  # 2 hours

Out of Memory During Build

# Use larger machine type in cloudbuild-combined.yaml:
options:
  machineType: 'E2_HIGHCPU_32'  # 32 CPUs, 32 GB RAM

---

📊 Resource Metrics

Build Resources (Cloud Build)

• Machine: E2_HIGHCPU_8 (8 CPUs, 8 GB RAM)
• Disk: 100 GB
• Memory Peak: ~6 GB (during webpack compilation)
• CPU Peak: 70-80% (during npm install)

Final Image

• Size: ~1.46 GB
• Layers: 15
• Compression: Good (uses multi-stage build)

Deployed Pods (3 replicas)

• RAM per pod: 1-2 GB (requested: 1 GB, limit: 2 GB)
• CPU per pod: 0.5-1 core (requested: 500m, limit: 1000m)
• Total Cost: ~$160/month (3 pods × $53/month)

---

✅ Success Criteria

Before marking deployment complete:

• Cloud Build succeeds (status: SUCCESS)
• Image pushed to Artifact Registry
• 3 pods Running in coditect-app namespace
• All pods pass readiness checks
• Health endpoint returns "healthy"
• V5 frontend loads at https://coditect.ai/
• theia IDE loads at https://coditect.ai/theia
• Monaco editor works (can edit files)
• terminal works (can type commands)
• File explorer works (can browse files)
• WebSocket stable (terminal doesn't disconnect)
• No errors in browser console
• No errors in pod logs

---

📞 Support

Check Build Status

# List recent builds
gcloud builds list --limit=5

# Get build details
gcloud builds describe <BUILD_ID>

Check Deployment Status

# Get all resources
kubectl get all -n coditect-app | grep coditect-combined

# Check events
kubectl get events -n coditect-app --sort-by='.lastTimestamp' | tail -20

# Check resource usage
kubectl top pods -n coditect-app

Rollback Deployment

# Rollback to previous version
kubectl rollout undo deployment coditect-combined -n coditect-app

# Check rollout status
kubectl rollout status deployment coditect-combined -n coditect-app

---

🔗 Related Documentation

• README.md - Project overview
• deployment-summary.md - Architecture overview
• DEPLOYMENT-architecture.md - Detailed architecture
• checkpoint-docker-setup.md - Local build testing summary
• docs/06-backend/gcp-cloud-build-guide.md - GCP reference

---

🎉 Ready to Deploy!

All prerequisites are met. All lessons learned have been applied. The build configuration has been tested locally and succeeded.

Next step:

gcloud builds submit --config cloudbuild-combined.yaml --project=serene-voltage-464305-n2

Good luck! 🚀