container-superposition 0.1.1

package/overlays/go/README.md

@@ -0,0 +1,293 @@
+# Go Overlay
+
+Adds Go latest stable version with tooling for cloud-native development, microservices, and CLI applications.
+
+## Features
+
+- **Go** - Latest stable version from official Go team
+- **gopls** - Official Go language server for IntelliSense
+- **delve** - Powerful Go debugger
+- **golangci-lint** - Fast linters aggregator
+- **VS Code Extension:** Go (golang.go) - Complete Go development experience
+- **Automatic module management** - Runs `go mod download` on container creation
+
+## How It Works
+
+This overlay uses the official devcontainers Go feature to install the latest stable Go version. The setup script installs essential Go development tools including gopls (language server), delve (debugger), and golangci-lint (linter).
+
+**Installation method:**
+
+- Go runtime via official devcontainer feature
+- Development tools via `go install`
+- Tools accessible in $GOPATH/bin
+
+## Common Commands
+
+### Project Initialization
+
+```bash
+# Create new module
+go mod init github.com/username/project
+
+# Add dependency
+go get github.com/gin-gonic/gin@latest
+
+# Update dependencies
+go get -u ./...
+
+# Tidy modules (remove unused)
+go mod tidy
+```
+
+### Building and Running
+
+```bash
+# Run application
+go run main.go
+
+# Build binary
+go build -o myapp
+
+# Build with optimizations
+go build -ldflags="-s -w" -o myapp
+
+# Cross-compile for Linux
+GOOS=linux GOARCH=amd64 go build -o myapp-linux
+
+# Install binary to $GOPATH/bin
+go install
+```
+
+### Testing
+
+```bash
+# Run tests
+go test ./...
+
+# Run with coverage
+go test -cover ./...
+
+# Generate coverage report
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
+
+# Run benchmarks
+go test -bench=. ./...
+
+# Verbose output
+go test -v ./...
+```
+
+### Code Quality
+
+```bash
+# Format code
+go fmt ./...
+# or with gofumpt (stricter)
+gofumpt -l -w .
+
+# Lint with golangci-lint
+golangci-lint run
+
+# Vet (detect suspicious code)
+go vet ./...
+
+# Static analysis with staticcheck
+staticcheck ./...
+```
+
+### Dependency Management
+
+```bash
+# List dependencies
+go list -m all
+
+# View dependency graph
+go mod graph
+
+# Vendor dependencies (optional)
+go mod vendor
+
+# Check for updates
+go list -u -m all
+```
+
+## Use Cases
+
+- **Microservices** - Cloud-native services with gRPC or REST APIs
+- **CLI tools** - Command-line applications (Cobra, urfave/cli)
+- **Cloud infrastructure** - Kubernetes operators, Terraform providers
+- **Web servers** - HTTP APIs (Gin, Echo, Fiber)
+- **Systems programming** - High-performance networked services
+- **DevOps tools** - Build tools, deployment automation
+
+**Integrates well with:**
+
+- `postgres`, `redis`, `mysql` - Database drivers (pq, go-redis, mysql)
+- `docker-sock` - Docker SDK for Go
+- `kubectl-helm` - Kubernetes client libraries
+- `otel-collector`, `jaeger` - OpenTelemetry Go SDK
+- `prometheus` - Prometheus Go client
+
+## Configuration
+
+### Go Version
+
+The overlay installs the **latest stable** Go version. To use a specific version, modify `devcontainer.patch.json`:
+
+```json
+{
+    "features": {
+        "ghcr.io/devcontainers/features/go:1": {
+            "version": "1.21" // Specify exact version
+        }
+    }
+}
+```
+
+### golangci-lint Configuration
+
+Create `.golangci.yml` in project root:
+
+```yaml
+linters:
+    enable:
+        - gofmt
+        - gofumpt
+        - govet
+        - staticcheck
+        - errcheck
+        - gosimple
+        - unused
+
+linters-settings:
+    gofumpt:
+        extra-rules: true
+```
+
+## Application Integration
+
+### HTTP Server with Gin
+
+```go
+package main
+
+import (
+    "github.com/gin-gonic/gin"
+    "net/http"
+)
+
+func main() {
+    r := gin.Default()
+
+    r.GET("/", func(c *gin.Context) {
+        c.JSON(http.StatusOK, gin.H{
+            "message": "Hello from Go!",
+        })
+    })
+
+    r.Run(":8080") // Listen on port 8080
+}
+```
+
+**Run:**
+
+```bash
+go mod init myapp
+go get github.com/gin-gonic/gin
+go run main.go
+# Access at http://localhost:8080
+```
+
+### PostgreSQL Integration
+
+```go
+package main
+
+import (
+    "database/sql"
+    _ "github.com/lib/pq"
+)
+
+func main() {
+    connStr := "host=postgres port=5432 user=postgres password=postgres dbname=mydb sslmode=disable"
+    db, err := sql.Open("postgres", connStr)
+    if err != nil {
+        panic(err)
+    }
+    defer db.Close()
+
+    // Use database
+    rows, err := db.Query("SELECT * FROM users")
+    // ...
+}
+```
+
+## Troubleshooting
+
+### Issue: gopls not found
+
+**Symptoms:**
+
+- IntelliSense not working
+- "gopls not found" error
+
+**Solution:**
+
+```bash
+# Install gopls manually
+go install golang.org/x/tools/gopls@latest
+
+# Verify installation
+gopls version
+```
+
+### Issue: Module not found
+
+**Symptoms:**
+
+- `cannot find module` errors
+- Import errors
+
+**Solution:**
+
+```bash
+# Initialize module if not done
+go mod init github.com/yourname/project
+
+# Download dependencies
+go mod download
+
+# Tidy dependencies
+go mod tidy
+```
+
+### Issue: GOPATH/GOROOT issues
+
+**Solution:**
+
+```bash
+# Check environment
+go env GOPATH
+go env GOROOT
+
+# Should output:
+# GOPATH=/go
+# GOROOT=/usr/local/go
+```
+
+## References
+
+- [Official Go Documentation](https://go.dev/doc/) - Complete Go documentation
+- [Go by Example](https://gobyexample.com/) - Hands-on introduction
+- [Effective Go](https://go.dev/doc/effective_go) - Best practices
+- [Go Extension for VS Code](https://marketplace.visualstudio.com/items?itemName=golang.Go)
+- [golangci-lint](https://golangci-lint.run/) - Linters aggregator
+
+**Related Overlays:**
+
+- `postgres` - PostgreSQL database (lib/pq driver)
+- `redis` - Redis cache (go-redis library)
+- `docker-sock` - Docker SDK for Go
+- `kubectl-helm` - Kubernetes client-go
+- `prometheus` - Prometheus Go client

package/overlays/go/devcontainer.patch.json

@@ -0,0 +1,43 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential",
+            "apk": "build-base"
+        },
+        "ghcr.io/devcontainers/features/go:1": {
+            "version": "latest"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["golang.go"],
+            "settings": {
+                "go.toolsManagement.autoUpdate": true,
+                "[go]": {
+                    "editor.formatOnSave": true,
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": "explicit"
+                    }
+                },
+                "go.lintTool": "golangci-lint",
+                "go.lintOnSave": "package"
+            }
+        }
+    },
+    "remoteEnv": {
+        "PATH": "/go/bin:/usr/local/go/bin:${containerEnv:PATH}",
+        "GOPATH": "/go"
+    },
+    "forwardPorts": [8080, 8081],
+    "portsAttributes": {
+        "8080": {
+            "label": "Web Server",
+            "onAutoForward": "openBrowser"
+        },
+        "8081": {
+            "label": "gRPC/API",
+            "onAutoForward": "notify"
+        }
+    }
+}

package/overlays/go/overlay.yml

@@ -0,0 +1,15 @@
+id: go
+name: Go
+description: Go latest stable with gopls and delve debugger
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - go
+    - golang
+ports:
+    - 8080
+    - 8081

package/overlays/go/setup.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Go setup script - Install Go tools and verify installation
+
+set -e
+
+echo "🔧 Setting up Go development environment..."
+
+# Install common Go tools
+echo "📦 Installing Go development tools..."
+
+# gopls (Language Server)
+go install golang.org/x/tools/gopls@latest || echo "⚠️ gopls installation failed"
+
+# delve (Debugger)
+go install github.com/go-delve/delve/cmd/dlv@latest || echo "⚠️ delve installation failed"
+
+# golangci-lint (Linter) - install via go install for security
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest || echo "⚠️ golangci-lint installation failed"
+
+# gofumpt (Formatter)
+go install mvdan.cc/gofumpt@latest || echo "⚠️ gofumpt installation failed"
+
+# staticcheck (Static analyzer)
+go install honnef.co/go/tools/cmd/staticcheck@latest || echo "⚠️ staticcheck installation failed"
+
+# Install project dependencies if go.mod exists
+if [ -f "go.mod" ]; then
+    echo "📦 Go module detected, downloading dependencies..."
+    go mod download || echo "⚠️ go mod download failed"
+    go mod tidy || echo "⚠️ go mod tidy failed"
+fi
+
+echo "✓ Go setup complete"

package/overlays/go/verify.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Verification script for Go overlay
+
+set -e
+
+echo "🔍 Verifying Go overlay..."
+echo ""
+
+# Check Go is installed
+echo "1️⃣ Checking Go..."
+if command -v go &> /dev/null; then
+    go version
+    echo "   ✅ Go found"
+else
+    echo "   ❌ Go not found"
+    exit 1
+fi
+
+# Check gopls (Language Server)
+echo ""
+echo "2️⃣ Checking gopls..."
+if command -v gopls &> /dev/null; then
+    gopls version
+    echo "   ✅ gopls found"
+else
+    echo "   ⚠️ gopls not found (will be installed on first use)"
+fi
+
+# Check delve (Debugger)
+echo ""
+echo "3️⃣ Checking delve..."
+if command -v dlv &> /dev/null; then
+    dlv version
+    echo "   ✅ delve found"
+else
+    echo "   ⚠️ delve not found (will be installed on first use)"
+fi
+
+echo ""
+echo "✅ Go overlay verification complete"

package/overlays/grafana/.env.example

@@ -0,0 +1,9 @@
+# Grafana version
+GRAFANA_VERSION=latest
+
+# Grafana admin credentials
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+
+# Grafana port
+GRAFANA_PORT=3000