container-superposition 0.1.7 → 0.1.8

package/overlays/k3d/README.md

@@ -0,0 +1,201 @@
+# k3d Overlay
+
+Installs [k3d](https://k3d.io), a lightweight wrapper that runs [k3s](https://k3s.io) (Rancher's minimal Kubernetes distribution) in Docker containers, enabling fast local Kubernetes clusters for development.
+
+> **Note:** This overlay conflicts with `kind` because both tools create local Kubernetes clusters using Docker containers. Choose `k3d` for faster startup and lower resource usage, or `kind` for full Kubernetes conformance.
+
+## Features
+
+- **k3d CLI** — Create, manage, and delete local k3s clusters from the terminal
+- **Fast cluster startup** — Clusters spin up in seconds, compared to heavier alternatives
+- **Low resource usage** — k3s has a smaller memory and CPU footprint than full Kubernetes
+- **Multi-node clusters** — Simulate multi-node topologies with server and agent nodes
+- **Load balancer included** — Built-in k3s service load balancer for `LoadBalancer` services
+- **Port and volume mapping** — Map host ports and directories into the cluster easily
+
+## How It Works
+
+k3d is installed as a static binary in the devcontainer during `setup.sh`. It requires Docker (provided by the `docker-in-docker` dependency) to create k3s nodes as Docker containers.
+
+**Dependencies:**
+
+- `docker-in-docker` (required) — Provides the Docker daemon that k3d uses to launch k3s nodes
+
+**Suggested overlays:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm for interacting with k3d clusters
+
+## Installation
+
+k3d is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads the k3d binary for your architecture (amd64/arm64)
+- Installs to `/usr/local/bin/k3d`
+- Verifies Docker access
+
+## Common Commands
+
+### Cluster Management
+
+```bash
+# Create a single-node cluster (control plane + agent in one node)
+k3d cluster create dev
+
+# Create a cluster with multiple agents
+k3d cluster create dev --agents 2
+
+# Create with a specific k3s version
+k3d cluster create dev --image rancher/k3s:v1.30.0-k3s1
+
+# Create with port mapping (host 8080 → cluster LoadBalancer 80)
+k3d cluster create dev -p "8080:80@loadbalancer"
+
+# List all clusters
+k3d cluster list
+
+# Start/stop a cluster
+k3d cluster start dev
+k3d cluster stop dev
+
+# Delete a cluster
+k3d cluster delete dev
+```
+
+### Working with Clusters
+
+```bash
+# Merge k3d kubeconfig into default kubeconfig
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Get kubeconfig for a specific cluster
+k3d kubeconfig get dev
+
+# Import a Docker image into the cluster (avoids registry push/pull)
+docker build -t myapp:dev .
+k3d image import myapp:dev --cluster dev
+```
+
+### kubectl Integration
+
+```bash
+# Use kubectl with the k3d cluster
+kubectl cluster-info --context k3d-dev
+
+# Deploy a workload
+kubectl create deployment nginx --image=nginx
+kubectl expose deployment nginx --port=80 --type=LoadBalancer
+
+# Port-forward for direct access
+kubectl port-forward service/nginx 8080:80
+```
+
+## Configuration
+
+### Multi-Node Cluster
+
+```bash
+k3d cluster create dev \
+  --servers 1 \
+  --agents 3 \
+  --k3s-arg "--disable=traefik@server:*"
+```
+
+### Volume Mounts
+
+```bash
+# Mount a local directory into all nodes
+k3d cluster create dev \
+  --volume "${PWD}:/app@all"
+```
+
+### Port Mapping
+
+```bash
+# Expose ports 80 and 443 through the cluster load balancer
+k3d cluster create dev \
+  -p "80:80@loadbalancer" \
+  -p "443:443@loadbalancer"
+```
+
+## Benefits vs kind
+
+| Feature               | k3d (this overlay)          | kind                         |
+| --------------------- | --------------------------- | ---------------------------- |
+| **Distribution**      | k3s (lightweight variant)   | ✅ Full Kubernetes           |
+| **Startup speed**     | ✅ Faster (~15–30 s)        | Moderate (~30–60 s)          |
+| **Resource usage**    | ✅ Lower (~256 MB RAM/node) | Higher (~512 MB+ RAM/node)   |
+| **Conformance**       | High (not 100%)             | ✅ 100% CNCF conformant      |
+| **Port mapping**      | ✅ Built-in load balancer   | Manual NodePort/port-forward |
+| **Production parity** | Sufficient for most apps    | ✅ Identical to production   |
+
+**Choose k3d when:**
+
+- Fast iteration cycles are more important than 100% conformance
+- System resources are limited
+- You want built-in load balancer for easy port mapping
+
+**Choose kind when:**
+
+- You need guaranteed Kubernetes API compatibility
+- Developing Kubernetes operators or controllers
+- Testing for production environments
+
+## Use Cases
+
+- **Rapid Kubernetes development** — Fast cluster creation and teardown for iterative development
+- **Helm chart testing** — Deploy and test Helm charts locally before pushing
+- **CI/CD prototyping** — Simulate cluster deployments in low-resource environments
+- **Multi-node testing** — Test workloads across multiple nodes on a single machine
+- **Learning Kubernetes** — Explore Kubernetes concepts with minimal overhead
+
+**Integrates well with:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm package manager
+- `tilt` — Live reload for Kubernetes workloads
+- `skaffold` — Build/deploy automation for Kubernetes
+- `terraform` — IaC for cluster configuration
+
+## Troubleshooting
+
+### Cluster Creation Fails
+
+```bash
+# Ensure Docker daemon is running
+docker info
+
+# Check Docker has sufficient resources
+docker system df
+```
+
+### `kubectl` Cannot Connect
+
+```bash
+# Ensure kubeconfig is merged
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Verify cluster is running
+k3d cluster list
+kubectl cluster-info --context k3d-dev
+```
+
+### Image Not Found in Cluster
+
+```bash
+# Import local images directly (avoids registry round-trip)
+k3d image import myapp:latest --cluster dev
+```
+
+## References
+
+- [k3d Documentation](https://k3d.io)
+- [k3d GitHub](https://github.com/k3d-io/k3d)
+- [k3s Documentation](https://docs.k3s.io)
+- [Kubernetes Documentation](https://kubernetes.io/docs/)
+
+**Related Overlays:**
+
+- `docker-in-docker` — Required: provides the Docker daemon for k3d
+- [`kubectl-helm`](../kubectl-helm/README.md) — Kubernetes CLI and Helm
+- [`kind`](../kind/README.md) — Full-conformance K8s alternative (conflicts)
+- [`tilt`](../tilt/README.md) — Live reload for Kubernetes development
+- [`skaffold`](../skaffold/README.md) — K8s build and deploy automation

package/overlays/k3d/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    }
+}

package/overlays/k3d/overlay.yml

@@ -0,0 +1,19 @@
+id: k3d
+name: k3d
+description: Lightweight local Kubernetes clusters using k3s in Docker
+category: cloud
+supports: []
+requires:
+    - docker-in-docker
+suggests:
+    - kubectl-helm
+conflicts:
+    - kind
+tags:
+    - cloud
+    - kubernetes
+    - k8s
+    - k3d
+    - k3s
+    - testing
+ports: []

package/overlays/k3d/setup.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Setup script for k3d
+
+set -e
+
+echo "🔧 Setting up k3d..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+# Install k3d
+K3D_VERSION="${K3D_VERSION:-v5.7.4}"
+echo "📦 Installing k3d ${K3D_VERSION}..."
+
+install_binary \
+    "https://github.com/k3d-io/k3d/releases/download/${K3D_VERSION}/k3d-linux-${CS_ARCH}" \
+    "k3d"
+
+# Verify installation
+if command -v k3d &>/dev/null; then
+    echo "✅ k3d installed successfully"
+    k3d version
+else
+    echo "❌ k3d installation failed"
+    exit 1
+fi
+
+echo "✅ k3d setup complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/k3d/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for k3d overlay
+# Confirms k3d is installed
+
+set -e
+
+echo "🔍 Verifying k3d overlay..."
+echo ""
+
+# Check k3d is installed
+echo "1️⃣ Checking k3d installation..."
+if command -v k3d &>/dev/null; then
+    k3d version
+    echo "   ✅ k3d is installed"
+else
+    echo "   ❌ k3d is not installed"
+    exit 1
+fi
+
+# Check Docker is available (required for k3d)
+echo ""
+echo "2️⃣ Checking Docker availability..."
+if ! command -v docker &>/dev/null; then
+    echo "   ❌ Docker CLI not found"
+    exit 1
+fi
+if docker version --format '{{.Server.Version}}' &>/dev/null; then
+    echo "   ✅ Docker is available"
+else
+    echo "   ❌ Docker daemon not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ k3d overlay verification complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/ollama/.env.example

@@ -0,0 +1,14 @@
+# Ollama Configuration
+
+# Path to the Ollama data directory on the host machine.
+# Defaults to ~/.ollama — models downloaded there are available without re-pull.
+# Override to use a different directory, e.g. an external drive:
+# OLLAMA_MODELS_PATH=/Volumes/BigDrive/ollama
+# Windows users: set this explicitly, e.g. OLLAMA_MODELS_PATH=C:/Users/you/.ollama
+OLLAMA_MODELS_PATH=~/.ollama
+
+# Ollama image version (defaults to latest)
+OLLAMA_VERSION=latest
+
+# Host port for the Ollama API (defaults to 11434)
+OLLAMA_PORT=11434

package/overlays/ollama/README.md

@@ -0,0 +1,325 @@
+# Ollama Overlay
+
+Runs [Ollama](https://ollama.com) as a Docker Compose service inside the devcontainer, enabling local LLM inference without leaving the dev environment. The Ollama CLI is also installed directly in the devcontainer for ergonomic model management and inference from the terminal.
+
+## Features
+
+- **Ollama inference server** — Run large language models locally with a simple REST API
+- **Ollama CLI in devcontainer** — Manage models and run inference with `ollama pull / run / list / rm` from the terminal without SSH-ing into the sidecar
+- **OpenAI-compatible endpoint** — Drop-in replacement for many OpenAI API integrations
+- **Pre-configured `OLLAMA_HOST`** — Points automatically at the sidecar; no manual setup required
+- **Host model reuse** — Mounts your host's `~/.ollama` directory so models are shared without re-downloading
+- **GPU passthrough** — Both the `ollama` sidecar and the devcontainer itself get access to all NVIDIA GPUs via the `deploy.resources.reservations.devices` block
+- **Port 11434** — Standard Ollama API port, accessible from the devcontainer as `http://ollama:11434`
+
+## How It Works
+
+Ollama runs as a long-lived Docker Compose service (`ollama`) alongside your devcontainer. The devcontainer connects to it using the hostname `ollama` on port `11434`.
+
+**Service configuration:**
+
+- Image: `ollama/ollama:latest`
+- Network: `devnet` (shared with the dev container)
+- Port: `11434` (REST API)
+- Volume: `${OLLAMA_MODELS_PATH:-~/.ollama}:/root/.ollama` — mounts the host Ollama data directory
+
+The `OLLAMA_HOST` environment variable is set to `http://ollama:11434` in the devcontainer, so the Ollama CLI and any tools that respect this variable will connect to the sidecar automatically.
+
+The `setup.sh` script installs the Ollama CLI directly in the devcontainer at container creation time, providing the full `ollama` UX from the terminal. In the normal compose-based case it copies `/usr/bin/ollama` from the already-running `ollama/ollama` sidecar image, avoiding a second multi-gigabyte download. If Docker is unavailable, it falls back to the official Linux release archives (`.tar.zst`, with legacy `.tgz` fallback). The CLI is client-only and does not start a daemon inside the devcontainer.
+
+## Mapping Host Models into the Container
+
+This is the most important feature for day-to-day use. Models downloaded via `ollama pull` on the **host machine** are stored in `~/.ollama/models` (macOS/Linux) or `%USERPROFILE%\.ollama\models` (Windows). Re-downloading multi-gigabyte models inside the container on every rebuild is wasteful.
+
+### Default Behaviour
+
+The compose volume `${OLLAMA_MODELS_PATH:-~/.ollama}:/root/.ollama` automatically mounts the host's default Ollama data directory. Any model already pulled on the host is immediately available inside the container — no re-download required.
+
+### Override Path
+
+Set `OLLAMA_MODELS_PATH` in `.devcontainer/.env` to point at a different directory, for example an external drive with large models:
+
+```bash
+# .devcontainer/.env
+OLLAMA_MODELS_PATH=/Volumes/BigDrive/ollama
+```
+
+### Windows Note
+
+On Windows, `~` expansion may not work as expected. Set `OLLAMA_MODELS_PATH` explicitly:
+
+```bash
+OLLAMA_MODELS_PATH=C:/Users/you/.ollama
+```
+
+### Read-Write Mount
+
+The mount is read-write by default, so `ollama pull` inside the container also saves models to the host directory. This means models downloaded inside the devcontainer are available on the host and in future container rebuilds.
+
+## Using the Ollama CLI
+
+The Ollama CLI is installed directly in the devcontainer by `setup.sh`. The `OLLAMA_HOST` environment variable is pre-configured to `http://ollama:11434`, so all commands automatically target the sidecar — no manual configuration required.
+
+```bash
+# From the main devcontainer terminal — talks to the sidecar
+
+# Pull a model and list available models
+ollama pull llama3.2
+ollama list
+
+# Run a different model for inference
+ollama run mistral "explain this function"
+```
+
+> **Note:** Do **not** run `ollama serve` inside the devcontainer. The sidecar IS the server. Running `ollama serve` would start a second daemon that conflicts with the sidecar.
+
+> **Note:** `ollama pull` inside the devcontainer writes models to the host-mounted `OLLAMA_MODELS_PATH` directory (default `~/.ollama`). Models are persisted across container rebuilds.
+
+### Model Management
+
+```bash
+# Pull a model (saved to the host-mounted ~/.ollama directory)
+ollama pull llama3.2
+
+# List available models
+ollama list
+
+# Show detailed model information
+ollama show llama3.2
+
+# Remove a model
+ollama rm llama3.2
+
+# Copy a model under a new name
+ollama cp llama3.2 my-custom-llama
+```
+
+### Running Models
+
+```bash
+# Interactive chat session
+ollama run llama3.2
+
+# One-shot inference
+ollama run llama3.2 "explain this function"
+
+# Run a coding-focused model
+ollama run qwen2.5-coder "review this code"
+```
+
+## Common Commands
+
+### Pull and Run Models
+
+```bash
+# Pull a model (saved to host's ~/.ollama)
+ollama pull llama3.2
+
+# Run a model interactively
+ollama run llama3.2
+
+# Run a smaller model for faster responses
+ollama pull phi3.5
+ollama run phi3.5
+
+# Run a coding-focused model
+ollama pull qwen2.5-coder
+ollama run qwen2.5-coder
+```
+
+### Model Management
+
+```bash
+# List downloaded models
+ollama list
+
+# Show model information
+ollama show llama3.2
+
+# Remove a model
+ollama rm llama3.2
+
+# Copy a model
+ollama cp llama3.2 my-custom-llama
+```
+
+### REST API
+
+```bash
+# Health check — list available models
+curl http://ollama:11434/api/tags
+
+# Generate a completion
+curl http://ollama:11434/api/generate \
+  -d '{
+    "model": "llama3.2",
+    "prompt": "Why is the sky blue?",
+    "stream": false
+  }'
+
+# OpenAI-compatible chat endpoint
+curl http://ollama:11434/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "llama3.2",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+
+# From the host machine (via forwarded port)
+curl http://localhost:11434/api/tags
+```
+
+## GPU Acceleration
+
+GPU passthrough is enabled out of the box. Both the `ollama` sidecar and the `devcontainer` service receive `gpus: all` via the `deploy.resources.reservations.devices` block in the overlay's `docker-compose.yml`:
+
+```yaml
+deploy:
+    resources:
+        reservations:
+            devices:
+                - driver: nvidia
+                  count: all
+                  capabilities: [gpu]
+```
+
+This means:
+
+- The `ollama` sidecar uses the GPU for fast inference
+- The `devcontainer` has direct GPU access for GPU-accelerated tooling such as `torch`, `tensorflow`, and CUDA CLI tools
+
+### Prerequisites
+
+GPU passthrough requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) installed and configured on the host:
+
+```bash
+# Verify NVIDIA driver is installed on the host
+nvidia-smi
+
+# Verify NVIDIA Container Toolkit
+docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
+```
+
+> **Note:** On machines without an NVIDIA GPU or without the NVIDIA Container Toolkit, Docker Compose may warn about unresolvable device requests. Install the toolkit or remove the `deploy` block via a custom compose override if GPU support is not needed.
+
+### Verify GPU Access
+
+```bash
+# Check NVIDIA GPU is detected inside the devcontainer
+nvidia-smi
+
+# Confirm Ollama is using GPU
+ollama run llama3.2 "hello"
+# GPU usage should appear in nvidia-smi output
+```
+
+**See also:** The [`cuda`](../cuda/README.md) overlay for additional CUDA development tooling (CUDA libraries, `nvcc`, etc.) in the devcontainer.
+
+## Use Cases
+
+- **Offline AI coding** — Use local models with tools like `codex`, `claude-code`, or `amp` as a privacy-preserving backend
+- **Privacy-preserving LLM APIs** — Process sensitive code or documents without sending data to cloud providers
+- **Testing and prototyping** — Experiment with different models without API costs
+- **CI/CD pipelines** — Run LLM-based tests or validations in an isolated environment
+- **Custom fine-tuned models** — Load and serve models you have trained or customized
+
+**Integrates well with:**
+
+- `codex` — Point OpenAI Codex CLI at the local Ollama endpoint
+- `claude-code` — Use with a local proxy that speaks the Anthropic API format
+- `amp` — Configure Amp to use the local OpenAI-compatible endpoint
+
+## Configuration
+
+### Environment Variables
+
+Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+| Variable             | Default     | Description                                            |
+| -------------------- | ----------- | ------------------------------------------------------ |
+| `OLLAMA_MODELS_PATH` | `~/.ollama` | Host path to Ollama data directory (models are shared) |
+| `OLLAMA_VERSION`     | `latest`    | Ollama Docker image version                            |
+| `OLLAMA_PORT`        | `11434`     | Host port for the Ollama API                           |
+
+### Container Env in Devcontainer
+
+The following environment variable is set in the container environment (available to all processes, including setup scripts and terminals):
+
+| Variable      | Value                 | Description                                   |
+| ------------- | --------------------- | --------------------------------------------- |
+| `OLLAMA_HOST` | `http://ollama:11434` | URL for the Ollama API (used by CLI and SDKs) |
+
+## Troubleshooting
+
+### Models Not Found
+
+If `ollama list` shows no models, the host model directory may not be mounted correctly:
+
+```bash
+# Check the mount inside the container
+ls /root/.ollama/models
+
+# Verify OLLAMA_MODELS_PATH points to the right directory
+echo $OLLAMA_MODELS_PATH
+
+# Pull a model manually
+ollama pull llama3.2
+```
+
+### Port Conflicts
+
+If port `11434` is already in use on your host:
+
+```bash
+# .devcontainer/.env
+OLLAMA_PORT=11435
+```
+
+Then update `forwardPorts` in your devcontainer configuration accordingly, or use the `--port-offset` flag when generating.
+
+### GPU Not Detected
+
+```bash
+# Check if NVIDIA driver is installed on host
+nvidia-smi
+
+# Check NVIDIA Container Toolkit
+docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
+
+# If toolkit is missing, install it:
+# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
+```
+
+### Service Not Starting
+
+```bash
+# Check compose service status
+docker compose ps
+
+# View Ollama logs
+docker compose logs ollama
+
+# Restart the service
+docker compose restart ollama
+```
+
+## References
+
+- [Ollama Official Website](https://ollama.com)
+- [Ollama Docker Image](https://hub.docker.com/r/ollama/ollama)
+- [Ollama Model Library](https://ollama.com/library)
+- [Ollama REST API Documentation](https://github.com/ollama/ollama/blob/main/docs/api.md)
+- [OpenAI Compatibility](https://github.com/ollama/ollama/blob/main/docs/openai.md)
+
+**Related Overlays:**
+
+- [`cuda`](../cuda/README.md) — NVIDIA GPU passthrough for faster inference
+- [`rocm`](../rocm/README.md) — AMD GPU passthrough for faster inference
+- [`codex`](../codex/README.md) — OpenAI Codex CLI (can use local endpoint)
+- [`claude-code`](../claude-code/README.md) — Anthropic Claude CLI
+- [`amp`](../amp/README.md) — Sourcegraph Amp CLI

package/overlays/ollama/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["ollama"],
+    "forwardPorts": [11434],
+    "portsAttributes": {
+        "11434": {
+            "label": "Ollama API",
+            "onAutoForward": "ignore"
+        }
+    },
+    "containerEnv": {
+        "OLLAMA_HOST": "http://ollama:11434"
+    }
+}

package/overlays/ollama/docker-compose.yml

@@ -0,0 +1,24 @@
+version: '3.8'
+
+services:
+    ollama:
+        image: ollama/ollama:${OLLAMA_VERSION:-latest}
+        restart: unless-stopped
+        volumes:
+            - ${OLLAMA_MODELS_PATH:-~/.ollama}:/root/.ollama
+        environment:
+            - OLLAMA_HOST=0.0.0.0
+        ports:
+            - '${OLLAMA_PORT:-11434}:11434'
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]
+        networks:
+            - devnet
+
+networks:
+    devnet: