container-superposition 0.1.1

package/overlays/docker-sock/README.md

@@ -0,0 +1,256 @@
+# Docker (Host Socket) Overlay
+
+Access the host Docker daemon by mounting the Docker socket. This is Docker-outside-of-Docker (DooD).
+
+## Features
+
+- **Docker CLI** - Docker command-line interface
+- **Docker Compose** - Multi-container orchestration
+- **Host Socket Mount** - `/var/run/docker.sock` mounted from host
+- **Fast Performance** - Shares images and cache with host
+
+## How It Works
+
+This overlay mounts the host's Docker socket into the container, allowing the container to control the host's Docker daemon directly. This is also known as "Docker-outside-of-Docker" (DooD).
+
+**Mount configuration:**
+
+```yaml
+volumes:
+    - /var/run/docker.sock:/var/run/docker-host.sock
+```
+
+## Use Cases
+
+- **Building containers** - Build Docker images from within the dev container
+- **docker-compose testing** - Test multi-service applications
+- **CI/CD parity** - Simulate CI build environments locally
+- **Container management** - Start/stop containers from dev environment
+
+## Benefits vs Docker-in-Docker
+
+| Feature         | Docker-outside-of-Docker (This) | Docker-in-Docker       |
+| --------------- | ------------------------------- | ---------------------- |
+| **Performance** | ✅ Fast (shared cache)          | ⚠️ Slower              |
+| **Disk Usage**  | ✅ Efficient (shared images)    | ❌ Duplicates images   |
+| **Networking**  | ✅ Simple                       | ⚠️ Complex             |
+| **Security**    | ⚠️ Host access                  | ✅ Isolated            |
+| **Portability** | ⚠️ Local only                   | ✅ Works in Codespaces |
+
+## Common Commands
+
+### Build Images
+
+```bash
+# Build from Dockerfile
+docker build -t myapp:latest .
+
+# Build with build args
+docker build --build-arg NODE_VERSION=20 -t myapp .
+
+# Multi-stage build
+docker build --target production -t myapp:prod .
+```
+
+### Run Containers
+
+```bash
+# Run container
+docker run -d -p 8080:80 nginx
+
+# Run with volume mount
+docker run -v $(pwd):/app myapp
+
+# Run with environment variables
+docker run -e DATABASE_URL=postgres://... myapp
+```
+
+### Docker Compose
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+### Image Management
+
+```bash
+# List images
+docker images
+
+# Remove image
+docker rmi myapp:latest
+
+# Prune unused images
+docker image prune -a
+
+# Pull image
+docker pull nginx:latest
+```
+
+### Container Management
+
+```bash
+# List running containers
+docker ps
+
+# List all containers
+docker ps -a
+
+# Stop container
+docker stop CONTAINER_ID
+
+# Remove container
+docker rm CONTAINER_ID
+
+# Execute command in container
+docker exec -it CONTAINER_ID bash
+```
+
+## Security Considerations
+
+⚠️ **Important Security Implications**
+
+### Host Docker Access
+
+Mounting `/var/run/docker.sock` grants **full control** over the host Docker daemon:
+
+- ✅ **Can create containers** with host mounts
+- ✅ **Can access host filesystem** via volume mounts
+- ✅ **Can run privileged containers**
+- ⚠️ **Equivalent to root access on host**
+
+### Security Best Practices
+
+1. **Use in trusted environments only** - Development machines, not production
+2. **Don't expose to untrusted users** - Anyone with container access has Docker control
+3. **Audit Docker commands** - Be aware of what containers you create
+4. **Limit volume mounts** - Avoid mounting sensitive host directories
+5. **Consider alternatives** - Use Docker-in-Docker for untrusted environments
+
+### When NOT to Use
+
+- **Multi-tenant environments** - Users should not share Docker access
+- **Production containers** - Use proper orchestration (Kubernetes)
+- **Untrusted code** - Malicious code can escape container
+- **GitHub Codespaces** - Use Docker-in-Docker instead (this requires local Docker)
+
+### When to Use
+
+- ✅ **Local development** - Building/testing on your machine
+- ✅ **CI/CD simulation** - Mimic CI build environment locally
+- ✅ **Container development** - Building containerized apps
+- ✅ **Testing docker-compose** - Multi-service application development
+
+## Troubleshooting
+
+### Permission denied on Docker socket
+
+```bash
+# Check socket permissions
+ls -l /var/run/docker-host.sock
+
+# Verify Docker feature configured correctly
+# The devcontainers feature should handle user permissions automatically
+```
+
+### Docker daemon not accessible
+
+Ensure Docker Desktop (or Docker daemon) is running on your host machine.
+
+### Network conflicts
+
+```bash
+# List Docker networks
+docker network ls
+
+# Remove conflicting network
+docker network rm NETWORK_NAME
+```
+
+### Can't connect to containers
+
+When running containers from within the dev container, they are on the host's Docker network. Access them via:
+
+- **`localhost`** - For published ports (e.g., `-p 8080:80`)
+- **Container name** - If using custom networks
+- **Host IP** - Check with `ip addr show docker0`
+
+## Docker-in-Docker Alternative
+
+If you need isolation or are working in GitHub Codespaces, use the **docker-in-docker** overlay instead:
+
+- ✅ **Isolated** - Separate Docker daemon
+- ✅ **Portable** - Works in Codespaces
+- ❌ **Slower** - Nested virtualization overhead
+- ❌ **Larger** - Duplicates images
+
+**Switch overlays:**
+
+```bash
+# Remove this overlay, add docker-in-docker
+# Conflicts are enforced in index.yml
+```
+
+## Best Practices
+
+1. **Use .dockerignore** - Exclude unnecessary files from build context
+2. **Multi-stage builds** - Reduce final image size
+3. **Layer caching** - Order Dockerfile commands for optimal caching
+4. **Clean up** - Regularly prune unused images/containers
+5. **Named volumes** - Use Docker volumes instead of bind mounts when possible
+6. **Network isolation** - Use custom networks for container communication
+
+## Common Workflows
+
+### Building and Testing
+
+```bash
+# Build application
+docker build -t myapp:dev .
+
+# Run tests
+docker run --rm myapp:dev npm test
+
+# Run application
+docker run -p 3000:3000 myapp:dev
+```
+
+### Docker Compose Development
+
+```bash
+# Start all services
+docker-compose up -d
+
+# Watch logs
+docker-compose logs -f app
+
+# Rebuild specific service
+docker-compose up -d --build app
+
+# Run command in service
+docker-compose exec app bash
+```
+
+## Related Overlays
+
+- **docker-in-docker** - Conflicts with this overlay (use one or the other)
+- **kubectl-helm** - For Kubernetes development
+- **nodejs/python/dotnet** - Build containerized applications
+- **postgres/redis** - Database services (can run via Docker)
+
+## Notes
+
+- This overlay conflicts with **docker-in-docker** - only one can be selected
+- Requires Docker Desktop (or Docker daemon) running on host
+- Does **not** work in GitHub Codespaces (use docker-in-docker instead)
+- Socket mount path: `/var/run/docker-host.sock`

package/overlays/docker-sock/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+            "version": "latest",
+            "moby": false
+        }
+    }
+}

package/overlays/docker-sock/docker-compose.yml

@@ -0,0 +1,8 @@
+version: '3.8'
+
+services:
+    devcontainer:
+        command: sleep infinity
+        volumes:
+            # Mount host Docker socket for docker-outside-of-docker
+            - /var/run/docker.sock:/var/run/docker-host.sock

package/overlays/docker-sock/overlay.yml

@@ -0,0 +1,13 @@
+id: docker-sock
+name: Docker (host socket)
+description: Access host Docker daemon via socket mount (fast, local-only)
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - docker-in-docker
+tags:
+    - dev
+    - docker
+ports: []

package/overlays/dotnet/README.md

@@ -0,0 +1,147 @@
+# .NET Overlay
+
+Adds .NET 10 SDK with C# development tools and common global tools.
+
+## Features
+
+- **.NET 10 SDK** with C# compiler
+- **VS Code Extensions:**
+    - C# Dev Kit (ms-dotnettools.csdevkit)
+    - C# (ms-dotnettools.csharp)
+    - GUID Generator
+    - Nuke Build
+    - REST Client
+- **Global Tools:** Configured via `global-tools.txt`
+- **Automatic restore:** Runs `dotnet restore` on container creation
+
+## Customizing Global Tools
+
+The overlay includes a customizable `global-tools.txt` file in `.devcontainer/`:
+
+**`.devcontainer/global-tools.txt`:**
+
+```
+# .NET Global Tools
+# Format: one tool per line, with optional version
+# Example: dotnet-ef::8.0.0
+
+# Entity Framework Core CLI
+dotnet-ef
+
+# Code formatter
+dotnet-format
+
+# Dependency updater
+dotnet-outdated-tool
+
+# Add your custom tools here
+cake.tool
+dotnet-reportgenerator-globaltool
+```
+
+### Version Pinning
+
+Pin specific versions using `::`:
+
+```
+dotnet-ef::8.0.0
+dotnet-format::5.1.0
+```
+
+**Rebuild container** after editing to install new tools.
+
+## Common Global Tools
+
+### Development
+
+- `dotnet-ef` - Entity Framework Core migrations
+- `dotnet-format` - Code formatter
+- `dotnet-outdated-tool` - Check for outdated packages
+- `dotnet-reportgenerator-globaltool` - Coverage reports
+
+### Build & Deploy
+
+- `cake.tool` - Cake build system
+- `nuke.globaltool` - Nuke build system
+- `dotnet-sonarscanner` - SonarQube scanner
+
+### Testing & Quality
+
+- `dotnet-stryker` - Mutation testing
+- `dotnet-coverage` - Code coverage
+- `dotnet-depends` - Dependency analyzer
+
+## Project Structure
+
+Works with:
+
+- **.NET solutions** (`.sln`)
+- **Projects** (`.csproj`, `.fsproj`, `.vbproj`)
+- **Global.json** for SDK version pinning
+
+## Automatic Setup
+
+On container creation:
+
+1. ✅ Installs global tools from `global-tools.txt`
+2. ✅ Runs `dotnet restore` (if solution/project exists)
+3. ✅ Lists installed global tools for verification
+
+## Common Workflows
+
+### Web API Development
+
+```bash
+dotnet new webapi -n MyApi
+dotnet run
+```
+
+### Adding EF Migrations
+
+```bash
+dotnet ef migrations add InitialCreate
+dotnet ef database update
+```
+
+### Running Tests with Coverage
+
+```bash
+dotnet test /p:CollectCoverage=true
+```
+
+## Best Practices
+
+1. **Use global.json** to pin SDK version
+2. **Version control global-tools.txt** for team consistency
+3. **Pin tool versions** for reproducibility
+4. **Add .gitignore** for bin/, obj/, .vs/
+
+## Troubleshooting
+
+### Tool not found after adding to global-tools.txt
+
+Rebuild the container:
+
+- **VS Code:** `Cmd+Shift+P` → "Dev Containers: Rebuild Container"
+
+### Restore fails
+
+Check .NET SDK version in `global.json` matches container.
+
+### Want to use local tools instead?
+
+Create `.config/dotnet-tools.json`:
+
+```bash
+dotnet new tool-manifest
+dotnet tool install dotnet-ef
+```
+
+Local tools are project-specific and preferred for reproducibility.
+
+## Related Overlays
+
+- **sqlserver** - SQL Server for .NET apps
+- **postgres** - PostgreSQL with EF Core
+- **redis** - Caching layer
+- **otel-collector** - OpenTelemetry for instrumentation

package/overlays/dotnet/devcontainer.patch.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "xdg-utils pass sshpass build-essential netcat-traditional iputils-ping dnsutils git-lfs sqlite3",
+            "apk": "xdg-utils pass sshpass build-base netcat-openbsd iputils bind-tools git-lfs sqlite"
+        },
+        "ghcr.io/devcontainers/features/dotnet:2": {
+            "version": "10.0"
+        },
+        "ghcr.io/eitsupi/devcontainer-features/jq-likes:2": {
+            "jq": "latest",
+            "yq": "latest"
+        },
+        "ghcr.io/devcontainers/features/github-cli:1": {}
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-dotnettools.csdevkit",
+                "heaths.vscode-guid",
+                "nuke.support",
+                "humao.rest-client"
+            ],
+            "settings": {
+                "[csharp]": {
+                    "editor.formatOnSave": true
+                }
+            }
+        }
+    },
+    "forwardPorts": [5000, 5001, 8080],
+    "portsAttributes": {
+        "5000": {
+            "label": "HTTP",
+            "onAutoForward": "notify"
+        },
+        "5001": {
+            "label": "HTTPS",
+            "onAutoForward": "notify"
+        },
+        "8080": {
+            "label": "Web App",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "PATH": "${containerEnv:HOME}/.dotnet/tools:${containerEnv:PATH}",
+        "TESTCONTAINERS_HOST_OVERRIDE": "host.docker.internal"
+    }
+}

package/overlays/dotnet/global-tools.txt

@@ -0,0 +1,24 @@
+# .NET Global Tools
+# Customize this file to add or remove .NET global tools
+# Format: one tool per line, with optional version
+# Example: dotnet-ef::8.0.0
+
+# Entity Framework Core CLI
+dotnet-ef
+
+# Code formatter
+dotnet-format
+
+# Dependency updater
+dotnet-outdated-tool
+
+# Report generator for code coverage
+# dotnet-reportgenerator-globaltool
+
+# Cake build tool
+# cake.tool
+
+# .NET Aspire workload
+# Microsoft.NET.Sdk.Aspire.Manifest-8.0.100
+
+# Add your custom tools here

package/overlays/dotnet/overlay.yml

@@ -0,0 +1,13 @@
+id: dotnet
+name: .NET
+description: .NET 10 SDK with C# DevKit
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - dotnet
+    - csharp
+ports: []

package/overlays/dotnet/setup.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# .NET setup script - Install global tools and configure environment
+
+set -e
+
+# Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
+OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
+
+echo "🔧 Installing .NET global tools..."
+
+# Read tools from configuration file if it exists
+if [ -f ".devcontainer/global-tools-${OVERLAY_NAME}.txt" ]; then
+    echo "📦 Installing tools from global-tools-${OVERLAY_NAME}.txt..."
+    
+    while IFS= read -r line || [ -n "$line" ]; do
+        # Skip comments and empty lines
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+        
+        # Parse tool name and optional version (format: tool::version)
+        if [[ "$line" =~ ^(.+)::(.+)$ ]]; then
+            tool="${BASH_REMATCH[1]}"
+            version="${BASH_REMATCH[2]}"
+            echo "  Installing $tool version $version..."
+            dotnet tool install --global "$tool" --version "$version" || echo "  ⚠️  $tool already installed or failed"
+        else
+            tool="$line"
+            echo "  Installing $tool..."
+            dotnet tool install --global "$tool" || echo "  ⚠️  $tool already installed or failed"
+        fi
+    done < ".devcontainer/global-tools-${OVERLAY_NAME}.txt"
+else
+    # Fallback to hardcoded list
+    echo "📦 Installing default .NET global tools..."
+    dotnet tool install --global dotnet-ef || echo "dotnet-ef already installed"
+    dotnet tool install --global dotnet-format || echo "dotnet-format already installed"
+    dotnet tool install --global dotnet-outdated-tool || echo "dotnet-outdated-tool already installed"
+fi
+
+# Verify installations
+echo "✓ .NET global tools installed:"
+dotnet tool list --global
+
+# Restore project dependencies if solution/project exists
+if [ -f "*.sln" ] || [ -f "*.csproj" ] || [ -f "*.fsproj" ]; then
+    echo "📦 Restoring .NET dependencies..."
+    dotnet restore || true
+    echo "✓ .NET dependencies restored"
+fi
+
+echo "✓ .NET setup complete"

package/overlays/dotnet/verify.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Verification script for .NET overlay
+# Confirms .NET SDK is installed
+
+set -e
+
+echo "🔍 Verifying .NET overlay..."
+echo ""
+
+# Check dotnet is installed
+echo "1️⃣ Checking .NET SDK..."
+if command -v dotnet &> /dev/null; then
+    dotnet --version
+    echo "   ✅ .NET SDK found"
+else
+    echo "   ❌ .NET SDK not found"
+    exit 1
+fi
+
+# List installed SDKs
+echo ""
+echo "2️⃣ Installed .NET SDKs:"
+dotnet --list-sdks
+
+echo ""
+echo "✅ .NET overlay verification complete"