From 065a6534e3300e5099de0553d7fc9d25e94e0721 Mon Sep 17 00:00:00 2001 From: DevContainer User Date: Sun, 22 Feb 2026 13:32:49 +0000 Subject: [PATCH] docs: comprehensive updates for new Helm chart structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major documentation updates to reflect the reorganized Helm chart: - Update README.md and CLAUDE.md to use new mcp.sidecars structure - Reflect removal of Happy daemon automatic startup - Document new logical values organization (Basic → Access → Infrastructure → Integrations → Smart Defaults) - Update all MCP sidecar examples to use mcp.sidecars instead of mcpSidecars - Document new quickstart deployment options and progressive disclosure - Update troubleshooting sections with current configurations - Standardize all secret environment variable references to SCREAMING_SNAKE_CASE This completes the documentation sync following the major Helm chart user experience improvements implemented in previous commits. Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- CLAUDE.md | 29 +++++++++++++++++-------- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 72 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fef6084..f1a14d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Antigravity is a Docker-based cloud development environment that provides: +The Dev Container is a Docker-based cloud development environment that provides: - Web-based GUI IDE (VSCode/Antigravity) via VNC on port 5800 -- Happy Coder AI assistant integration +- Happy Coder AI assistant integration (manual startup) - Automatic GitHub repository cloning on startup - Kubernetes-native deployment with persistent home storage +- MCP (Model Context Protocol) sidecars for AI assistant integrations The stack is primarily **Bash scripts + YAML** — there is no Node.js package, compiled language, or test framework. @@ -87,8 +88,8 @@ MCP (Model Context Protocol) servers run as sidecar containers in the pod, enabl |---------|-------|---------|------|----------|---------| | `kubernetes-mcp` | `quay.io/containers/kubernetes_mcp_server` | v0.0.57 | 8080 | `http://localhost:8080/sse` | Enabled | | `flux-mcp` | `ghcr.io/controlplaneio-fluxcd/flux-operator-mcp` | v0.41.1 | 8081 | `http://localhost:8081/sse` | Enabled | -| `github-mcp` | `ghcr.io/modelcontextprotocol/servers/github` | latest | 8088 | `http://localhost:8088/sse` | Enabled | -| `homeassistant-mcp` | `ghcr.io/homeassistant-ai/ha-mcp` | 6.7.1 | 8087 | `http://localhost:8087/sse` | Disabled | +| `github-mcp` | `ghcr.io/modelcontextprotocol/servers/github` | latest | 8088 | `http://localhost:8088/sse` | Disabled | +| `homeassistant-mcp` | `ghcr.io/homeassistant-ai/ha-mcp` | stable | 8087 | `http://localhost:8087/sse` | Disabled | | `pgtuner-mcp` | `dog830228/pgtuner_mcp` | latest | 8085 | `http://localhost:8085/sse` | Disabled | | `playwright-mcp` | `microsoft/playwright-mcp` | latest | 8086 | `http://localhost:8086/sse` | Enabled | @@ -106,7 +107,8 @@ To control MCP sidecars, set the `enabled` flag in your values override: ```yaml # Disable all MCP sidecars -mcpSidecars: +mcp: + sidecars: kubernetes: enabled: false flux: @@ -121,7 +123,8 @@ mcpSidecars: enabled: false # Or selectively enable/disable -mcpSidecars: +mcp: + sidecars: kubernetes: enabled: true # Keep Kubernetes MCP enabled flux: @@ -138,10 +141,18 @@ mcpSidecars: When deploying via Helm: ```bash -# Using --set flag -helm install my-devcontainer ./chart --set mcpSidecars.kubernetes.enabled=false --set mcpSidecars.flux.enabled=false +# Quick start (recommended) +cp chart/values-quickstart.yaml my-values.yaml +# Edit name and githubRepo in my-values.yaml +helm install my-devcontainer ./chart -f my-values.yaml -# Or with a values file +# Using --set flags +helm install my-devcontainer ./chart \ + --set name=mydev \ + --set githubRepo=https://github.com/user/repo \ + --set mcp.sidecars.kubernetes.enabled=false + +# Full customization helm install my-devcontainer ./chart -f custom-values.yaml ``` diff --git a/README.md b/README.md index 2f30a3d..dbd5dfd 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,32 @@ A containerized cloud development environment with web-based GUI access, featuri ## Quick Start +### Option A: Quickstart (Recommended) + +For 80% of users, use the simplified quickstart values: + +```bash +# Copy and customize the quickstart template +cp chart/values-quickstart.yaml my-values.yaml + +# Edit my-values.yaml to set your name and repository: +# name: mydev +# githubRepo: https://github.com/youruser/yourrepo + +# Deploy with minimal configuration +helm install mydev ./chart -f my-values.yaml +``` + +### Option B: One-Command Deploy + +```bash +helm install mydev ./chart \ + --set name=mydev \ + --set githubRepo=https://github.com/youruser/yourrepo +``` + +### Option C: Full Configuration + ### 1. Create a secret The secret is picked up automatically via `envFrom`. Keys recognised: @@ -75,6 +101,18 @@ A Chrome browser window will open inside VNC for the Claude Max OAuth login. Cre ## Helm Chart Reference +The Helm chart uses a logical organization with these main sections: +- **Basic Configuration**: name, image, githubRepo +- **Access & Interface**: IDE, SSH, display, user settings +- **Infrastructure**: storage, resources, cluster access +- **Integrations**: Happy Coder, MCP sidecars +- **Smart Defaults**: auto-detection and profiles + +📖 **Documentation**: +- [USAGE.md](chart/USAGE.md) - Comprehensive examples and scenarios +- [values-quickstart.yaml](chart/values-quickstart.yaml) - Minimal configuration +- [values.schema.json](chart/values.schema.json) - IDE validation support + ### Core values | Value | Default | Description | @@ -160,12 +198,12 @@ The devcontainer includes MCP (Model Context Protocol) servers as sidecar contai | Sidecar | Default | Purpose | |---------|---------|---------| -| `mcpSidecars.kubernetes.enabled` | `true` | Kubernetes API access via MCP | -| `mcpSidecars.flux.enabled` | `true` | Flux GitOps operations via MCP | -| `mcpSidecars.github.enabled` | `false` | GitHub API access via MCP (DISABLED: archived image) | -| `mcpSidecars.homeassistant.enabled` | `false` | Home Assistant smart home control via MCP | -| `mcpSidecars.pgtuner.enabled` | `false` | PostgreSQL performance tuning and analysis via MCP | -| `mcpSidecars.playwright.enabled` | `true` | Browser automation and web testing via MCP | +| `mcp.sidecars.kubernetes.enabled` | `true` | Kubernetes API access via MCP | +| `mcp.sidecars.flux.enabled` | `true` | Flux GitOps operations via MCP | +| `mcp.sidecars.github.enabled` | `false` | GitHub API access via MCP (DISABLED: archived image) | +| `mcp.sidecars.homeassistant.enabled` | `false` | Home Assistant smart home control via MCP | +| `mcp.sidecars.pgtuner.enabled` | `false` | PostgreSQL performance tuning and analysis via MCP | +| `mcp.sidecars.playwright.enabled` | `true` | Browser automation and web testing via MCP | **Notes:** - Kubernetes and Flux sidecars require `clusterAccess` != `none` to be deployed (automatically disabled when no cluster access) @@ -180,15 +218,15 @@ The devcontainer includes MCP (Model Context Protocol) servers as sidecar contai helm install mydev ./chart \ --set name=mydev \ --set githubRepo=https://github.com/youruser/yourrepo \ - --set mcpSidecars.kubernetes.enabled=false \ - --set mcpSidecars.flux.enabled=false \ - --set mcpSidecars.playwright.enabled=false + --set mcp.sidecars.kubernetes.enabled=false \ + --set mcp.sidecars.flux.enabled=false \ + --set mcp.sidecars.playwright.enabled=false # Or selectively disable helm install mydev ./chart \ --set name=mydev \ --set githubRepo=https://github.com/youruser/yourrepo \ - --set mcpSidecars.flux.enabled=false # Disable only Flux MCP + --set mcp.sidecars.flux.enabled=false # Disable only Flux MCP ``` **Enable Home Assistant MCP:** @@ -203,7 +241,7 @@ kubectl create secret generic devcontainer-mydev-secrets-env \ helm install mydev ./chart \ --set name=mydev \ --set githubRepo=https://github.com/youruser/yourrepo \ - --set mcpSidecars.homeassistant.enabled=true + --set mcp.sidecars.homeassistant.enabled=true ``` **Enable PostgreSQL Tuner MCP:** @@ -217,13 +255,14 @@ kubectl create secret generic devcontainer-mydev-secrets-env \ helm install mydev ./chart \ --set name=mydev \ --set githubRepo=https://github.com/youruser/yourrepo \ - --set mcpSidecars.pgtuner.enabled=true + --set mcp.sidecars.pgtuner.enabled=true ``` **Custom MCP configuration:** ```yaml # values.yaml override -mcpSidecars: +mcp: + sidecars: kubernetes: enabled: true image: