container-superposition 0.1.1 → 0.1.3

package/overlays/jupyter/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["jupyter"],
+    "forwardPorts": [8888],
+    "portsAttributes": {
+        "8888": {
+            "label": "Jupyter Notebook",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "JUPYTER_URL": "http://jupyter:8888"
+    }
+}

package/overlays/jupyter/docker-compose.yml

@@ -0,0 +1,23 @@
+version: '3.8'
+
+services:
+    jupyter:
+        image: jupyter/minimal-notebook:${JUPYTER_VERSION:-latest}
+        restart: unless-stopped
+        volumes:
+            - jupyter-data:/home/jovyan/work
+            - ${JUPYTER_NOTEBOOKS_PATH:-./notebooks}:/home/jovyan/notebooks
+        environment:
+            JUPYTER_ENABLE_LAB: ${JUPYTER_ENABLE_LAB:-yes}
+            JUPYTER_TOKEN: ${JUPYTER_TOKEN:-}
+        ports:
+            - '${JUPYTER_PORT:-8888}:8888'
+        networks:
+            - devnet
+        command: start-notebook.sh --NotebookApp.token='' --NotebookApp.password=''
+
+volumes:
+    jupyter-data:
+
+networks:
+    devnet:

package/overlays/jupyter/overlay.yml

@@ -0,0 +1,18 @@
+id: jupyter
+name: Jupyter
+description: Jupyter notebook server for interactive computing and data science
+category: language
+supports:
+    - compose
+requires:
+    - python
+suggests: []
+conflicts: []
+tags:
+    - language
+    - jupyter
+    - python
+    - notebook
+    - data-science
+ports:
+    - 8888

package/overlays/jupyter/verify.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Verification script for Jupyter overlay
+# Confirms Jupyter is running
+
+set -e
+
+echo "🔍 Verifying Jupyter overlay..."
+echo ""
+
+# Check if Jupyter service is running
+echo "1️⃣ Checking Jupyter service..."
+if command -v curl &> /dev/null; then
+    # Wait up to 30 seconds for Jupyter to be ready
+    JUPYTER_READY=false
+    for i in {1..30}; do
+        if curl -s http://jupyter:8888 &> /dev/null; then
+            echo "   ✅ Jupyter service is ready"
+            JUPYTER_READY=true
+            break
+        fi
+        sleep 1
+    done
+
+    if [ "$JUPYTER_READY" = false ]; then
+        echo "   ❌ Jupyter service not ready after 30 seconds"
+        exit 1
+    fi
+else
+    echo "   ⚠️  curl not found, skipping service check"
+fi
+
+echo ""
+echo "✅ Jupyter overlay verification complete"
+echo ""
+echo "ℹ️  Access Jupyter at http://localhost:8888"

package/overlays/kind/README.md

@@ -0,0 +1,221 @@
+# kind (Kubernetes in Docker) Overlay
+
+Local Kubernetes cluster for development and testing using kind.
+
+## Features
+
+- **kind** - Kubernetes in Docker for local cluster creation
+- **Multi-node support** - Create single or multi-node clusters
+- **Fast startup** - Lightweight compared to traditional VMs
+- **Docker-based** - Uses Docker containers as Kubernetes nodes
+- **Production-like** - Runs actual Kubernetes, not a simulator
+
+## How It Works
+
+This overlay installs kind (Kubernetes in Docker), a tool for running local Kubernetes clusters using Docker containers as nodes. It requires Docker-in-Docker to function.
+
+**Dependencies:**
+
+- `docker-in-docker` (required) - Provides Docker daemon for kind clusters
+
+**Suggested overlays:**
+
+- `kubectl-helm` - Kubernetes CLI and Helm package manager
+
+## Installation
+
+kind is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads kind binary for your architecture (amd64/arm64)
+- Installs to `/usr/local/bin/kind`
+- Verifies Docker access
+
+## Common Commands
+
+### Cluster Management
+
+```bash
+# Create a cluster
+kind create cluster --name dev
+
+# Create cluster with custom config
+cat <<EOF | kind create cluster --config=-
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+- role: worker
+- role: worker
+EOF
+
+# List clusters
+kind get clusters
+
+# Delete a cluster
+kind delete cluster --name dev
+```
+
+### Working with Clusters
+
+```bash
+# Get kubeconfig
+kind get kubeconfig --name dev
+
+# Load Docker image into cluster
+docker pull nginx:latest
+kind load docker-image nginx:latest --name dev
+
+# Export logs
+kind export logs /tmp/kind-logs --name dev
+```
+
+### kubectl Integration
+
+```bash
+# kind automatically updates kubeconfig
+kubectl cluster-info --context kind-dev
+
+# Deploy workload
+kubectl create deployment nginx --image=nginx
+kubectl expose deployment nginx --port=80 --type=NodePort
+
+# Access service
+kubectl port-forward service/nginx 8080:80
+```
+
+## Configuration
+
+### Custom Cluster Configuration
+
+Create a `kind-config.yaml`:
+
+```yaml
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+    - role: control-plane
+      kubeadmConfigPatches:
+          - |
+              kind: InitConfiguration
+              nodeRegistration:
+                kubeletExtraArgs:
+                  node-labels: "ingress-ready=true"
+      extraPortMappings:
+          - containerPort: 80
+            hostPort: 80
+            protocol: TCP
+          - containerPort: 443
+            hostPort: 443
+            protocol: TCP
+    - role: worker
+    - role: worker
+```
+
+Use it:
+
+```bash
+kind create cluster --name dev --config kind-config.yaml
+```
+
+### Version Control
+
+Specify kind version in setup.sh via environment variable:
+
+```bash
+KIND_VERSION=v0.22.0
+```
+
+## Use Cases
+
+- **Kubernetes development** - Develop and test K8s applications locally
+- **Operator development** - Build and test Kubernetes operators
+- **CI/CD testing** - Run K8s tests in CI pipelines
+- **Learning Kubernetes** - Experiment with K8s without cloud costs
+- **Multi-cluster scenarios** - Test federation, service mesh across clusters
+
+**Integrates well with:**
+
+- `kubectl-helm` - Kubernetes CLI and Helm
+- `tilt` - Live reload for Kubernetes development
+- `skaffold` - Build/deploy automation for K8s
+- `terraform` - Infrastructure as Code
+- `nodejs`, `python`, `dotnet` - Application development
+
+## Benefits vs k3d
+
+| Feature               | kind                       | k3d                          |
+| --------------------- | -------------------------- | ---------------------------- |
+| **Distribution**      | ✅ Full Kubernetes         | ⚠️ k3s (lightweight variant) |
+| **Conformance**       | ✅ 100% conformant         | ✅ High conformance          |
+| **Speed**             | ⚠️ Moderate startup        | ✅ Faster startup            |
+| **Resource Usage**    | ⚠️ Higher                  | ✅ Lower                     |
+| **Production Parity** | ✅ Identical to production | ⚠️ Some differences          |
+| **Maturity**          | ✅ CNCF project            | ✅ CNCF sandbox              |
+
+**When to use kind:**
+
+- Need 100% Kubernetes compatibility
+- Testing for production environments
+- Developing Kubernetes itself or operators
+- Don't mind slightly higher resource usage
+
+**When to use k3d:**
+
+- Need faster iteration cycles
+- Limited system resources
+- Don't need full Kubernetes features
+
+## Troubleshooting
+
+### Cluster Creation Fails
+
+Check Docker is running:
+
+```bash
+docker ps
+```
+
+Check Docker has sufficient resources (4GB+ RAM recommended).
+
+### Network Issues
+
+kind uses Docker networks. If having network issues:
+
+```bash
+# Delete and recreate cluster
+kind delete cluster --name dev
+kind create cluster --name dev
+```
+
+### Image Pull Failures
+
+Load images manually:
+
+```bash
+docker pull myimage:tag
+kind load docker-image myimage:tag --name dev
+```
+
+### Persistent Volumes
+
+kind uses local path provisioner. PVs are stored in Docker containers:
+
+```bash
+# Inspect node container
+docker exec -it dev-control-plane ls /var/local-path-provisioner
+```
+
+## References
+
+- [kind Documentation](https://kind.sigs.k8s.io/)
+- [kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/)
+- [kind Configuration](https://kind.sigs.k8s.io/docs/user/configuration/)
+- [Kubernetes Documentation](https://kubernetes.io/docs/)
+
+**Related Overlays:**
+
+- `docker-in-docker` - Required for kind to function
+- `kubectl-helm` - Kubernetes CLI and Helm
+- `tilt` - Live reload for Kubernetes
+- `skaffold` - K8s build orchestration
+- `k3d` - Alternative lightweight K8s (conflicts)

package/overlays/kind/devcontainer.patch.json

@@ -0,0 +1,10 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    },
+    "postCreateCommand": "bash .devcontainer/scripts/setup-kind.sh"
+}

package/overlays/kind/overlay.yml

@@ -0,0 +1,18 @@
+id: kind
+name: kind (Kubernetes in Docker)
+description: Local Kubernetes cluster for development and testing
+category: cloud
+supports: []
+requires:
+    - docker-in-docker
+suggests:
+    - kubectl-helm
+conflicts:
+    - k3d
+tags:
+    - cloud
+    - kubernetes
+    - k8s
+    - kind
+    - testing
+ports: []

package/overlays/kind/setup.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Setup script for kind (Kubernetes in Docker)
+
+set -e
+
+echo "🔧 Setting up kind (Kubernetes in Docker)..."
+
+# Detect architecture
+ARCH=$(uname -m)
+case $ARCH in
+    x86_64)
+        KIND_ARCH="amd64"
+        ;;
+    aarch64|arm64)
+        KIND_ARCH="arm64"
+        ;;
+    *)
+        echo "❌ Unsupported architecture: $ARCH"
+        exit 1
+        ;;
+esac
+
+# Install kind
+KIND_VERSION="${KIND_VERSION:-v0.22.0}"
+echo "📦 Installing kind ${KIND_VERSION}..."
+
+curl -Lo /tmp/kind "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-${KIND_ARCH}"
+chmod +x /tmp/kind
+sudo mv /tmp/kind /usr/local/bin/kind
+
+# Verify installation
+if command -v kind &> /dev/null; then
+    echo "✅ kind installed successfully"
+    kind version
+else
+    echo "❌ kind installation failed"
+    exit 1
+fi
+
+echo "✅ kind setup complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   kind create cluster --name dev"

package/overlays/kind/verify.sh

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

package/overlays/localstack/.env.example

@@ -0,0 +1,6 @@
+# LocalStack Configuration
+LOCALSTACK_VERSION=latest
+LOCALSTACK_SERVICES=s3,sqs,sns,dynamodb,lambda,cloudformation
+LOCALSTACK_DEBUG=0
+LOCALSTACK_EDGE_PORT=4566
+LOCALSTACK_S3_PORT=4571

package/overlays/localstack/README.md

@@ -0,0 +1,188 @@
+# LocalStack Overlay
+
+Local AWS cloud stack for development and testing without requiring an AWS account.
+
+## Features
+
+- **LocalStack** - Full AWS cloud emulator running locally
+- **Multiple AWS Services** - S3, DynamoDB, SQS, SNS, Lambda, CloudFormation, and more
+- **Docker Compose service** - Runs as separate container
+- **Persistent storage** - Data survives container restarts
+- **Pre-configured environment** - AWS CLI ready to use with LocalStack endpoints
+
+## How It Works
+
+This overlay adds LocalStack as a Docker Compose service that emulates AWS cloud services locally. The service runs in its own container and is accessible from your development container via the hostname `localstack`.
+
+**Architecture:**
+
+- Edge API endpoint: `http://localstack:4566` (all services)
+- S3 endpoint: `http://localstack:4571` (S3-specific)
+- Services run inside LocalStack container
+- Data persisted to Docker volume
+
+## Configuration
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy it to `.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Default values (.env.example):**
+
+```bash
+# LocalStack Configuration
+LOCALSTACK_VERSION=latest
+LOCALSTACK_SERVICES=s3,sqs,sns,dynamodb,lambda,cloudformation
+LOCALSTACK_DEBUG=0
+LOCALSTACK_EDGE_PORT=4566
+LOCALSTACK_S3_PORT=4571
+```
+
+### Available Services
+
+LocalStack supports many AWS services. Common ones include:
+
+- **Storage**: S3, EFS
+- **Databases**: DynamoDB, RDS, Redshift
+- **Messaging**: SQS, SNS, Kinesis
+- **Compute**: Lambda, ECS, Batch
+- **Infrastructure**: CloudFormation, CloudWatch
+
+Set `LOCALSTACK_SERVICES` to enable specific services or use `LOCALSTACK_SERVICES=` (empty) to enable all.
+
+### Port Configuration
+
+The default ports (4566, 4571) can be changed via the `--port-offset` option when initializing the devcontainer:
+
+```bash
+npm run init -- --port-offset 100 --stack compose --cloud localstack
+# LocalStack Edge will be on port 4666, S3 on port 4671
+```
+
+## Common Commands
+
+### AWS CLI Usage
+
+The `aws-cli` overlay integrates seamlessly with LocalStack:
+
+```bash
+# AWS CLI automatically uses LocalStack endpoints via AWS_ENDPOINT_URL
+aws s3 ls
+aws s3 mb s3://my-bucket
+aws s3 cp myfile.txt s3://my-bucket/
+
+# DynamoDB
+aws dynamodb list-tables
+aws dynamodb create-table --table-name MyTable \
+  --attribute-definitions AttributeName=id,AttributeType=S \
+  --key-schema AttributeName=id,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST
+
+# SQS
+aws sqs list-queues
+aws sqs create-queue --queue-name my-queue
+aws sqs send-message --queue-url http://localstack:4566/000000000000/my-queue \
+  --message-body "Hello LocalStack"
+
+# Lambda
+aws lambda list-functions
+```
+
+### Health Check
+
+```bash
+# Check LocalStack health
+curl http://localstack:4566/_localstack/health
+
+# Check specific service
+curl http://localstack:4566/_localstack/health | jq '.services.s3'
+```
+
+### Direct API Calls
+
+```bash
+# S3 via REST API
+curl http://localstack:4566/my-bucket
+
+# List buckets
+aws --endpoint-url=http://localstack:4566 s3 ls
+```
+
+## Use Cases
+
+- **Cloud development without AWS account** - Develop and test AWS-based applications locally
+- **Integration testing** - Test cloud integrations without external dependencies
+- **Learning AWS services** - Experiment with AWS APIs without cost
+- **CI/CD pipelines** - Run AWS-dependent tests in CI without credentials
+- **Event-driven architectures** - Test SQS, SNS, Lambda workflows locally
+
+**Integrates well with:**
+
+- `aws-cli` - AWS command-line interface (suggested)
+- `terraform` - Infrastructure as Code testing
+- `pulumi` - Infrastructure as Code testing
+- Node.js, Python, .NET - Application development with AWS SDK
+
+## Differences from Real AWS
+
+LocalStack aims for high fidelity but has some differences:
+
+- **Authentication** - Uses test credentials (no real IAM)
+- **Performance** - May be faster or slower than real AWS
+- **Feature parity** - Not all AWS features supported
+- **Behavior** - Some edge cases may differ
+
+For production deployments, always test on real AWS.
+
+## Troubleshooting
+
+### Service Not Ready
+
+If LocalStack takes time to start:
+
+```bash
+# Check logs
+docker-compose logs localstack
+
+# Wait for health check
+curl http://localstack:4566/_localstack/health
+```
+
+### Connection Refused
+
+Ensure the service is running:
+
+```bash
+# Check service status
+docker-compose ps localstack
+
+# Restart if needed
+docker-compose restart localstack
+```
+
+### Services Not Available
+
+Enable specific services in `.env`:
+
+```bash
+LOCALSTACK_SERVICES=s3,dynamodb,sqs,sns,lambda
+```
+
+## References
+
+- [LocalStack Documentation](https://docs.localstack.cloud/)
+- [LocalStack GitHub](https://github.com/localstack/localstack)
+- [Supported AWS Services](https://docs.localstack.cloud/user-guide/aws/feature-coverage/)
+- [AWS CLI with LocalStack](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
+
+**Related Overlays:**
+
+- `aws-cli` - AWS command-line interface
+- `terraform` - Infrastructure as Code
+- `pulumi` - Infrastructure as Code
+- `nodejs`, `python`, `dotnet` - Application development

package/overlays/localstack/devcontainer.patch.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["localstack"],
+    "forwardPorts": [4566, 4571],
+    "portsAttributes": {
+        "4566": {
+            "label": "LocalStack Edge",
+            "onAutoForward": "notify"
+        },
+        "4571": {
+            "label": "LocalStack S3",
+            "onAutoForward": "ignore"
+        }
+    },
+    "remoteEnv": {
+        "AWS_ENDPOINT_URL": "http://localstack:4566",
+        "AWS_ACCESS_KEY_ID": "test",
+        "AWS_SECRET_ACCESS_KEY": "test",
+        "AWS_DEFAULT_REGION": "us-east-1"
+    }
+}

package/overlays/localstack/docker-compose.yml

@@ -0,0 +1,25 @@
+version: '3.8'
+
+services:
+    localstack:
+        image: localstack/localstack:${LOCALSTACK_VERSION:-latest}
+        restart: unless-stopped
+        volumes:
+            - localstack-data:/var/lib/localstack
+            - /var/run/docker.sock:/var/run/docker.sock
+        environment:
+            SERVICES: ${LOCALSTACK_SERVICES:-s3,sqs,sns,dynamodb,lambda,cloudformation}
+            DEBUG: ${LOCALSTACK_DEBUG:-0}
+            DATA_DIR: /var/lib/localstack
+            DOCKER_HOST: unix:///var/run/docker.sock
+        ports:
+            - '${LOCALSTACK_EDGE_PORT:-4566}:4566'
+            - '${LOCALSTACK_S3_PORT:-4571}:4571'
+        networks:
+            - devnet
+
+volumes:
+    localstack-data:
+
+networks:
+    devnet:

package/overlays/localstack/overlay.yml

@@ -0,0 +1,18 @@
+id: localstack
+name: LocalStack
+description: Local AWS cloud stack for development and testing
+category: cloud
+supports:
+    - compose
+requires: []
+suggests:
+    - aws-cli
+conflicts: []
+tags:
+    - cloud
+    - aws
+    - testing
+    - localstack
+ports:
+    - 4566
+    - 4571