container-superposition 0.1.8 → 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/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/docker-compose.yml

@@ -37,3 +37,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/comfyui/overlay.yml

@@ -7,9 +7,13 @@ supports:
 requires: []
 suggests:
     - cuda
+    - rocm
     - python
     - ollama
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml
 conflicts: []
+serviceOrder: 3
 tags:
     - dev
     - ai

package/overlays/commitlint/devcontainer.patch.json

@@ -1,8 +1,3 @@
 {
-    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "ghcr.io/devcontainers/features/node:1": {
-            "version": "lts"
-        }
-    }
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
 }

package/overlays/docker-sock/overlay.yml

@@ -7,6 +7,7 @@ requires: []
 suggests: []
 conflicts:
     - docker-in-docker
+serviceOrder: 0
 tags:
     - dev
     - docker

package/overlays/dotnet/overlay.yml

@@ -5,7 +5,10 @@ category: language
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - mysql
+    - redpanda
+    - otel-demo-nodejs
 tags:
     - language
     - dotnet

package/overlays/fuseki/.env.example

@@ -0,0 +1,5 @@
+# Apache Jena Fuseki Configuration
+FUSEKI_VERSION={{cs.FUSEKI_VERSION}}
+FUSEKI_PORT={{cs.FUSEKI_PORT}}
+FUSEKI_ADMIN_PASSWORD={{cs.FUSEKI_ADMIN_PASSWORD}}
+FUSEKI_DATASET={{cs.FUSEKI_DATASET}}

package/overlays/fuseki/README.md

@@ -0,0 +1,173 @@
+# Apache Jena Fuseki Overlay
+
+SPARQL 1.1 server and RDF triplestore powered by Apache Jena TDB2, with a built-in web administration UI.
+
+## Features
+
+- **Apache Jena Fuseki** — SPARQL 1.1 server supporting queries, updates, and the Graph Store Protocol
+- **TDB2 triplestore** — High-performance persistent RDF storage with better concurrency than TDB1
+- **Admin web UI** — Browser-based interface for managing datasets, running ad-hoc queries, and monitoring the server (port 3030)
+- **REST management API** — Create, list, and delete datasets without restarting the server
+- **Dataset auto-creation** — A default dataset is created automatically on first start
+- **Persistent storage** — RDF data is stored in a named Docker volume (`fuseki-data`) and survives container restarts
+- **Docker Compose service** — Runs as an isolated sidecar container accessible on the `devnet` network
+
+## How It Works
+
+This overlay adds Fuseki as a separate Docker Compose service. Fuseki runs inside its own container and is reachable from your development container using the hostname `fuseki`.
+
+**Service configuration:**
+
+- Image: `ghcr.io/stain/jena-fuseki`
+- Network: `devnet` (shared with the dev container)
+- Persistence: `fuseki-data` volume for TDB2 database files
+- Port: 3030 (customizable via `FUSEKI_PORT` host mapping)
+
+**Environment variables set in the dev container:**
+
+| Variable                | Value                | Description                               |
+| ----------------------- | -------------------- | ----------------------------------------- |
+| `FUSEKI_HOST`           | `fuseki`             | Container hostname for internal access    |
+| `FUSEKI_PORT`           | `3030`               | Container-internal port for SPARQL access |
+| `FUSEKI_URL`            | `http://fuseki:3030` | Base URL for SPARQL requests              |
+| `FUSEKI_DATASET`        | `ds` (default)       | Name of the default dataset               |
+| `FUSEKI_ADMIN_PASSWORD` | see `.env`           | Admin user password (set in `.env`)       |
+
+## Common Commands
+
+### SPARQL Queries
+
+```bash
+# Simple SELECT query
+curl -X POST \
+  -H "Content-Type: application/sparql-query" \
+  -d "SELECT * WHERE { ?s ?p ?o } LIMIT 10" \
+  "$FUSEKI_URL/$FUSEKI_DATASET/query"
+
+# Query with URL encoding (GET request)
+curl -G "$FUSEKI_URL/$FUSEKI_DATASET/query" \
+  --data-urlencode "query=SELECT * WHERE { ?s ?p ?o } LIMIT 10"
+```
+
+### Loading RDF Data
+
+```bash
+# Load a Turtle file into the default graph
+curl -X PUT \
+  -H "Content-Type: text/turtle" \
+  --data-binary @data.ttl \
+  "$FUSEKI_URL/$FUSEKI_DATASET/data"
+
+# Add data without replacing existing triples (POST)
+curl -X POST \
+  -H "Content-Type: text/turtle" \
+  --data-binary @more-data.ttl \
+  "$FUSEKI_URL/$FUSEKI_DATASET/data"
+
+# Load into a named graph
+curl -X PUT \
+  -H "Content-Type: text/turtle" \
+  --data-binary @data.ttl \
+  "$FUSEKI_URL/$FUSEKI_DATASET/data?graph=http://example.org/mygraph"
+```
+
+### SPARQL Update
+
+```bash
+# Insert triples via SPARQL Update
+curl -X POST \
+  -H "Content-Type: application/sparql-update" \
+  -d "INSERT DATA { <http://example.org/s> <http://example.org/p> \"o\" . }" \
+  "$FUSEKI_URL/$FUSEKI_DATASET/update"
+```
+
+### Dataset Management
+
+```bash
+# List all datasets (requires admin credentials)
+curl -u "admin:$FUSEKI_ADMIN_PASSWORD" "$FUSEKI_URL/\$/datasets"
+
+# Create a new TDB2-backed dataset
+curl -X POST \
+  -u "admin:$FUSEKI_ADMIN_PASSWORD" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "dbName=mydata&dbType=tdb2" \
+  "$FUSEKI_URL/\$/datasets"
+
+# Delete a dataset
+curl -X DELETE \
+  -u "admin:$FUSEKI_ADMIN_PASSWORD" \
+  "$FUSEKI_URL/\$/datasets/mydata"
+```
+
+### Admin UI
+
+```bash
+# Open in browser (from the host machine)
+open http://localhost:3030
+```
+
+Log in with username `admin` and the configured `FUSEKI_ADMIN_PASSWORD`. From the UI you can browse and query datasets, upload RDF files, create/delete datasets, and monitor server statistics.
+
+## Use Cases
+
+- **Semantic web development** — Prototype and test OWL/RDFS ontologies and SPARQL queries locally
+- **Linked data applications** — Build applications that consume or publish RDF data
+- **Knowledge graph projects** — Store, update, and query knowledge graphs during development
+- **Data integration** — Use SPARQL Federation or CONSTRUCT queries to merge heterogeneous data sources
+- **Research and education** — Run SPARQL 1.1 workloads without a cloud account
+
+**Integrates well with:**
+
+- `java` — Use Apache Jena client library (`jena-arq`) for typed SPARQL queries
+- `python` — Use `SPARQLWrapper` or `rdflib-endpoint` for data science workflows
+- `nodejs` — Use `n3` or `comunica` for JavaScript/TypeScript SPARQL clients
+
+## Configuration
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Default values (`.devcontainer/.env.example`):**
+
+```bash
+FUSEKI_VERSION=latest
+FUSEKI_PORT=3030
+FUSEKI_ADMIN_PASSWORD=admin   # ⚠ Change this for any shared environment
+FUSEKI_DATASET=ds
+```
+
+⚠️ **Security:** The default `FUSEKI_ADMIN_PASSWORD=admin` must be changed for any environment accessible beyond localhost.
+
+### SPARQL Endpoints
+
+Default dataset `ds` endpoints (from inside the dev container):
+
+| Endpoint          | URL                            |
+| ----------------- | ------------------------------ |
+| SPARQL Query      | `http://fuseki:3030/ds/query`  |
+| SPARQL Update     | `http://fuseki:3030/ds/update` |
+| Graph Store (GSP) | `http://fuseki:3030/ds/data`   |
+| Admin UI          | `http://fuseki:3030`           |
+
+All endpoints are also forwarded to `localhost:3030` on the host machine.
+
+## References
+
+- [Apache Jena Fuseki Documentation](https://jena.apache.org/documentation/fuseki2/)
+- [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/)
+- [SPARQL 1.1 Update](https://www.w3.org/TR/sparql11-update/)
+- [Fuseki Docker Image (stain/jena-docker)](https://github.com/stain/jena-docker)
+- [Apache Jena TDB2](https://jena.apache.org/documentation/tdb2/)
+
+**Related Overlays:**
+
+- `java` — Develop JVM applications using Apache Jena client libraries
+- `python` — Use RDFLib or SPARQLWrapper for Python-based SPARQL workflows
+- `nodejs` — Build JavaScript SPARQL clients with Comunica or N3.js

package/overlays/fuseki/devcontainer.patch.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["fuseki"],
+    "forwardPorts": [3030],
+    "portsAttributes": {
+        "3030": {
+            "label": "Fuseki SPARQL Server",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "FUSEKI_HOST": "fuseki",
+        "FUSEKI_PORT": "3030",
+        "FUSEKI_DATASET": "{{cs.FUSEKI_DATASET}}",
+        "FUSEKI_ADMIN_PASSWORD": "{{cs.FUSEKI_ADMIN_PASSWORD}}",
+        "FUSEKI_URL": "http://fuseki:3030"
+    }
+}

package/overlays/fuseki/docker-compose.yml

@@ -0,0 +1,29 @@
+version: '3.8'
+
+services:
+    fuseki:
+        image: stain/jena-fuseki:${FUSEKI_VERSION:-{{cs.FUSEKI_VERSION}}}
+        restart: unless-stopped
+        volumes:
+            - fuseki-data:/fuseki
+        environment:
+            ADMIN_PASSWORD: ${FUSEKI_ADMIN_PASSWORD:-{{cs.FUSEKI_ADMIN_PASSWORD}}}
+            FUSEKI_DATASET_1: ${FUSEKI_DATASET:-{{cs.FUSEKI_DATASET}}}
+            TDB: '2'
+        ports:
+            - '${FUSEKI_PORT:-{{cs.FUSEKI_PORT}}}:3030'
+        networks:
+            - devnet
+        healthcheck:
+            test: ['CMD-SHELL', 'curl -sf http://localhost:3030/$/ping || exit 1']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 20s
+
+volumes:
+    fuseki-data:
+
+networks:
+    devnet:
+        name: devnet

package/overlays/fuseki/overlay.yml

@@ -0,0 +1,42 @@
+id: fuseki
+name: Apache Jena Fuseki
+description: SPARQL 1.1 server and triplestore backed by Apache Jena TDB
+category: database
+supports:
+    - compose
+requires: []
+suggests:
+    - java
+    - python
+    - nodejs
+conflicts: []
+serviceOrder: 0
+tags:
+    - database
+    - rdf
+    - sparql
+    - triplestore
+    - semantic-web
+    - linked-data
+    - jena
+ports:
+    - port: 3030
+      service: fuseki
+      protocol: http
+      description: Fuseki SPARQL server and admin UI
+      path: /
+      onAutoForward: openBrowser
+parameters:
+    FUSEKI_VERSION:
+        description: Apache Jena Fuseki image version tag
+        default: latest
+    FUSEKI_PORT:
+        description: Host port mapped to Fuseki (3030 inside container)
+        default: '3030'
+    FUSEKI_ADMIN_PASSWORD:
+        description: Fuseki admin user password
+        default: admin
+        sensitive: true
+    FUSEKI_DATASET:
+        description: Name of the default dataset to create on first start
+        default: ds

package/overlays/fuseki/verify.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Verification script for Apache Jena Fuseki overlay
+# Confirms Fuseki is running and responding to requests
+
+set -e
+
+FUSEKI_HOST="${FUSEKI_HOST:-fuseki}"
+FUSEKI_PORT="${FUSEKI_PORT:-3030}"
+FUSEKI_URL="http://${FUSEKI_HOST}:${FUSEKI_PORT}"
+
+echo "Verifying Apache Jena Fuseki overlay..."
+echo ""
+
+# Check curl is available
+echo "1. Checking curl availability..."
+if command -v curl &> /dev/null; then
+    echo "   curl found"
+else
+    echo "   curl not found - cannot verify Fuseki service"
+    exit 1
+fi
+
+# Check Fuseki ping endpoint
+echo ""
+echo "2. Checking Fuseki service at ${FUSEKI_URL}/\$/ping..."
+FUSEKI_READY=false
+for i in {1..15}; do
+    if curl -sf "${FUSEKI_URL}/\$/ping" &> /dev/null; then
+        echo "   Fuseki service is ready"
+        FUSEKI_READY=true
+        break
+    fi
+    sleep 2
+done
+
+if [ "$FUSEKI_READY" = false ]; then
+    echo "   Fuseki service not ready after 30 seconds"
+    exit 1
+fi
+
+# Check dataset exists
+DATASET="${FUSEKI_DATASET:-ds}"
+ADMIN_PASSWORD="${FUSEKI_ADMIN_PASSWORD:-admin}"
+echo ""
+echo "3. Checking dataset '${DATASET}' exists..."
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+    -u "admin:${ADMIN_PASSWORD}" \
+    "${FUSEKI_URL}/\$/datasets/${DATASET}")
+
+if [ "$HTTP_STATUS" = "200" ]; then
+    echo "   Dataset '${DATASET}' found"
+else
+    echo "   Dataset '${DATASET}' not found (HTTP ${HTTP_STATUS}) - it may still be initializing"
+fi
+
+echo ""
+echo "Apache Jena Fuseki overlay verification complete"
+echo "Admin UI: ${FUSEKI_URL}"