container-superposition 0.1.8 → 0.1.10

package/overlays/.presets/k8s-dev.yml

@@ -0,0 +1,174 @@
+# Kubernetes Development Preset
+# Local Kubernetes cluster + dev loop tooling, language-agnostic
+
+id: k8s-dev
+name: Kubernetes Development
+description: Local Kubernetes cluster with fast inner-loop tooling — choose your cluster provider and dev-loop tool
+type: meta
+category: preset
+supports: [] # Works with both plain and compose
+tags: [preset, kubernetes, k8s, kind, k3d, skaffold, tilt, devloop, kubectl, helm]
+
+selects:
+    required:
+        - kubectl-helm
+        - docker-in-docker
+        - modern-cli-tools
+
+    userChoice: {}
+
+parameters:
+    cluster:
+        description: 'Local Kubernetes cluster provider'
+        default: k3d
+        options:
+            - id: k3d
+              overlays: [k3d]
+              description: 'k3d (k3s in Docker) — fastest startup, lowest memory, ideal for CI'
+            - id: kind
+              overlays: [kind]
+              description: 'kind (Kubernetes in Docker) — official CNCF tool, most compatible'
+
+    devloop:
+        description: 'Inner-loop dev tool (watch → build → deploy on save)'
+        default: tilt
+        options:
+            - id: tilt
+              overlays: [tilt]
+              description: 'Tilt — live UI, smart rebuilds, port-forward management'
+            - id: skaffold
+              overlays: [skaffold]
+              description: 'Skaffold — declarative YAML, CI-compatible, multi-deployer support'
+            - id: none
+              overlays: []
+              description: 'No dev-loop tool — use kubectl directly'
+
+glueConfig:
+    environment:
+        KUBECONFIG: '/home/vscode/.kube/config'
+        KUBECTL_CONTEXT: 'local'
+
+    portMappings:
+        app: 8080
+        tilt-ui: 10350
+
+    readme: |
+        ## Kubernetes Development Stack
+
+        This devcontainer provides a complete local Kubernetes development environment.
+
+        ### Tools
+
+        | Tool | Purpose |
+        |------|---------|
+        | kubectl + Helm | Kubernetes CLI and package manager |
+        | docker-in-docker | Run Docker inside the devcontainer to build images |
+        | k3d / kind | Provision a local Kubernetes cluster |
+        | Tilt / Skaffold | Watch → build → deploy inner loop |
+        | Modern CLI tools | `jq`, `yq`, `bat`, `fd`, `rg` for working with manifests |
+
+        ### Cluster Management
+
+        #### k3d (default)
+
+        ```bash
+        # Create cluster
+        k3d cluster create dev --port "8080:80@loadbalancer"
+
+        # List clusters
+        k3d cluster list
+
+        # Delete cluster
+        k3d cluster delete dev
+        ```
+
+        #### kind
+
+        ```bash
+        # Create cluster
+        kind create cluster --name dev
+
+        # List clusters
+        kind get clusters
+
+        # Delete cluster
+        kind delete cluster --name dev
+        ```
+
+        ### Inner-Loop Workflow
+
+        #### Tilt
+
+        Create a `Tiltfile` in your project root:
+
+        ```python
+        # Tiltfile
+        docker_build('my-app', '.')
+        k8s_yaml('k8s/')
+        k8s_resource('my-app', port_forwards=8080)
+        ```
+
+        Then run:
+
+        ```bash
+        tilt up
+        # Open http://localhost:10350 for the Tilt UI
+        ```
+
+        #### Skaffold
+
+        Create a `skaffold.yaml` in your project root:
+
+        ```yaml
+        apiVersion: skaffold/v4beta11
+        kind: Config
+        build:
+            artifacts:
+                - image: my-app
+        manifests:
+            rawYaml:
+                - k8s/*.yaml
+        ```
+
+        Then run:
+
+        ```bash
+        skaffold dev
+        ```
+
+        ### Helm Quick Start
+
+        ```bash
+        # Add a chart repository
+        helm repo add bitnami https://charts.bitnami.com/bitnami
+        helm repo update
+
+        # Install a chart
+        helm install my-release bitnami/postgresql
+
+        # Upgrade
+        helm upgrade my-release bitnami/postgresql --set auth.password=secret
+        ```
+
+        ### kubectl Tips
+
+        ```bash
+        # Watch all resources
+        kubectl get all -A -w
+
+        # Port-forward a service
+        kubectl port-forward svc/my-app 8080:80
+
+        # Inspect manifest with yq
+        kubectl get deployment my-app -o yaml | yq '.spec.template.spec.containers[0]'
+
+        # Live logs
+        kubectl logs -f -l app=my-app
+        ```
+
+        ### Next Steps
+
+        - Add a language overlay (`nodejs`, `go`, `python`, etc.) for your application runtime
+        - Add the `k8s-operator-dev` preset if you are building Kubernetes operators
+        - Configure image registry credentials for pushing built images
+        - Add Prometheus + Grafana overlays for in-cluster monitoring

package/overlays/.presets/local-llm.yml

@@ -0,0 +1,105 @@
+# Local LLM Stack Preset
+# Run local language models with a browser chat UI
+
+id: local-llm
+name: Local LLM Stack
+description: Local inference with Ollama and Open WebUI — pull any model and chat without an API key
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for Ollama service
+tags: [preset, ai, llm, ollama, open-webui, local-inference]
+
+selects:
+    required:
+        - ollama
+        - ollama-cli
+        - open-webui
+
+    userChoice: {}
+
+parameters:
+    gpu:
+        description: 'GPU acceleration (optional — CPU works without it)'
+        default: none
+        options:
+            - id: none
+              overlays: []
+              description: 'CPU only — works on any machine, slower for large models'
+            - id: nvidia
+              overlays: [cuda]
+              description: 'Nvidia GPU via CUDA'
+            - id: amd
+              overlays: [rocm]
+              description: 'AMD GPU via ROCm'
+
+glueConfig:
+    environment:
+        OLLAMA_HOST: 'http://ollama:11434'
+
+    portMappings:
+        ollama-api: 11434
+        open-webui: 3000
+
+    readme: |
+        ## Local LLM Stack
+
+        This devcontainer runs a full local LLM environment — no API key required.
+
+        ### Services
+
+        - **Ollama** — LLM runtime serving models on port 11434
+        - **Open WebUI** — Browser-based chat UI at http://localhost:3000
+        - **ollama-cli** — `ollama` command available in the terminal
+
+        ### Quick Start
+
+        1. Open http://localhost:3000 in your browser
+        2. Sign up with any email (local only — no data leaves your machine)
+        3. Pull a model via the terminal or the UI:
+
+        ```bash
+        # Pull a model
+        ollama pull llama3.2
+
+        # Run interactively in the terminal
+        ollama run llama3.2
+
+        # List pulled models
+        ollama list
+        ```
+
+        ### Recommended Models
+
+        | Model | Size | Use case |
+        |-------|------|----------|
+        | `llama3.2` | 2–8 B | General purpose, fast |
+        | `mistral` | 7 B | Strong reasoning |
+        | `codellama` | 7–34 B | Code generation |
+        | `nomic-embed-text` | 137 M | Embeddings for RAG |
+        | `phi4` | 14 B | Microsoft research model |
+
+        ### Using the API
+
+        ```bash
+        # Chat completion
+        curl http://localhost:11434/api/chat -d '{
+          "model": "llama3.2",
+          "messages": [{"role": "user", "content": "Hello!"}]
+        }'
+
+        # Generate embeddings
+        curl http://localhost:11434/api/embeddings -d '{
+          "model": "nomic-embed-text",
+          "prompt": "Hello world"
+        }'
+        ```
+
+        ### GPU Acceleration
+
+        If you selected a GPU option, ensure the relevant drivers are installed on the host.
+        CPU-only mode works on any machine — expect ~10–30 tokens/sec for 7 B models.
+
+        ### Next Steps
+
+        - Add the `qdrant` overlay and `vector-ai` preset for a full RAG pipeline
+        - Add the `python` overlay to build LLM-powered apps

package/overlays/.presets/vector-ai.yml

@@ -0,0 +1,150 @@
+# Vector AI Stack Preset
+# Full RAG pipeline: vector DB + local embeddings + Python client
+
+id: vector-ai
+name: Vector AI Stack
+description: Full RAG pipeline — Qdrant vector database, Ollama for local embeddings, and Python for client code
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for Qdrant and Ollama services
+tags: [preset, ai, rag, vector, embeddings, qdrant, ollama, python]
+
+selects:
+    required:
+        - qdrant
+        - ollama
+        - ollama-cli
+        - python
+
+    userChoice: {}
+
+parameters:
+    gpu:
+        description: 'GPU acceleration for embedding generation'
+        default: none
+        options:
+            - id: none
+              overlays: []
+              description: 'CPU only — adequate for embedding workloads (smaller models)'
+            - id: nvidia
+              overlays: [cuda]
+              description: 'Nvidia GPU via CUDA — significantly faster embedding throughput'
+            - id: amd
+              overlays: [rocm]
+              description: 'AMD GPU via ROCm'
+
+    chat_ui:
+        description: 'Browser chat UI (optional — useful for testing your RAG pipeline)'
+        default: none
+        options:
+            - id: none
+              overlays: []
+              description: 'No chat UI — use the API or your own frontend'
+            - id: open-webui
+              overlays: [open-webui]
+              description: 'Open WebUI — test RAG-augmented chat visually'
+
+glueConfig:
+    environment:
+        OLLAMA_HOST: 'http://ollama:11434'
+        QDRANT_HOST: 'qdrant'
+        QDRANT_PORT: '6333'
+        QDRANT_URL: 'http://qdrant:6333'
+        EMBEDDING_MODEL: 'nomic-embed-text'
+
+    portMappings:
+        qdrant-rest: 6333
+        qdrant-grpc: 6334
+        ollama-api: 11434
+
+    readme: |
+        ## Vector AI Stack
+
+        This devcontainer provides a complete local RAG (Retrieval-Augmented Generation) pipeline.
+
+        ### Services
+
+        | Service | Port | Purpose |
+        |---------|------|---------|
+        | Qdrant | 6333 (REST), 6334 (gRPC) | Vector database |
+        | Ollama | 11434 | LLM and embedding model runtime |
+        | ollama-cli | — | `ollama` command in terminal |
+
+        ### Quick Start
+
+        #### 1. Pull an embedding model
+
+        ```bash
+        ollama pull nomic-embed-text
+        ```
+
+        #### 2. Pull a chat model (for RAG generation)
+
+        ```bash
+        ollama pull llama3.2
+        ```
+
+        #### 3. Build your pipeline (Python example)
+
+        ```python
+        from qdrant_client import QdrantClient
+        import ollama
+        import os
+
+        qdrant = QdrantClient(url=os.environ["QDRANT_URL"])
+        embedding_model = os.environ["EMBEDDING_MODEL"]
+
+        # Create a collection
+        from qdrant_client.models import Distance, VectorParams
+        qdrant.create_collection(
+            collection_name="docs",
+            vectors_config=VectorParams(size=768, distance=Distance.COSINE),
+        )
+
+        # Embed and index a document
+        text = "Container Superposition makes devcontainer composition easy."
+        response = ollama.embed(model=embedding_model, input=text)
+        vector = response["embeddings"][0]
+
+        qdrant.upsert(
+            collection_name="docs",
+            points=[{"id": 1, "vector": vector, "payload": {"text": text}}],
+        )
+
+        # Search
+        query = "How does devcontainer composition work?"
+        q_vec = ollama.embed(model=embedding_model, input=query)["embeddings"][0]
+        results = qdrant.search(collection_name="docs", query_vector=q_vec, limit=3)
+        for r in results:
+            print(r.payload["text"])
+        ```
+
+        ### Environment Variables
+
+        Already set in your devcontainer:
+
+        ```bash
+        OLLAMA_HOST=http://ollama:11434
+        QDRANT_HOST=qdrant
+        QDRANT_PORT=6333
+        QDRANT_URL=http://qdrant:6333
+        EMBEDDING_MODEL=nomic-embed-text
+        ```
+
+        ### Qdrant Dashboard
+
+        Access the Qdrant web dashboard at http://localhost:6333/dashboard to inspect
+        collections, run queries, and monitor index health.
+
+        ### Recommended Python Packages
+
+        ```bash
+        pip install qdrant-client ollama openai langchain-community
+        ```
+
+        ### Next Steps
+
+        - Add the `local-llm` preset's Open WebUI to test your RAG pipeline through a chat interface
+        - Swap `nomic-embed-text` for `mxbai-embed-large` for higher-quality embeddings
+        - Use Qdrant's named vectors for hybrid dense + sparse retrieval
+        - Add `prometheus` and `grafana` overlays to monitor Qdrant query performance

package/overlays/.shared/vscode/js-ts-settings.json

@@ -0,0 +1,19 @@
+{
+    "customizations": {
+        "vscode": {
+            "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
+            "settings": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+                "editor.formatOnSave": true,
+                "[typescript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true
+                },
+                "[javascript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true
+                }
+            }
+        }
+    }
+}

package/overlays/.shared/vscode/markdown-extensions.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "customizations": {
+        "vscode": {
+            "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
+        }
+    }
+}

package/overlays/alertmanager/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["alertmanager"],
-    "_serviceOrder": 2,
     "forwardPorts": [9093],
     "portsAttributes": {
         "9093": {

package/overlays/alertmanager/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     alertmanager:
         image: prom/alertmanager:${ALERTMANAGER_VERSION:-latest}
+        restart: unless-stopped
         command:
             - '--config.file=/etc/alertmanager/alertmanager.yml'
             - '--storage.path=/alertmanager'
@@ -12,9 +13,16 @@ services:
             - '${ALERTMANAGER_PORT:-9093}:9093'
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:9093/-/ready']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
 
 volumes:
     alertmanager_data:
 
 networks:
     devnet:
+        name: devnet

package/overlays/alertmanager/overlay.yml

@@ -15,3 +15,4 @@ tags:
 ports:
     - 9093
 order: 2
+serviceOrder: 2

package/overlays/amp/devcontainer.patch.json

@@ -1,3 +1,6 @@
 {
-    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "postCreateCommand": {
+        "setup-amp": "bash .devcontainer/scripts/setup-amp.sh"
+    }
 }

package/overlays/ansible/README.md

@@ -0,0 +1,163 @@
+# Ansible Overlay
+
+Adds [Ansible](https://www.ansible.com/) tooling for automation, configuration management, and infrastructure provisioning workflows inside your devcontainer.
+
+## Features
+
+- **Ansible CLI** — `ansible`, `ansible-playbook`, `ansible-galaxy`, `ansible-vault`, `ansible-doc`
+- **ansible-lint** — Best-practice and style checks for playbooks, roles, and collections
+- **VS Code Extension:** Red Hat Ansible (`redhat.ansible`) — syntax highlighting, autocomplete, and validation powered by the Ansible Language Server
+
+## How It Works
+
+Ansible and ansible-lint are installed via the shared `cross-distro-packages` feature during devcontainer creation:
+
+- **Debian/Ubuntu**: installs `ansible` (or `ansible-core`) and `ansible-lint` (or `python3-ansible-lint`) via `apt`
+- **Alpine**: installs `ansible` and `ansible-lint` via `apk`
+
+No extra services are started — Ansible runs entirely inside the devcontainer and connects to remote hosts (or `localhost`) over SSH or WinRM.
+
+**Dependencies:** None required. Combine with cloud CLI overlays (`aws-cli`, `azure-cli`, `gcloud`) for cloud target automation, or `terraform` for hybrid IaC workflows.
+
+## Common Commands
+
+### Inventory & Connectivity
+
+```bash
+# Ping all hosts in the default inventory
+ansible all -m ping
+
+# Ping using an explicit inventory file
+ansible all -i inventory/hosts.ini -m ping
+
+# Gather facts from a host group
+ansible webservers -m gather_facts -i inventory/hosts.ini
+
+# List all hosts in an inventory
+ansible-inventory -i inventory/hosts.ini --list
+```
+
+### Running Playbooks
+
+```bash
+# Run a playbook against all hosts in inventory
+ansible-playbook playbook.yml
+
+# Run with an explicit inventory
+ansible-playbook -i inventory/hosts.ini playbook.yml
+
+# Run with extra variables
+ansible-playbook playbook.yml -e "env=production db_host=db.example.com"
+
+# Limit execution to a specific host group
+ansible-playbook playbook.yml --limit webservers
+
+# Dry-run (check mode) — show changes without applying them
+ansible-playbook playbook.yml --check
+
+# Verbose output for debugging
+ansible-playbook playbook.yml -vvv
+```
+
+### Ansible Galaxy
+
+```bash
+# Install a collection from Galaxy
+ansible-galaxy collection install community.general
+
+# Install a role from Galaxy
+ansible-galaxy role install geerlingguy.nginx
+
+# Install from a requirements file
+ansible-galaxy install -r requirements.yml
+
+# List installed collections
+ansible-galaxy collection list
+```
+
+### Vault (Secrets Management)
+
+```bash
+# Encrypt a file
+ansible-vault encrypt secrets.yml
+
+# Decrypt a file
+ansible-vault decrypt secrets.yml
+
+# View an encrypted file without decrypting on disk
+ansible-vault view secrets.yml
+
+# Edit an encrypted file in place
+ansible-vault edit secrets.yml
+
+# Run a playbook with an encrypted vault
+ansible-playbook playbook.yml --ask-vault-pass
+```
+
+### Linting
+
+```bash
+# Lint a playbook
+ansible-lint playbook.yml
+
+# Lint all playbooks and roles in the current project
+ansible-lint
+
+# Show lint violations with profile info
+ansible-lint --profile production playbook.yml
+```
+
+## Quick Start
+
+Create a minimal localhost playbook:
+
+```yaml
+# playbook.yml
+- name: Local test
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  tasks:
+      - name: Ping localhost
+        ansible.builtin.ping:
+
+      - name: Print a message
+        ansible.builtin.debug:
+            msg: 'Ansible is working!'
+```
+
+Run and lint it:
+
+```bash
+ansible-playbook playbook.yml
+ansible-lint playbook.yml
+```
+
+## Use Cases
+
+- **Configuration management** — Enforce consistent state across servers (packages, files, services, users)
+- **Application deployment** — Orchestrate multi-step deployments to remote hosts or cloud VMs
+- **Cloud provisioning** — Combine with cloud modules (`amazon.aws`, `azure.azcollection`, `google.cloud`) to provision infrastructure
+- **Kubernetes automation** — Use the `kubernetes.core` collection to manage cluster resources
+- **Local development automation** — Run playbooks against `localhost` to set up or reset dev environments
+
+**Integrates well with:**
+
+- `aws-cli`, `azure-cli`, `gcloud` — cloud target automation via provider-specific modules
+- `terraform` — use Terraform for infra provisioning, Ansible for configuration of provisioned resources
+- `kubectl-helm` — manage Kubernetes workloads with the `kubernetes.core` Ansible collection
+
+## References
+
+- [Ansible Documentation](https://docs.ansible.com/)
+- [ansible-lint Documentation](https://ansible.readthedocs.io/projects/lint/)
+- [Ansible Galaxy](https://galaxy.ansible.com/)
+- [Red Hat Ansible VS Code Extension](https://marketplace.visualstudio.com/items?itemName=redhat.ansible)
+- [Ansible Collections Index](https://docs.ansible.com/ansible/latest/collections/index.html)
+
+**Related Overlays:**
+
+- [`aws-cli`](../aws-cli/README.md) — AWS CLI for cloud target automation
+- [`azure-cli`](../azure-cli/README.md) — Azure CLI for cloud target automation
+- [`gcloud`](../gcloud/README.md) — Google Cloud SDK for cloud target automation
+- [`terraform`](../terraform/README.md) — Infrastructure provisioning to pair with Ansible configuration management

package/overlays/ansible/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "ansible|ansible-core ansible-lint|python3-ansible-lint",
+            "apk": "ansible ansible-lint"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["redhat.ansible"]
+        }
+    }
+}