Skip to main content

Combined V5 + theia Deployment Guide

Overview​

This deployment combines both the V5 React frontend AND the Eclipse theia IDE backend into a single Docker container, deployed to GKE.

Architecture​

┌─────────────────────────────────────────────────────┐
│  GKE Pod: coditect-combined                         │
├─────────────────────────────────────────────────────┤
│                                                      │
│  NGINX (Port 80)                                    │
│  ├─→ / → V5 Frontend (React SPA from dist/)        │
│  └─→ /theia → theia Backend (Node.js on port 3000) │
│                                                      │
│  theia Process (Port 3000)                          │
│  └─→ Eclipse theia 1.65 with AI extensions         │
│                                                      │
└─────────────────────────────────────────────────────┘

URLs After Deployment​

Prerequisites​

  1. GCP Project: serene-voltage-464305-n2
  2. GKE Cluster: codi-poc-e2-cluster (us-central1-a)
  3. Artifact Registry: coditect repository created
  4. Permissions: Cloud Build, GKE, Artifact Registry APIs enabled

Step 1: Update .gcloudignore​

Ensure .gcloudignore excludes unnecessary files:

# Already exists - verify it includes:
node_modules/
dist/
build/
.git/
*.log

Step 2: Build and Deploy (Cloud Build)​

# From project root: /home/hal/v4/PROJECTS/t2/
gcloud builds submit --config cloudbuild-combined.yaml

# This will:
# 1. Build V5 frontend (Vite)
# 2. Build theia backend (Eclipse theia 1.65)
# 3. Create combined Docker image
# 4. Push to Artifact Registry
# 5. Deploy to GKE cluster
#
# ⏱️ Expected time: 60-80 minutes (theia build is slow)

Option B: Manual Docker Build (Testing)​

# Build locally (faster iteration for testing)
docker build -f dockerfile.combined -t coditect-combined:test .

# Test locally
docker run -p 8080:80 coditect-combined:test

# Access:
# - Frontend: http://localhost:8080/
# - theia: http://localhost:8080/theia

# If works, push to Cloud Build

Step 3: Verify Deployment​

# Check deployment status
kubectl get deployments -n default | grep coditect-combined

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

# Check service
kubectl get svc coditect-combined-service

# View logs
kubectl logs -f deployment/coditect-combined --tail=100

# Check theia specifically
kubectl logs -f deployment/coditect-combined | grep -i theia

Step 4: Update Ingress (Route Traffic)​

Update your existing Ingress to route to the new combined service:

# k8s-ingress.yaml (create or update)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: coditect-ingress
  namespace: default
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.global-static-ip-name: "coditect-static-ip"
    networking.gke.io/managed-certificates: "coditect-ssl-cert"
    kubernetes.io/ingress.allow-http: "true"
spec:
  rules:
    - host: coditect.ai
      http:
        paths:
          # V5 Backend API (existing Rust service)
          - path: /api/v5
            pathType: Prefix
            backend:
              service:
                name: coditect-v5-backend-service
                port:
                  number: 80

          # Combined V5 Frontend + theia (NEW)
          - path: /
            pathType: Prefix
            backend:
              service:
                name: coditect-combined-service
                port:
                  number: 80

Apply:

kubectl apply -f k8s-ingress.yaml

# Wait for Ingress to be ready (can take 5-10 minutes)
kubectl describe ingress coditect-ingress

# Check IP
kubectl get ingress coditect-ingress

Step 5: Test Deployed Application​

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

# Test V5 frontend
curl -I https://coditect.ai/
# Expected: 200 OK, HTML content

# Test theia backend
curl -I https://coditect.ai/theia/
# Expected: 200 OK, theia HTML

# Full test in browser:
# 1. Open https://coditect.ai/ → Should show V5 UI
# 2. Click "workspace" tab → Should load theia IDE iframe
# 3. Verify Monaco editor loads
# 4. Verify terminal works
# 5. Verify file explorer works

Troubleshooting​

Build Fails​

Issue: npm ci times out Solution: Increase Cloud Build timeout in cloudbuild-combined.yaml:

timeout: '7200s'  # 2 hours

Issue: Out of memory during theia build Solution: Increase machine type:

options:
  machineType: 'E2_HIGHCPU_16'  # 16 CPUs
  diskSizeGb: 200

Deployment Fails​

Issue: Pods crash with OOM (Out of Memory) Solution: Increase memory limits in k8s-combined-deployment.yaml:

resources:
  limits:
    memory: "4Gi"  # Increase from 2Gi

Issue: theia doesn't start Solution: Check logs for missing dependencies:

kubectl logs deployment/coditect-combined | grep -i error

# If missing Node modules:
# Rebuild with: docker build --no-cache

WebSocket Issues​

Issue: theia terminal doesn't work (WebSocket fails) Solution: Verify NGINX WebSocket config in nginx-combined.conf:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Issue: theia disconnects after timeout Solution: Increase session affinity timeout in k8s-combined-deployment.yaml:

sessionAffinityConfig:
  clientIP:
    timeoutSeconds: 21600  # 6 hours

Monitoring​

# Watch pods
watch kubectl get pods -n default

# Live logs (combined)
kubectl logs -f deployment/coditect-combined --all-containers

# Live logs (NGINX only)
kubectl logs -f deployment/coditect-combined -c combined | grep nginx

# Live logs (theia only)
kubectl logs -f deployment/coditect-combined -c combined | grep theia

# Resource usage
kubectl top pods -n default | grep coditect-combined

# Autoscaling status
kubectl get hpa coditect-combined-hpa

Scaling​

Manual Scaling​

# Scale up
kubectl scale deployment coditect-combined --replicas=5

# Scale down
kubectl scale deployment coditect-combined --replicas=1

Auto-Scaling (Already Configured)​

The HorizontalPodAutoscaler will automatically scale between 3-10 pods based on:

  • CPU usage > 70%
  • Memory usage > 80%

Rollback​

# View deployment history
kubectl rollout history deployment/coditect-combined

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

# Rollback to specific revision
kubectl rollout undo deployment/coditect-combined --to-revision=2

Cost Optimization​

Current Setup (3 pods × 2GB RAM × 1 CPU):

  • ~$130/month for compute
  • ~$20/month for load balancer
  • ~$10/month for storage
  • Total: ~$160/month

To Reduce Costs:

  1. Reduce replicas (development):
kubectl scale deployment coditect-combined --replicas=1
# Saves ~$85/month
  1. Use smaller machine type:
# In k8s-combined-deployment.yaml
resources:
  limits:
    memory: "1Gi"  # Down from 2Gi
    cpu: "500m"     # Down from 1000m
# Saves ~$40/month
  1. Use Spot VMs (production-safe for stateless apps):
gcloud container node-pools create spot-pool \
  --cluster=codi-poc-e2-cluster \
  --zone=us-central1-a \
  --spot
# Saves ~60% on compute costs

Next Steps​

  1. ✅ Deploy combined service
  2. ✅ Verify both V5 and theia work
  3. ⬜ Set up monitoring (Prometheus + Grafana)
  4. ⬜ Configure backups (FoundationDB snapshots)
  5. ⬜ Set up staging environment
  6. ⬜ Implement blue-green deployment
  7. ⬜ Add rate limiting (API Gateway)
  8. ⬜ Configure CDN (Cloud CDN)

Support​

Deployment Issues:

  • Check logs: kubectl logs -f deployment/coditect-combined
  • Check events: kubectl get events --sort-by='.lastTimestamp'
  • Check resources: kubectl describe pod <pod-name>

Application Issues:

  • Check browser console for JavaScript errors
  • Check Network tab for failed requests
  • Verify API backend is running: curl https://coditect.ai/api/v5/health

Summary​

What You Get:

✅ Single Docker image containing both V5 and theia ✅ NGINX serves V5 frontend at / ✅ NGINX proxies theia backend at /theia ✅ WebSocket support for theia terminal ✅ Auto-scaling (3-10 pods) ✅ Health checks ✅ Session affinity for WebSocket ✅ Production-ready deployment

Deployment Command:

gcloud builds submit --config cloudbuild-combined.yaml

Access URLs: