container-superposition 0.1.1 → 0.1.4

package/overlays/keycloak/README.md

@@ -0,0 +1,238 @@
+# Keycloak Overlay
+
+Open-source identity and access management for developing apps with OAuth2/OIDC authentication.
+
+## Features
+
+- **Keycloak 26** - Latest stable version with OIDC/OAuth2 support
+- **Admin console** - Web UI for managing realms, clients, and users (port 8180)
+- **OIDC/OAuth2** - Full OpenID Connect and OAuth 2.0 support
+- **PostgreSQL backend** - Uses the PostgreSQL overlay as database
+- **Docker Compose service** - Runs as separate container
+- **Development mode** - Pre-configured for local development (no TLS required)
+
+## How It Works
+
+This overlay adds Keycloak as a Docker Compose service alongside your development container. It requires the `postgres` overlay to provide the database backend.
+
+**Architecture:**
+
+```
+Development Container
+  └─ Your application code
+  └─ Connects to keycloak:8180 for auth
+
+Keycloak Container (port 8180)
+  └─ Admin console
+  └─ OIDC/OAuth2 endpoints
+  └─ Connects to postgres:5432
+
+PostgreSQL Container (port 5432)
+  └─ Keycloak database storage
+```
+
+The Keycloak service is accessible from the dev container using the hostname `keycloak`.
+
+## 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
+# Keycloak Configuration
+KEYCLOAK_VERSION=26.0
+KEYCLOAK_PORT=8180
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=admin
+```
+
+⚠️ **Security Note:** Default credentials (`admin`/`admin`) are for development only. Never use these in production.
+
+### PostgreSQL Integration
+
+Keycloak uses the PostgreSQL overlay's environment variables:
+
+```bash
+POSTGRES_DB=devdb       # Database name
+POSTGRES_USER=postgres  # Database user
+POSTGRES_PASSWORD=postgres  # Database password
+```
+
+These are configured in the `postgres` overlay's `.env.example`.
+
+## Common Commands
+
+### Access Admin Console
+
+```bash
+# Open in browser
+open http://localhost:8180
+
+# Admin credentials
+# Username: admin (or KEYCLOAK_ADMIN value)
+# Password: admin (or KEYCLOAK_ADMIN_PASSWORD value)
+```
+
+### Realm Management
+
+```bash
+# List realms via Admin REST API
+curl -s \
+  -u admin:admin \
+  http://localhost:8180/admin/realms | jq '.[].realm'
+
+# Create a new realm
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  -u admin:admin \
+  http://localhost:8180/admin/realms \
+  -d '{"realm": "myrealm", "enabled": true}'
+```
+
+### OIDC Discovery
+
+```bash
+# Discover OIDC endpoints for the master realm
+curl -s http://localhost:8180/realms/master/.well-known/openid-configuration | jq .
+
+# Get discovery for a custom realm
+curl -s http://localhost:8180/realms/myrealm/.well-known/openid-configuration | jq .
+```
+
+### Client Credentials Flow
+
+```bash
+# Get access token using client credentials
+curl -s -X POST \
+  http://localhost:8180/realms/master/protocol/openid-connect/token \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "grant_type=password" | jq .access_token
+```
+
+### Token Introspection
+
+```bash
+TOKEN=$(curl -s -X POST \
+  http://localhost:8180/realms/master/protocol/openid-connect/token \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "grant_type=password" | jq -r .access_token)
+
+# Decode token (base64)
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .
+```
+
+## Application Integration
+
+### Node.js (using openid-client)
+
+```javascript
+import { Issuer } from 'openid-client';
+
+const keycloakIssuer = await Issuer.discover('http://keycloak:8180/realms/myrealm');
+
+const client = new keycloakIssuer.Client({
+    client_id: 'my-app',
+    client_secret: 'my-secret',
+    redirect_uris: ['http://localhost:3000/callback'],
+    response_types: ['code'],
+});
+```
+
+### Python (using requests-oauthlib)
+
+```python
+from requests_oauthlib import OAuth2Session
+
+oauth = OAuth2Session(
+    client_id="my-app",
+    redirect_uri="http://localhost:5000/callback",
+    scope=["openid", "profile", "email"]
+)
+
+authorization_url, state = oauth.authorization_url(
+    "http://keycloak:8180/realms/myrealm/protocol/openid-connect/auth"
+)
+```
+
+### .NET (using Microsoft.AspNetCore.Authentication.OpenIdConnect)
+
+```csharp
+builder.Services.AddAuthentication(options => {
+    options.DefaultScheme = "Cookies";
+    options.DefaultChallengeScheme = "oidc";
+})
+.AddCookie("Cookies")
+.AddOpenIdConnect("oidc", options => {
+    options.Authority = "http://keycloak:8180/realms/myrealm";
+    options.ClientId = "my-app";
+    options.ClientSecret = "my-secret";
+    options.ResponseType = "code";
+    options.RequireHttpsMetadata = false; // Development only
+});
+```
+
+## Use Cases
+
+- **OAuth2/OIDC integration testing** - Test authentication flows end-to-end
+- **Multi-tenant applications** - Create separate realms per tenant
+- **SSO development** - Single Sign-On across multiple local services
+- **Identity federation** - Test social login, LDAP, SAML integration
+- **Role-based access control** - Define and test permissions locally
+
+## Troubleshooting
+
+### Keycloak takes too long to start
+
+Keycloak can take 60–90 seconds on first startup (database schema creation). Wait for the health check to pass:
+
+```bash
+docker-compose logs -f keycloak
+# Look for: "Keycloak X.X started"
+```
+
+### Database connection errors
+
+Ensure PostgreSQL is running and healthy before Keycloak starts:
+
+```bash
+docker-compose ps postgres
+# Should show "healthy"
+```
+
+### Cannot connect from application
+
+Use `keycloak` (not `localhost`) as the hostname when connecting from inside the container:
+
+```bash
+# Correct (from inside dev container)
+http://keycloak:8180/realms/master
+
+# Correct (from host machine browser)
+http://localhost:8180/realms/master
+```
+
+## References
+
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/)
+- [OpenID Connect Specification](https://openid.net/connect/)
+- [Keycloak Docker Image](https://quay.io/repository/keycloak/keycloak)
+
+**Related Overlays:**
+
+- `postgres` - Required database backend
+- `nodejs` - Node.js application development
+- `python` - Python application development
+- `dotnet` - .NET application development

package/overlays/keycloak/devcontainer.patch.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["keycloak"],
+    "_serviceOrder": 10,
+    "forwardPorts": [8180],
+    "portsAttributes": {
+        "8180": {
+            "label": "Keycloak Admin Console",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "KEYCLOAK_HOST": "keycloak",
+        "KEYCLOAK_PORT": "8180",
+        "KEYCLOAK_ISSUER": "http://keycloak:8180/realms/master"
+    }
+}

package/overlays/keycloak/docker-compose.yml

@@ -0,0 +1,32 @@
+version: '3.8'
+
+services:
+    keycloak:
+        image: quay.io/keycloak/keycloak:${KEYCLOAK_VERSION:-26.0}
+        command: start-dev
+        restart: unless-stopped
+        environment:
+            KC_DB: postgres
+            KC_DB_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-devdb}
+            KC_DB_USERNAME: ${POSTGRES_USER:-postgres}
+            KC_DB_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+            KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN:-admin}
+            KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD:-admin}
+            KC_HTTP_PORT: 8180
+            KC_HOSTNAME_STRICT: 'false'
+            KC_HTTP_ENABLED: 'true'
+        ports:
+            - '${KEYCLOAK_PORT:-8180}:8180'
+        depends_on:
+            - postgres
+        networks:
+            - devnet
+        healthcheck:
+            test: ['CMD-SHELL', 'curl -sf http://localhost:8180/health/ready || exit 1']
+            interval: 15s
+            timeout: 10s
+            retries: 10
+            start_period: 60s
+
+networks:
+    devnet:

package/overlays/keycloak/overlay.yml

@@ -0,0 +1,23 @@
+id: keycloak
+name: Keycloak
+description: Open-source identity and access management (OIDC/OAuth2)
+category: dev
+supports:
+    - compose
+requires:
+    - postgres
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - auth
+    - oidc
+    - oauth2
+    - identity
+ports:
+    - port: 8180
+      service: keycloak
+      protocol: http
+      description: Keycloak admin console and auth endpoints
+      path: /
+      onAutoForward: openBrowser

package/overlays/keycloak/verify.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Verification script for Keycloak overlay
+# Confirms Keycloak is running and accessible
+
+set -e
+
+echo "🔍 Verifying Keycloak overlay..."
+echo ""
+
+# Check if curl is available
+echo "1️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check Keycloak health endpoint
+echo ""
+echo "2️⃣ Checking Keycloak service..."
+KEYCLOAK_HOST="${KEYCLOAK_HOST:-keycloak}"
+KEYCLOAK_PORT="${KEYCLOAK_PORT:-8180}"
+KEYCLOAK_READY=false
+
+for i in {1..40}; do
+    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/health/ready" &> /dev/null; then
+        echo "   ✅ Keycloak service is ready"
+        KEYCLOAK_READY=true
+        break
+    fi
+    sleep 3
+done
+
+if [ "$KEYCLOAK_READY" = false ]; then
+    echo "   ❌ Keycloak service not ready after 2 minutes"
+    echo "   ℹ️  Keycloak can take a while to start on first run"
+    exit 1
+fi
+
+# Check OIDC discovery endpoint
+echo ""
+echo "3️⃣ Checking OIDC discovery endpoint..."
+if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/realms/master/.well-known/openid-configuration" &> /dev/null; then
+    echo "   ✅ OIDC discovery endpoint is accessible"
+else
+    echo "   ❌ OIDC discovery endpoint not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ Keycloak overlay verification complete"
+echo "   Admin console: http://localhost:${KEYCLOAK_PORT}"
+echo "   Admin credentials: admin / admin (default)"
+echo "   OIDC discovery: http://localhost:${KEYCLOAK_PORT}/realms/master/.well-known/openid-configuration"

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"