enhancement: Improve user experience with better installation flow and error messages #38

New Issue

Open

opened 2026-02-22 13:14:19 +00:00 by cpfarhood · 0 comments

cpfarhood commented 2026-02-22 13:14:19 +00:00 (Migrated from github.com)

Copy Link

Copy Source

Summary

Enhance the overall user experience with improved installation flows, actionable error messages, and user-friendly interfaces that guide users through common deployment scenarios.

Proposed Improvements

1. Enhanced Installation Flow

Guided Installation Process:

# Three-tier installation approach
# Tier 1: One-command quickstart
helm install mydev oci://ghcr.io/cpfarhood/charts/devcontainer-basic \
  --set name=mydev \
  --set githubRepo=https://github.com/user/repo

# Tier 2: Interactive installer
./scripts/install.sh  # Walks through configuration options

# Tier 3: Full customization  
cp values-quickstart.yaml my-values.yaml
# Edit my-values.yaml
helm install mydev ./chart -f my-values.yaml

Installation Wizard UI (optional web interface):

# Launch web-based configuration wizard
kubectl apply -f https://raw.githubusercontent.com/cpfarhood/devcontainer/main/installer/wizard.yaml
kubectl port-forward svc/devcontainer-wizard 8080:80

# Visit http://localhost:8080 for GUI configuration

2. Actionable Error Messages

Current: Generic Helm/Kubernetes errors
Improved: Context-aware, actionable messages

# Template error improvements
{{- if not .Values.name }}
{{- fail `
❌ MISSING REQUIRED VALUE: 'name'

The 'name' field is required to generate unique resource names.

💡 QUICK FIX:
   helm install mydev ./chart --set name=mydev

📖 DOCUMENTATION:
   See values.yaml line 5 or https://github.com/cpfarhood/devcontainer#name
` }}
{{- end }}

{{- if and .Values.ssh.enabled (not .Values.envSecretName) }}
{{- fail `
⚠️  SSH SECURITY WARNING: SSH enabled without authorized keys

SSH server will start but no authorized keys are configured.

💡 QUICK FIX:
   kubectl create secret generic devcontainer-{{ .Values.name }}-secrets-env \
     --from-literal=SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_rsa.pub)"

🔒 SECURITY:
   Never use password authentication in production
` }}
{{- end }}

Error Classification System:

• 🚨 Critical: Deployment will fail
• ⚠️ Warning: Suboptimal configuration
• 💡 Info: Helpful suggestions
• 📖 Documentation: Links to detailed guides

3. Smart NOTES.txt Output

Context-aware post-installation guidance:

# templates/NOTES.txt
{{- $deploymentName := include "antigravity.fullname" . }}

🎉 {{ .Chart.Name | title }} deployed successfully!

{{- if eq .Values.ide.type "vscode" }}
🎯 NEXT STEPS FOR VSCODE:
   1. Port-forward: kubectl port-forward deployment/{{ $deploymentName }} 5800:5800
   2. Open browser: http://localhost:5800  
   3. Default password: {{ .Values.display.secureConnection | ternary "check your secret" "none" }}
   
🔧 FIRST TIME SETUP:
   • Open terminal in VSCode
   • Run 'claude' to authenticate AI assistant
   • Git is pre-configured with your GitHub token
{{- end }}

{{- if .Values.ssh.enabled }}
🔐 SSH ACCESS:
   kubectl port-forward deployment/{{ $deploymentName }} 2222:22
   ssh -p 2222 user@localhost
{{- end }}

{{- $enabledSidecars := list }}
{{- range $name, $config := .Values.mcp.sidecars }}
{{- if $config.enabled }}{{ $enabledSidecars = append $enabledSidecars $name }}{{ end }}
{{- end }}
{{- if $enabledSidecars }}
🤖 AI FEATURES ENABLED:
{{- range $enabledSidecars }}
   • {{ . | title }} MCP integration
{{- end }}
   
   Try asking Claude:
   • "Show me all pods in this namespace" (kubernetes)
   • "Open a webpage in browser" (playwright)
   • "Analyze database performance" (pgtuner)
{{- end }}

{{- include "antigravity.troubleshootingTips" . }}

📚 DOCUMENTATION: https://github.com/cpfarhood/devcontainer
🐛 ISSUES: https://github.com/cpfarhood/devcontainer/issues

4. Common Pitfall Prevention

Proactive issue detection and guidance:

{{- define "antigravity.troubleshootingTips" -}}

{{- if eq .Values.clusterAccess "none" }}
💡 TIP: Enable Kubernetes access for more AI features:
   helm upgrade {{ .Release.Name }} ./chart --set clusterAccess=readonly
{{- end }}

{{- if not .Values.envSecretName }}
🔑 ENHANCE WITH SECRETS:
   kubectl create secret generic devcontainer-{{ .Values.name }}-secrets-env \
     --from-literal=GITHUB_TOKEN='ghp_...' \
     --from-literal=VNC_PASSWORD='your-password'
   
   Then upgrade: helm upgrade {{ .Release.Name }} ./chart
{{- end }}

{{- $totalSidecars := len .Values.mcp.sidecars }}
{{- $enabledSidecars := 0 }}
{{- range $name, $config := .Values.mcp.sidecars }}
{{- if $config.enabled }}{{ $enabledSidecars = add $enabledSidecars 1 }}{{ end }}
{{- end }}
{{- if lt $enabledSidecars 2 }}
🚀 MORE AI FEATURES AVAILABLE:
   Enable additional MCP sidecars in values.yaml:
   • kubernetes: Cluster management
   • flux: GitOps operations  
   • playwright: Browser automation
   • pgtuner: Database optimization
{{- end }}

{{- end }}

5. Built-in helm test Validation

User-friendly test output:

# templates/tests/user-acceptance-test.yaml
apiVersion: v1
kind: Pod
metadata:
  name: {{ include "antigravity.fullname" . }}-test-ux
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-weight": "10"
spec:
  restartPolicy: Never
  containers:
  - name: user-acceptance-test
    image: curlimages/curl:latest
    command: ['sh', '-c']
    args:
    - |
      set -e
      
      echo "🧪 Running User Acceptance Tests..."
      echo "=================================="
      
      # Test 1: VNC interface loads
      echo "📺 Testing VNC interface..."
      if curl -f -s http://{{ include "antigravity.fullname" . }}:5800/vnc.html >/dev/null; then
          echo "✅ VNC interface accessible"
      else
          echo "❌ VNC interface not accessible"
          exit 1
      fi
      
      # Test 2: Check workspace is mounted
      echo "📁 Testing workspace mount..."
      if curl -f -s http://{{ include "antigravity.fullname" . }}:5800/api/workspace >/dev/null 2>&1; then
          echo "✅ Workspace mounted correctly"
      else
          echo "⚠️  Workspace API not responding (may be normal)"
      fi
      
      # Test 3: MCP sidecars responding
      {{- range $name, $config := .Values.mcp.sidecars }}
      {{- if $config.enabled }}
      echo "🤖 Testing {{ $name }} MCP sidecar..."
      if curl -f -s http://{{ include "antigravity.fullname" . }}:{{ $config.port }}/sse >/dev/null 2>&1; then
          echo "✅ {{ $name | title }} MCP responding"
      else  
          echo "⚠️  {{ $name | title }} MCP not ready (may still be starting)"
      fi
      {{- end }}
      {{- end }}
      
      echo ""
      echo "🎉 User Acceptance Tests Completed!"
      echo "Your dev container is ready to use."
      echo ""
      echo "🔗 Quick Access:"
      echo "   kubectl port-forward deployment/{{ include "antigravity.fullname" . }} 5800:5800"
      echo "   Open: http://localhost:5800"

6. Progressive Disclosure

Layered configuration complexity:

Level 1: Essential (values-quickstart.yaml)

name: ""
githubRepo: ""

Level 2: Common (values-common.yaml)

name: ""
githubRepo: ""
ide:
  type: vscode
ssh:
  enabled: false
resources:
  profile: medium  # small | medium | large

Level 3: Advanced (values.yaml)

# Full configuration with all options

7. Interactive Troubleshooting

Built-in diagnostic commands:

# Add to main container
/usr/local/bin/devcontainer-doctor

#!/bin/bash
# devcontainer-doctor script

echo "🏥 Dev Container Health Check"
echo "============================"

# Network connectivity
echo "🌐 Network Tests:"
curl -f google.com >/dev/null 2>&1 && echo "✅ Internet connectivity" || echo "❌ No internet access"

# Storage checks  
echo "💾 Storage Tests:"
df -h /workspace /config | tail -n +2 | while read line; do
    echo "✅ $line"
done

# MCP sidecar health
echo "🤖 AI Assistant Tests:"
{{- range $name, $config := .Values.mcp.sidecars }}
{{- if $config.enabled }}
curl -f http://localhost:{{ $config.port }}/health >/dev/null 2>&1 && \
    echo "✅ {{ $name | title }} MCP healthy" || \
    echo "⚠️  {{ $name | title }} MCP not responding"
{{- end }}  
{{- end }}

# Git configuration
echo "🔧 Development Environment:"
git config --get user.name >/dev/null && echo "✅ Git user configured" || echo "⚠️  Git user not set"
git config --get credential.helper >/dev/null && echo "✅ Git credentials helper set" || echo "⚠️  Git credentials not configured"

# AI assistant
echo "🎯 AI Assistant:"
which claude >/dev/null && echo "✅ Claude Code available" || echo "❌ Claude Code not found"
which happy >/dev/null && echo "✅ Happy Coder available" || echo "❌ Happy Coder not found"

echo ""
echo "🏁 Health check complete!"

Benefits

• Lower Barrier to Entry: New users can succeed quickly
• Reduced Support Load: Self-service troubleshooting
• Better Adoption: Positive first experience
• Fewer Errors: Proactive guidance prevents issues
• Increased Confidence: Clear feedback and validation

Implementation Plan

• Design three-tier installation flow
• Enhance error messages with actionable guidance
• Create smart NOTES.txt templates
• Add common pitfall detection
• Build comprehensive test suite with UX focus
• Implement progressive disclosure in values files
• Create interactive troubleshooting tools
• Design optional installation wizard UI
• Test UX improvements with new users
• Document improved workflows

## Summary Enhance the overall user experience with improved installation flows, actionable error messages, and user-friendly interfaces that guide users through common deployment scenarios. ## Proposed Improvements ### 1. Enhanced Installation Flow **Guided Installation Process**: ```bash # Three-tier installation approach # Tier 1: One-command quickstart helm install mydev oci://ghcr.io/cpfarhood/charts/devcontainer-basic \ --set name=mydev \ --set githubRepo=https://github.com/user/repo # Tier 2: Interactive installer ./scripts/install.sh # Walks through configuration options # Tier 3: Full customization cp values-quickstart.yaml my-values.yaml # Edit my-values.yaml helm install mydev ./chart -f my-values.yaml ``` **Installation Wizard UI** (optional web interface): ```bash # Launch web-based configuration wizard kubectl apply -f https://raw.githubusercontent.com/cpfarhood/devcontainer/main/installer/wizard.yaml kubectl port-forward svc/devcontainer-wizard 8080:80 # Visit http://localhost:8080 for GUI configuration ``` ### 2. Actionable Error Messages **Current**: Generic Helm/Kubernetes errors **Improved**: Context-aware, actionable messages ```yaml # Template error improvements {{- if not .Values.name }} {{- fail ` ❌ MISSING REQUIRED VALUE: 'name' The 'name' field is required to generate unique resource names. 💡 QUICK FIX: helm install mydev ./chart --set name=mydev 📖 DOCUMENTATION: See values.yaml line 5 or https://github.com/cpfarhood/devcontainer#name ` }} {{- end }} {{- if and .Values.ssh.enabled (not .Values.envSecretName) }} {{- fail ` ⚠️ SSH SECURITY WARNING: SSH enabled without authorized keys SSH server will start but no authorized keys are configured. 💡 QUICK FIX: kubectl create secret generic devcontainer-{{ .Values.name }}-secrets-env \ --from-literal=SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_rsa.pub)" 🔒 SECURITY: Never use password authentication in production ` }} {{- end }} ``` **Error Classification System**: - 🚨 **Critical**: Deployment will fail - ⚠️ **Warning**: Suboptimal configuration - 💡 **Info**: Helpful suggestions - 📖 **Documentation**: Links to detailed guides ### 3. Smart NOTES.txt Output **Context-aware post-installation guidance**: ```yaml # templates/NOTES.txt {{- $deploymentName := include "antigravity.fullname" . }} 🎉 {{ .Chart.Name | title }} deployed successfully! {{- if eq .Values.ide.type "vscode" }} 🎯 NEXT STEPS FOR VSCODE: 1. Port-forward: kubectl port-forward deployment/{{ $deploymentName }} 5800:5800 2. Open browser: http://localhost:5800 3. Default password: {{ .Values.display.secureConnection | ternary "check your secret" "none" }} 🔧 FIRST TIME SETUP: • Open terminal in VSCode • Run 'claude' to authenticate AI assistant • Git is pre-configured with your GitHub token {{- end }} {{- if .Values.ssh.enabled }} 🔐 SSH ACCESS: kubectl port-forward deployment/{{ $deploymentName }} 2222:22 ssh -p 2222 user@localhost {{- end }} {{- $enabledSidecars := list }} {{- range $name, $config := .Values.mcp.sidecars }} {{- if $config.enabled }}{{ $enabledSidecars = append $enabledSidecars $name }}{{ end }} {{- end }} {{- if $enabledSidecars }} 🤖 AI FEATURES ENABLED: {{- range $enabledSidecars }} • {{ . | title }} MCP integration {{- end }} Try asking Claude: • "Show me all pods in this namespace" (kubernetes) • "Open a webpage in browser" (playwright) • "Analyze database performance" (pgtuner) {{- end }} {{- include "antigravity.troubleshootingTips" . }} 📚 DOCUMENTATION: https://github.com/cpfarhood/devcontainer 🐛 ISSUES: https://github.com/cpfarhood/devcontainer/issues ``` ### 4. Common Pitfall Prevention **Proactive issue detection and guidance**: ```yaml {{- define "antigravity.troubleshootingTips" -}} {{- if eq .Values.clusterAccess "none" }} 💡 TIP: Enable Kubernetes access for more AI features: helm upgrade {{ .Release.Name }} ./chart --set clusterAccess=readonly {{- end }} {{- if not .Values.envSecretName }} 🔑 ENHANCE WITH SECRETS: kubectl create secret generic devcontainer-{{ .Values.name }}-secrets-env \ --from-literal=GITHUB_TOKEN='ghp_...' \ --from-literal=VNC_PASSWORD='your-password' Then upgrade: helm upgrade {{ .Release.Name }} ./chart {{- end }} {{- $totalSidecars := len .Values.mcp.sidecars }} {{- $enabledSidecars := 0 }} {{- range $name, $config := .Values.mcp.sidecars }} {{- if $config.enabled }}{{ $enabledSidecars = add $enabledSidecars 1 }}{{ end }} {{- end }} {{- if lt $enabledSidecars 2 }} 🚀 MORE AI FEATURES AVAILABLE: Enable additional MCP sidecars in values.yaml: • kubernetes: Cluster management • flux: GitOps operations • playwright: Browser automation • pgtuner: Database optimization {{- end }} {{- end }} ``` ### 5. Built-in `helm test` Validation **User-friendly test output**: ```yaml # templates/tests/user-acceptance-test.yaml apiVersion: v1 kind: Pod metadata: name: {{ include "antigravity.fullname" . }}-test-ux annotations: "helm.sh/hook": test "helm.sh/hook-weight": "10" spec: restartPolicy: Never containers: - name: user-acceptance-test image: curlimages/curl:latest command: ['sh', '-c'] args: - | set -e echo "🧪 Running User Acceptance Tests..." echo "==================================" # Test 1: VNC interface loads echo "📺 Testing VNC interface..." if curl -f -s http://{{ include "antigravity.fullname" . }}:5800/vnc.html >/dev/null; then echo "✅ VNC interface accessible" else echo "❌ VNC interface not accessible" exit 1 fi # Test 2: Check workspace is mounted echo "📁 Testing workspace mount..." if curl -f -s http://{{ include "antigravity.fullname" . }}:5800/api/workspace >/dev/null 2>&1; then echo "✅ Workspace mounted correctly" else echo "⚠️ Workspace API not responding (may be normal)" fi # Test 3: MCP sidecars responding {{- range $name, $config := .Values.mcp.sidecars }} {{- if $config.enabled }} echo "🤖 Testing {{ $name }} MCP sidecar..." if curl -f -s http://{{ include "antigravity.fullname" . }}:{{ $config.port }}/sse >/dev/null 2>&1; then echo "✅ {{ $name | title }} MCP responding" else echo "⚠️ {{ $name | title }} MCP not ready (may still be starting)" fi {{- end }} {{- end }} echo "" echo "🎉 User Acceptance Tests Completed!" echo "Your dev container is ready to use." echo "" echo "🔗 Quick Access:" echo " kubectl port-forward deployment/{{ include "antigravity.fullname" . }} 5800:5800" echo " Open: http://localhost:5800" ``` ### 6. Progressive Disclosure **Layered configuration complexity**: **Level 1: Essential** (values-quickstart.yaml) ```yaml name: "" githubRepo: "" ``` **Level 2: Common** (values-common.yaml) ```yaml name: "" githubRepo: "" ide: type: vscode ssh: enabled: false resources: profile: medium # small | medium | large ``` **Level 3: Advanced** (values.yaml) ```yaml # Full configuration with all options ``` ### 7. Interactive Troubleshooting **Built-in diagnostic commands**: ```bash # Add to main container /usr/local/bin/devcontainer-doctor ``` ```bash #!/bin/bash # devcontainer-doctor script echo "🏥 Dev Container Health Check" echo "============================" # Network connectivity echo "🌐 Network Tests:" curl -f google.com >/dev/null 2>&1 && echo "✅ Internet connectivity" || echo "❌ No internet access" # Storage checks echo "💾 Storage Tests:" df -h /workspace /config | tail -n +2 | while read line; do echo "✅ $line" done # MCP sidecar health echo "🤖 AI Assistant Tests:" {{- range $name, $config := .Values.mcp.sidecars }} {{- if $config.enabled }} curl -f http://localhost:{{ $config.port }}/health >/dev/null 2>&1 && \ echo "✅ {{ $name | title }} MCP healthy" || \ echo "⚠️ {{ $name | title }} MCP not responding" {{- end }} {{- end }} # Git configuration echo "🔧 Development Environment:" git config --get user.name >/dev/null && echo "✅ Git user configured" || echo "⚠️ Git user not set" git config --get credential.helper >/dev/null && echo "✅ Git credentials helper set" || echo "⚠️ Git credentials not configured" # AI assistant echo "🎯 AI Assistant:" which claude >/dev/null && echo "✅ Claude Code available" || echo "❌ Claude Code not found" which happy >/dev/null && echo "✅ Happy Coder available" || echo "❌ Happy Coder not found" echo "" echo "🏁 Health check complete!" ``` ## Benefits - **Lower Barrier to Entry**: New users can succeed quickly - **Reduced Support Load**: Self-service troubleshooting - **Better Adoption**: Positive first experience - **Fewer Errors**: Proactive guidance prevents issues - **Increased Confidence**: Clear feedback and validation ## Implementation Plan - [ ] Design three-tier installation flow - [ ] Enhance error messages with actionable guidance - [ ] Create smart NOTES.txt templates - [ ] Add common pitfall detection - [ ] Build comprehensive test suite with UX focus - [ ] Implement progressive disclosure in values files - [ ] Create interactive troubleshooting tools - [ ] Design optional installation wizard UI - [ ] Test UX improvements with new users - [ ] Document improved workflows

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

gh-pages

fix/update-cpfarhood-to-farhoodliquor

fix/init-home-before-git-config

feat/helm-github-pages

feature/serverless-2.0.0

fix/schema-new-mcp-sidecars

fix/ci-race-condition

feature/add-fetch-sequential-thinking-mcp

feat/mcp-sidecars

fix/persist-config-to-pvc

docs/final-readme-pass

fix/antigravity-userdata-persistence

fix/antigravity-no-sandbox

feat/ide-choice

fix/happy-home-dir

feat/cluster-access-rbac

fix/happy-daemon-stale-lock

fix/happy-daemon-no-sudo

fix/happy-daemon-user

fix/chrome-in-docker

fix/claude-code-auth

fix/install-claude-code

fix/app-user-shell

fix/happy-daemon-nonblocking

chore/rename-chart-cpfarhood

chore/renovate

feat/helm-oci-publish

fix/happy-daemon-start

v2.6.0

v2.5.0

v2.4.0

v2.3.0

v2.2.5

v2.2.4

v2.2.3

v2.2.2

v2.2.1

v2.2.0

v2.1.1

v2.1.0

v2.0.5

v2.0.4

v2.0.3

v2.0.2

v2.0.1-dev

v2.0.0-dev

v1.0.2

v1.0.1

v0.4.13

v0.4.12

v0.4.11

v0.4.9

v0.4.8

v0.4.7

v0.4.6

v0.4.5

v0.4.4

v0.4.3

v0.4.2

v0.4.1

v0.4.0

v0.3.2

v0.3.0

v0.2.5

v0.2.4

v0.2.3

v0.2.2

v0.2.1

v0.2.0

v0.1.24

v0.1.22

v0.1.21

v1.0.0

Labels

Clear labels

antigravity

architecture

automation

bug

Something isn't working

documentation

Improvements or additions to documentation

duplicate

This issue or pull request already exists

enhancement

New feature or request

examples

good first issue

Good for newcomers

helm

help wanted

Extra attention is needed

invalid

This doesn't seem right

maintainability

monitoring

question

Further information is requested

refactor

tooling

user-experience

validation

wontfix

This will not be worked on

No Label documentation enhancement user-experience

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

fl_blake (Blake MIddleware) cpfarhood (Chris Farhood) ci (Continuous Integration [bot]) flux (Flux CD) admin (Gitea Admin) fl_hugh (Hugh Commit) renovate (Mend Renovate) fl_warren (Warren Bufferpool)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: farhoodlabs/devcontainer#38