container-superposition 0.1.7 → 0.1.9

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/README.md

@@ -10,6 +10,7 @@ This directory contains reusable configuration fragments that can be imported by
 │   ├── instrumentation.env            # OTEL SDK env vars for instrumentation
 │   └── otel-base-config.yaml          # Base OTEL collector pipeline config
 ├── compose/                           # Docker Compose patterns
+│   ├── nvidia-gpu-devcontainer.yml    # NVIDIA GPU passthrough for the devcontainer service
 │   └── common-healthchecks.md         # Standard healthcheck patterns (reference — not importable)
 └── vscode/                            # VS Code extension sets
     └── recommended-extensions.json    # Commonly recommended extensions (devcontainer patch)
@@ -44,6 +45,20 @@ This directory contains reusable configuration fragments that can be imported by
 
 ---
 
+### `compose/nvidia-gpu-devcontainer.yml`
+
+**Purpose:** Adds the `deploy.resources.reservations.devices` block to the `devcontainer` service, giving the devcontainer itself direct NVIDIA GPU access. This enables GPU-accelerated tooling (`torch`, `tensorflow`, CUDA CLIs, `nvidia-smi`) to work directly in the dev environment.
+
+**Format:** Docker Compose service fragment (services.devcontainer only).
+
+**Merge type:** `compose_imports:` — deep-merged into the final `docker-compose.yml` before the overlay's own `docker-compose.yml`.
+
+**Imported by:** `ollama`
+
+**Prerequisites:** NVIDIA Container Toolkit must be installed on the host.
+
+---
+
 ### `compose/common-healthchecks.md`
 
 **Purpose:** Reference library of standard Docker Compose healthcheck patterns for common services (HTTP, PostgreSQL, Redis, MongoDB, MySQL).
@@ -64,7 +79,7 @@ This directory contains reusable configuration fragments that can be imported by
 
 ## Usage
 
-Reference shared fragments in `overlay.yml` via the `imports` field:
+Reference shared devcontainer fragments in `overlay.yml` via the `imports` field:
 
 ```yaml
 id: my-overlay
@@ -73,11 +88,21 @@ imports:
     - .shared/vscode/recommended-extensions.json
 ```
 
+Reference shared docker-compose fragments via the `compose_imports` field:
+
+```yaml
+id: my-overlay
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml
+```
+
 **Rules:**
 
 - All paths must begin with `.shared/`
 - Paths are relative to `overlays/`
-- Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+- `imports` fragments are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+- `compose_imports` fragments are deep-merged into `docker-compose.yml` before the overlay's own `docker-compose.yml` (overlay wins on conflict)
+- `compose_imports` files must be `.yml` or `.yaml`
 
 ## Creating New Fragments
 

package/overlays/.shared/compose/nvidia-gpu-devcontainer.yml

@@ -0,0 +1,22 @@
+# Shared Docker Compose fragment: NVIDIA GPU passthrough for the devcontainer service.
+#
+# Adds the deploy.resources.reservations.devices block to the devcontainer service so
+# GPU-accelerated tooling (torch, tensorflow, CUDA CLIs, etc.) works directly in the
+# dev environment alongside any GPU-enabled sidecar services.
+#
+# Requirements: NVIDIA Container Toolkit must be installed on the host.
+#   https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
+#
+# Used by: ollama
+# Import via compose_imports in overlay.yml:
+#   compose_imports:
+#     - .shared/compose/nvidia-gpu-devcontainer.yml
+services:
+    devcontainer:
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]

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/bun/devcontainer.patch.json

@@ -12,16 +12,7 @@
     },
     "customizations": {
         "vscode": {
-            "extensions": ["oven.bun-vscode", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
-            "settings": {
-                "editor.defaultFormatter": "esbenp.prettier-vscode",
-                "[typescript]": {
-                    "editor.defaultFormatter": "esbenp.prettier-vscode"
-                },
-                "[javascript]": {
-                    "editor.defaultFormatter": "esbenp.prettier-vscode"
-                }
-            }
+            "extensions": ["oven.bun-vscode"]
         }
     },
     "remoteEnv": {

package/overlays/bun/overlay.yml

@@ -5,7 +5,12 @@ category: language
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - grafana
+    - open-webui
+    - mysql
+    - redpanda
+    - otel-demo-nodejs
 tags:
     - language
     - bun
@@ -14,3 +19,5 @@ tags:
 ports:
     - 3000
     - 8080
+imports:
+    - .shared/vscode/js-ts-settings.json

package/overlays/claude-code/devcontainer.patch.json

@@ -1,3 +1,8 @@
 {
-    "$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",
+    "customizations": {
+        "vscode": {
+            "extensions": ["anthropic.claude-code"]
+        }
+    }
 }

package/overlays/codex/devcontainer.patch.json

@@ -5,5 +5,10 @@
             "apt": "bubblewrap",
             "apk": "bubblewrap"
         }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["openai.chatgpt"]
+        }
     }
 }

package/overlays/comfyui/.env.example

@@ -0,0 +1,34 @@
+# ComfyUI Configuration
+
+# ComfyUI models storage strategy:
+#
+# Option A (default) — named Docker volume (no host path needed):
+#   Leave COMFYUI_MODELS_HOST_PATH unset. Models persist in the Docker volume
+#   named "comfyui-models" and are shared between devcontainer and ComfyUI.
+#
+# Option B — bind mount to host directory (also accessible from host tools):
+#   Set COMFYUI_MODELS_HOST_PATH to an absolute host path.
+#   Docker creates the directory if it does not exist.
+#   Note: Docker Compose does not expand '~' in .env files; always use full absolute paths.
+#   macOS/Linux examples:
+#     COMFYUI_MODELS_HOST_PATH=/home/you/.cache/comfyui/models
+#     COMFYUI_MODELS_HOST_PATH=/home/you/ComfyUI/models
+#   Windows (Docker Desktop — use absolute path, no tilde):
+#     COMFYUI_MODELS_HOST_PATH=C:/Users/you/.cache/comfyui/models
+#
+# COMFYUI_MODELS_HOST_PATH=
+
+# Where ComfyUI-generated images/videos are saved.
+# Leave unset to use the named Docker volume "comfyui-output" (default),
+# or set to an absolute host path to save outputs to the host filesystem.
+# COMFYUI_OUTPUT_PATH=
+
+# ComfyUI Docker image tag. Use 'latest-cuda' for NVIDIA GPU, 'latest-rocm' for AMD/ROCm, or 'latest-cpu' for CPU-only.
+COMFYUI_VERSION=latest-cuda
+
+# Host port for the ComfyUI web UI. Default: 8188.
+COMFYUI_PORT=8188
+
+# Extra CLI arguments passed to ComfyUI at startup.
+# --listen 0.0.0.0 is required to accept connections from outside the container.
+CLI_ARGS=--listen 0.0.0.0