Skip to main content

theia AI Configuration Persistence for GCP Deployment

Overview​

This document outlines the strategy for persisting theia AI configuration (custom agents, prompts, settings) when deploying to Google Cloud Platform (GCP).

Configuration Files to Persist​

.theia/ Directory Structure​

.theia/
├── agents.yaml              # Custom AI agents (V5 code generator, UI designer, reviewer)
├── mcp-servers.json         # MCP server configurations (LM Studio, filesystem, git)
├── settings.json            # theia IDE settings (AI models, providers, preferences)
└── prompts/                 # Custom prompt templates
    ├── code-review.prompttemplate
    ├── generate-component.prompttemplate
    └── ui-design.prompttemplate

GCP Deployment Strategy​

Advantages:

  • Simple to manage
  • Version controlled
  • Easy rollback
  • No additional storage costs

Implementation:

# Create ConfigMap from .theia directory
kubectl create configmap theia-ai-config \
  --from-file=.theia/agents.yaml \
  --from-file=.theia/mcp-servers.json \
  --from-file=.theia/settings.json \
  --from-file=.theia/prompts/ \
  -n default

# Or use kustomization.yaml

Kubernetes Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: theia-ide
spec:
  template:
    spec:
      containers:
      - name: theia
        image: gcr.io/serene-voltage-464305-n2/theia-v5:latest
        volumeMounts:
        - name: theia-config
          mountPath: /home/theia/.theia
          readOnly: true
      volumes:
      - name: theia-config
        configMap:
          name: theia-ai-config

Option 2: Persistent Volume (for User-Modifiable Config)​

Advantages:

  • Users can modify agents/prompts at runtime
  • Supports per-user customization
  • Changes persist across pod restarts

Implementation:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: theia-config-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: standard-rwo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: theia-ide
spec:
  template:
    spec:
      containers:
      - name: theia
        image: gcr.io/serene-voltage-464305-n2/theia-v5:latest
        volumeMounts:
        - name: theia-config
          mountPath: /home/theia/.theia
      volumes:
      - name: theia-config
        persistentVolumeClaim:
          claimName: theia-config-pvc

Option 3: Hybrid (ConfigMap + User Overrides)​

Best of Both Worlds:

  • Base configuration in ConfigMap
  • User customizations in PVC
  • Merge at runtime

Implementation:

volumes:
- name: theia-base-config
  configMap:
    name: theia-ai-config
- name: theia-user-config
  persistentVolumeClaim:
    claimName: theia-user-config-pvc

# Mount both and use overlay filesystem or custom init script

Dockerfile Configuration​

Ensure .theia/ is included in the Docker image:

# Dockerfile
FROM node:20-bullseye

WORKDIR /app

# Copy application code
COPY . .

# Copy theia configuration (base defaults)
COPY .theia /app/.theia

# Install dependencies
RUN npm install && npm run theia:build:prod

# Create non-root user
RUN useradd -m -s /bin/bash theia && \
    chown -R theia:theia /app

USER theia

# Expose port
EXPOSE 3000

CMD ["npm", "run", "theia:start"]

Cloud Build Configuration​

cloudbuild.yaml:

steps:
  # Build Docker image
  - name: 'gcr.io/cloud-builders/docker'
    args:
      - 'build'
      - '-t'
      - 'gcr.io/$PROJECT_ID/theia-v5:$COMMIT_SHA'
      - '-t'
      - 'gcr.io/$PROJECT_ID/theia-v5:latest'
      - '--build-arg'
      - 'THEIA_version=1.65.0'
      - '.'

  # Push to Container Registry
  - name: 'gcr.io/cloud-builders/docker'
    args:
      - 'push'
      - 'gcr.io/$PROJECT_ID/theia-v5:$COMMIT_SHA'

  # Create ConfigMap from .theia directory
  - name: 'gcr.io/cloud-builders/kubectl'
    args:
      - 'create'
      - 'configmap'
      - 'theia-ai-config'
      - '--from-file=.theia/'
      - '--dry-run=client'
      - '-o'
      - 'yaml'
      - '|'
      - 'kubectl'
      - 'apply'
      - '-f'
      - '-'
    env:
      - 'CLOUDSDK_COMPUTE_REGION=us-central1'
      - 'CLOUDSDK_CONTAINER_CLUSTER=codi-poc-e2-cluster'

  # Deploy to GKE
  - name: 'gcr.io/cloud-builders/kubectl'
    args:
      - 'set'
      - 'image'
      - 'deployment/theia-ide'
      - 'theia=gcr.io/$PROJECT_ID/theia-v5:$COMMIT_SHA'
    env:
      - 'CLOUDSDK_COMPUTE_REGION=us-central1'
      - 'CLOUDSDK_CONTAINER_CLUSTER=codi-poc-e2-cluster'

images:
  - 'gcr.io/$PROJECT_ID/theia-v5:$COMMIT_SHA'
  - 'gcr.io/$PROJECT_ID/theia-v5:latest'

Environment Variables for LM Studio​

Important: LM Studio will be running on a separate service in GCP.

settings.json adjustment for GCP:

{
  "ai-features.openAiCustom.apiEndpoint": "${LM_STUDIO_ENDPOINT}",
  "ai-features.openAiCustom.enableAuthentication": false
}

Kubernetes Deployment with LM Studio endpoint:

env:
- name: LM_STUDIO_ENDPOINT
  value: "http://lm-studio-service:1234/v1"

Verification Steps​

1. Build and Test Locally​

cd /workspace/PROJECTS/t2/theia-app
npm run theia:build:prod
npm start

# Access http://localhost:3000
# Verify AI chat is available
# Check custom agents appear in agent selector

2. Test ConfigMap Creation​

kubectl create configmap theia-ai-config \
  --from-file=.theia/ \
  --dry-run=client \
  -o yaml > k8s/theia-configmap.yaml

cat k8s/theia-configmap.yaml

3. Deploy to GKE​

# Apply ConfigMap
kubectl apply -f k8s/theia-configmap.yaml

# Deploy theia
kubectl apply -f k8s/theia-deployment.yaml

# Check logs
kubectl logs -f deployment/theia-ide

# Port forward to test
kubectl port-forward deployment/theia-ide 3000:3000

4. Verify AI Features​

  1. Open http://localhost:3000 (or GCP external IP)
  2. Open AI Chat panel (View → AI Chat)
  3. Check agent selector shows:
    • V5 Code Generator
    • V5 UI Designer
    • V5 Code Reviewer
  4. Select a model from LM Studio models dropdown
  5. Test a chat message

Use ConfigMap for base configuration:

  • .theia/agents.yaml - Custom agents
  • .theia/mcp-servers.json - MCP servers
  • .theia/settings.json - Base settings
  • .theia/prompts/ - Prompt templates

Version control these files:

git add .theia/
git commit -m "feat: Add theia AI configuration with V5 custom agents"
git push

Update via CI/CD:

  • On merge to main → Cloud Build triggers
  • Rebuild Docker image with latest .theia/ files
  • Update ConfigMap in GKE
  • Rolling update deployment

Multi-Tenant Considerations​

For multi-tenant deployments where each user needs custom agents:

Strategy:

  1. Base agents in ConfigMap (read-only)
  2. User-specific agents in Cloud Firestore or FoundationDB
  3. Merge at runtime via custom theia extension
  4. Cache in pod-local storage (ephemeral)

Implementation:

// Custom theia extension
export class CustomAgentProvider {
  async getAgents(userId: string): Promise<Agent[]> {
    // Load base agents from /home/theia/.theia/agents.yaml
    const baseAgents = await loadYaml('.theia/agents.yaml');

    // Load user-specific agents from FDB
    const userAgents = await fdb.get(`/users/${userId}/agents`);

    // Merge and return
    return [...baseAgents, ...userAgents];
  }
}

Troubleshooting​

Agents Not Showing Up​

Check:

  1. ConfigMap mounted correctly: kubectl describe pod <pod-name>
  2. File permissions: kubectl exec <pod-name> -- ls -la /home/theia/.theia/
  3. YAML syntax: kubectl exec <pod-name> -- cat /home/theia/.theia/agents.yaml
  4. theia logs: kubectl logs <pod-name> | grep -i agent

LM Studio Connection Failed​

Check:

  1. LM Studio service is running: kubectl get svc lm-studio-service
  2. Endpoint is correct in settings.json
  3. Network policy allows connection
  4. Test connection: kubectl exec <pod-name> -- curl http://lm-studio-service:1234/v1/models

MCP Servers Not Loading​

Check:

  1. MCP configuration: cat .theia/mcp-servers.json
  2. MCP server executables exist (npx commands work)
  3. Logs: kubectl logs <pod-name> | grep -i mcp
  4. MCP logging enabled in settings.json

Next Steps​

  1. Create Kubernetes manifests in k8s/ directory
  2. Test local deployment with Docker Compose
  3. Deploy to GKE staging environment
  4. Verify all AI features work
  5. Document user guide for using custom agents
  6. Set up monitoring/alerting for AI service health

Related Documentation:

  • docs/06-backend/gcp-cloud-build-guide.md - Complete GCP deployment guide
  • docs/03-infrastructure/infrastructure-map.md - Infrastructure overview
  • docs/theia-ai-research-findings.md - theia AI capabilities
  • .theia/agents.yaml - Custom agent definitions
  • .theia/settings.json - theia IDE settings