container-superposition 0.1.7 → 0.1.9

package/overlays/ollama-cli/setup.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Ollama CLI setup script
+# Installs the Ollama CLI in the devcontainer for local or remote Ollama usage.
+
+set -e
+
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+if command_exists ollama; then
+    echo "✓ Ollama CLI already installed: $(ollama --version)"
+    echo "ℹ️  OLLAMA_HOST=${OLLAMA_HOST:-http://localhost:11434}"
+    exit 0
+fi
+
+echo "📦 Installing Ollama CLI..."
+# Prefer copying the CLI binary from a local Ollama Docker image when available.
+# This avoids downloading large release archives in Docker-enabled environments.
+OLLAMA_IMAGE="ollama/ollama:${OLLAMA_VERSION:-latest}"
+if command_exists docker && docker info >/dev/null 2>&1; then
+    tmpdir=$(mktemp -d)
+    docker_container_id=""
+    trap '[ -n "${docker_container_id}" ] && docker rm -f "${docker_container_id}" >/dev/null 2>&1 || true; rm -rf "${tmpdir}"' EXIT
+
+    # Guard Docker command substitutions with || fallback so failures here are
+    # non-fatal and the archive fallback below can still run.
+    container_id="$(docker ps -q --filter "ancestor=${OLLAMA_IMAGE}" 2>/dev/null | head -n 1)" || container_id=""
+
+    if [ -z "${container_id}" ] && docker image inspect "${OLLAMA_IMAGE}" >/dev/null 2>&1; then
+        container_id="$(docker create "${OLLAMA_IMAGE}" 2>/dev/null)" || container_id=""
+        [ -n "${container_id}" ] && docker_container_id="${container_id}"
+    fi
+
+    if [ -n "${container_id}" ] && docker cp "${container_id}:/usr/bin/ollama" "${tmpdir}/ollama" >/dev/null 2>&1; then
+        echo "📦 Installing Ollama CLI from local Docker image..."
+        sudo install -m 0755 "${tmpdir}/ollama" /usr/local/bin/ollama
+    fi
+
+    [ -n "${docker_container_id}" ] && docker rm -f "${docker_container_id}" >/dev/null 2>&1 || true
+    docker_container_id=""
+    rm -rf "${tmpdir}"
+    trap - EXIT
+fi
+
+if ! command_exists ollama; then
+    # Fallback to official release archives without invoking the full install.sh
+    # flow, which configures a local daemon/service.
+    OLLAMA_DOWNLOAD_BASE="https://ollama.com/download/ollama-linux-${CS_ARCH}"
+
+    if curl -fsSLI "${OLLAMA_DOWNLOAD_BASE}.tar.zst" >/dev/null 2>&1; then
+        if ! command_exists zstd; then
+            echo "📦 Installing zstd for Ollama archive extraction..."
+            apt_install zstd
+        fi
+
+        archive_size_bytes="$(
+            curl -fsSLI "${OLLAMA_DOWNLOAD_BASE}.tar.zst" |
+                awk 'BEGIN { IGNORECASE = 1 } /^content-length:/ { print $2 }' |
+                tr -d '\r' |
+                tail -n 1
+        )"
+
+        if [ -n "${archive_size_bytes}" ]; then
+            archive_size_gib="$(awk "BEGIN { printf \"%.1f\", ${archive_size_bytes} / 1024 / 1024 / 1024 }")"
+            echo "⬇️ Downloading official Ollama archive (~${archive_size_gib} GiB)..."
+        else
+            echo "⬇️ Downloading official Ollama archive..."
+        fi
+
+        tmpdir=$(mktemp -d)
+        trap 'rm -rf "${tmpdir}"' EXIT
+
+        curl --fail --location --progress-bar "${OLLAMA_DOWNLOAD_BASE}.tar.zst" -o "${tmpdir}/ollama.tar.zst"
+
+        # Match the official Linux package layout so the CLI keeps working even
+        # when upstream ships supporting files under lib/ollama alongside the
+        # top-level ollama binary.
+        echo "📦 Extracting Ollama CLI from archive..."
+        sudo rm -rf /usr/local/lib/ollama
+        zstd -d -c "${tmpdir}/ollama.tar.zst" | sudo tar -xf - -C /usr/local
+        sudo install -d /usr/local/bin
+        sudo ln -sf /usr/local/ollama /usr/local/bin/ollama
+
+        rm -rf "${tmpdir}"
+        trap - EXIT
+    else
+        install_binary_from_tar \
+            "${OLLAMA_DOWNLOAD_BASE}.tgz" \
+            "bin/ollama" \
+            "ollama"
+    fi
+fi
+
+export PATH="/usr/local/bin:/usr/bin:/bin:${PATH}"
+
+if ! command_exists ollama; then
+    echo "❌ Ollama CLI install completed but the binary is still not on PATH"
+    exit 1
+fi
+
+echo "✓ Ollama CLI installed: $(ollama --version)"
+echo "ℹ️  Configure OLLAMA_HOST to target your server (current: ${OLLAMA_HOST:-http://localhost:11434})"

package/overlays/ollama-cli/verify.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Verification script for Ollama CLI overlay
+
+set -e
+
+echo "🔍 Verifying Ollama CLI overlay..."
+echo ""
+
+echo "1️⃣ Checking Ollama CLI..."
+if ! command -v ollama &>/dev/null; then
+    echo "   ❌ ollama CLI not found"
+    echo ""
+    echo "❌ Ollama CLI overlay verification failed"
+    exit 1
+fi
+echo "   ✅ ollama CLI found: $(ollama --version 2>/dev/null || echo 'version unavailable')"
+
+echo ""
+echo "2️⃣ Checking OLLAMA_HOST configuration..."
+if [[ -z "${OLLAMA_HOST:-}" ]]; then
+    echo "   ℹ️  OLLAMA_HOST is not set (default CLI target: http://localhost:11434)"
+    echo "   ℹ️  Set OLLAMA_HOST to a reachable Ollama endpoint, e.g. http://host.docker.internal:11434"
+    echo ""
+    echo "✅ Ollama CLI overlay verification complete"
+    exit 0
+fi
+
+echo "   ✅ OLLAMA_HOST=${OLLAMA_HOST}"
+
+echo ""
+echo "3️⃣ Checking endpoint reachability (best effort)..."
+if ! command -v curl &>/dev/null; then
+    echo "   ⚠️  curl not found; skipping endpoint check"
+    echo ""
+    echo "✅ Ollama CLI overlay verification complete"
+    exit 0
+fi
+
+set +e
+if curl -sf "${OLLAMA_HOST}/api/tags" >/dev/null; then
+    echo "   ✅ Reached Ollama endpoint at ${OLLAMA_HOST}"
+else
+    echo "   ⚠️  Could not reach ${OLLAMA_HOST}/api/tags"
+    echo "   ⚠️  Ensure your Ollama server is running and reachable from the devcontainer"
+fi
+set -e
+
+echo ""
+echo "✅ Ollama CLI overlay verification complete"

package/overlays/open-webui/.env.example

@@ -0,0 +1,5 @@
+# Open WebUI Configuration
+OPEN_WEBUI_VERSION={{cs.OPEN_WEBUI_VERSION}}
+OPEN_WEBUI_PORT={{cs.OPEN_WEBUI_PORT}}
+OLLAMA_BASE_URL={{cs.OLLAMA_BASE_URL}}
+WEBUI_SECRET_KEY={{cs.WEBUI_SECRET_KEY}}

package/overlays/open-webui/README.md

@@ -0,0 +1,162 @@
+# Open WebUI Overlay
+
+Adds [Open WebUI](https://github.com/open-webui/open-webui) as a Docker Compose service, providing a polished browser-based chat interface for Ollama and other OpenAI-compatible LLM backends.
+
+## Features
+
+- **Browser-based chat UI** — Full-featured conversational interface for local LLMs at `http://localhost:3000`
+- **Ollama integration** — Pre-configured to connect to the `ollama` sidecar when the `ollama` overlay is also selected
+- **Multi-model support** — Switch between different Ollama models from the UI without CLI commands
+- **Conversation history** — Persists chat history in a named Docker volume across container rebuilds
+- **OpenAI-compatible** — Works with any backend that speaks the OpenAI Chat Completions API
+- **Port 3000** — Web interface auto-forwarded and opened in the browser
+
+## How It Works
+
+Open WebUI runs as a Docker Compose service (`open-webui`) alongside your devcontainer. It connects to the Ollama service (or any OpenAI-compatible API) using the `OLLAMA_BASE_URL` environment variable.
+
+**Service configuration:**
+
+- Image: `ghcr.io/open-webui/open-webui:main`
+- Network: `devnet` (shared with devcontainer and ollama)
+- Port: `3000` on the host, mapped to `8080` inside the container
+- Volume: `open-webui-data` for persistent chat history and settings
+
+When used together with the `ollama` overlay, the stack looks like:
+
+```
+devcontainer ─── open-webui (port 3000) ─┐
+                                          ├── devnet
+                 ollama (port 11434) ─────┘
+```
+
+Open WebUI reads `OLLAMA_BASE_URL` to find the Ollama API. When the `ollama` overlay is selected, this is pre-set to `http://ollama:11434`.
+
+## Common Commands
+
+### Web Interface
+
+```bash
+# Open the web UI (auto-forwarded to localhost:3000)
+# Navigate to http://localhost:3000 in your browser
+
+# Check service status
+docker compose ps open-webui
+
+# View logs
+docker compose logs open-webui
+docker compose logs -f open-webui
+
+# Restart the service
+docker compose restart open-webui
+```
+
+### Using with Ollama
+
+```bash
+# Pull a model with the Ollama CLI (still available in devcontainer)
+ollama pull llama3.2
+
+# The model will automatically appear in the Open WebUI model picker
+# Visit http://localhost:3000 and start chatting
+```
+
+### REST API
+
+Open WebUI exposes an OpenAI-compatible REST API at `http://localhost:3000/api`:
+
+```bash
+# List available models via Open WebUI API
+curl http://localhost:3000/api/models
+
+# Chat completion via OpenAI-compatible endpoint
+curl http://localhost:3000/api/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "llama3.2",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+## Configuration
+
+### Environment Variables
+
+Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
+
+| Variable             | Default               | Description                                      |
+| -------------------- | --------------------- | ------------------------------------------------ |
+| `OPEN_WEBUI_VERSION` | `main`                | Open WebUI Docker image tag                      |
+| `OPEN_WEBUI_PORT`    | `3000`                | Host port for the web interface                  |
+| `OLLAMA_BASE_URL`    | `http://ollama:11434` | Base URL of the Ollama API                       |
+| `WEBUI_SECRET_KEY`   | `supersecret`         | Secret key for session signing (change for prod) |
+
+### Connecting to a Different LLM Backend
+
+If you are not using the `ollama` overlay but have another OpenAI-compatible API available, set `OLLAMA_BASE_URL` in `.devcontainer/.env`:
+
+```bash
+# Point at a remote OpenAI-compatible server
+OLLAMA_BASE_URL=http://my-llm-server:8000
+```
+
+## Use Cases
+
+- **Local AI chat** — Interact with local models via a polished UI instead of the CLI
+- **Model comparison** — Switch between models mid-conversation to compare quality
+- **Prompt engineering** — Iterate on system prompts and parameters interactively
+- **Offline AI workflows** — Full AI chat capability without internet access or API costs
+- **Team demos** — Share the forwarded port URL with teammates for collaborative testing
+
+**Integrates well with:**
+
+- `ollama` — Provides the LLM backend; Open WebUI connects automatically
+- `cuda` — GPU acceleration for faster Ollama inference
+- `python` — Build integrations using the Open WebUI REST API
+
+## Troubleshooting
+
+### UI Not Loading
+
+```bash
+# Check the service is running
+docker compose ps open-webui
+
+# View startup logs
+docker compose logs open-webui
+
+# Restart the service
+docker compose restart open-webui
+```
+
+### No Models Available
+
+If the model picker in Open WebUI shows no models:
+
+1. Ensure the `ollama` overlay is selected and the Ollama service is running
+2. Pull a model with `ollama pull llama3.2` from the devcontainer terminal
+3. Refresh the Open WebUI page
+
+```bash
+# Verify Ollama is reachable from within the Open WebUI container
+docker compose exec open-webui curl -sf http://ollama:11434/api/tags
+```
+
+### Port Conflict on 3000
+
+```bash
+# .devcontainer/.env
+OPEN_WEBUI_PORT=3001
+```
+
+## References
+
+- [Open WebUI GitHub](https://github.com/open-webui/open-webui)
+- [Open WebUI Documentation](https://docs.openwebui.com)
+- [Open WebUI Docker Hub](https://ghcr.io/open-webui/open-webui)
+
+**Related Overlays:**
+
+- [`ollama`](../ollama/README.md) — Local LLM inference server (recommended companion)
+- [`cuda`](../cuda/README.md) — NVIDIA GPU acceleration for faster inference
+- [`python`](../python/README.md) — Python SDK for building integrations

package/overlays/open-webui/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["open-webui"],
+    "forwardPorts": [3000],
+    "portsAttributes": {
+        "3000": {
+            "label": "Open WebUI",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "containerEnv": {
+        "OPEN_WEBUI_PORT": "3000"
+    }
+}

package/overlays/open-webui/docker-compose.yml

@@ -0,0 +1,24 @@
+version: '3.8'
+
+services:
+    open-webui:
+        image: ghcr.io/open-webui/open-webui:${OPEN_WEBUI_VERSION:-{{cs.OPEN_WEBUI_VERSION}}}
+        restart: unless-stopped
+        volumes:
+            - open-webui-data:/app/backend/data
+        environment:
+            OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-{{cs.OLLAMA_BASE_URL}}}
+            WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:-{{cs.WEBUI_SECRET_KEY}}}
+        ports:
+            - '${OPEN_WEBUI_PORT:-{{cs.OPEN_WEBUI_PORT}}}:8080'
+        extra_hosts:
+            - host.docker.internal:host-gateway
+        networks:
+            - devnet
+
+volumes:
+    open-webui-data:
+
+networks:
+    devnet:
+        name: devnet

package/overlays/open-webui/overlay.yml

@@ -0,0 +1,45 @@
+id: open-webui
+name: Open WebUI
+description: Browser-based chat UI for Ollama and OpenAI-compatible LLM backends
+category: dev
+supports:
+    - compose
+requires: []
+suggests:
+    - ollama
+    - prometheus
+    - otel-collector
+conflicts:
+    - grafana
+    - nodejs
+    - bun
+    - rust
+serviceOrder: 3
+tags:
+    - dev
+    - ai
+    - llm
+    - ui
+    - chat
+    - openwebui
+ports:
+    - port: 3000
+      service: open-webui
+      protocol: http
+      path: /
+      description: Open WebUI web interface
+      onAutoForward: openBrowser
+parameters:
+    OPEN_WEBUI_VERSION:
+        description: Open WebUI Docker image tag
+        default: main
+    OPEN_WEBUI_PORT:
+        description: Host port mapped to the Open WebUI web interface (8080 inside container)
+        default: '3000'
+    OLLAMA_BASE_URL:
+        description: Base URL of the Ollama API (leave default when using the ollama overlay)
+        default: 'http://ollama:11434'
+    WEBUI_SECRET_KEY:
+        description: Secret key for Open WebUI session signing (change for any shared environment)
+        default: change-me-please
+        sensitive: true

package/overlays/opencode/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-opencode": "bash .devcontainer/scripts/setup-opencode.sh"
+    }
 }

package/overlays/otel-collector/README.md

@@ -45,6 +45,10 @@ graph TD
 - `8889` - Prometheus exporter endpoint (scrape target)
 - `13133` - Health check extension
 
+### Pre-configured OpenTelemetry Environment
+
+When this overlay is selected, the devcontainer's `OTEL_EXPORTER_OTLP_ENDPOINT` is automatically set to `http://otel-collector:4317` so that any properly-instrumented app sends telemetry to the collector. If the **jaeger** overlay is also selected, the collector overlay takes precedence (it is applied later) and correctly routes telemetry through the collector pipeline to Jaeger.
+
 ### Environment Variables
 
 The overlay includes a `.env.example` file. Copy it to `.env` and customize:

package/overlays/otel-collector/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["otel-collector"],
-    "_serviceOrder": 2,
     "forwardPorts": [4317, 4318, 8888, 8889, 13133],
     "portsAttributes": {
         "4317": {
@@ -24,5 +23,9 @@
             "label": "Health Check",
             "onAutoForward": "silent"
         }
+    },
+    "remoteEnv": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector:4317",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"
     }
 }

package/overlays/otel-collector/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     otel-collector:
         image: otel/opentelemetry-collector-contrib:${OTEL_COLLECTOR_VERSION:-latest}
+        restart: unless-stopped
         command: ['--config=/etc/otel-collector-config.yaml']
         volumes:
             - ./otel-collector-config-otel-collector.yaml:/etc/otel-collector-config.yaml
@@ -11,12 +12,15 @@ services:
             - '${OTEL_METRICS_PORT:-8888}:8888' # Prometheus metrics exposed by collector
             - '${OTEL_EXPORTER_PORT:-8889}:8889' # Prometheus exporter
             - '${OTEL_HEALTH_PORT:-13133}:13133' # health_check extension
-        depends_on:
-            - jaeger
-            - prometheus
-            - loki
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:13133/']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
 
 networks:
     devnet:
+        name: devnet

package/overlays/otel-collector/overlay.yml

@@ -19,5 +19,6 @@ ports:
     - 8888
     - 8889
 order: 2
+serviceOrder: 2
 imports:
     - .shared/otel/instrumentation.env

package/overlays/otel-demo-nodejs/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["otel-demo-nodejs"],
-    "_serviceOrder": 3,
     "forwardPorts": [8080],
     "portsAttributes": {
         "8080": {

package/overlays/otel-demo-nodejs/docker-compose.yml

@@ -17,3 +17,4 @@ services:
 
 networks:
     devnet:
+        name: devnet

package/overlays/otel-demo-nodejs/overlay.yml

@@ -12,7 +12,14 @@ suggests:
     - prometheus
     - loki
     - grafana
-conflicts: []
+conflicts:
+    - mysql
+    - redpanda
+    - nodejs
+    - bun
+    - go
+    - java
+    - dotnet
 tags:
     - observability
     - demo
@@ -21,3 +28,4 @@ tags:
 ports:
     - 8080
 order: 4
+serviceOrder: 4

package/overlays/otel-demo-python/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["otel-demo-python"],
-    "_serviceOrder": 3,
     "forwardPorts": [8081],
     "portsAttributes": {
         "8081": {

package/overlays/otel-demo-python/docker-compose.yml

@@ -17,3 +17,4 @@ services:
 
 networks:
     devnet:
+        name: devnet

package/overlays/otel-demo-python/overlay.yml

@@ -12,7 +12,11 @@ suggests:
     - prometheus
     - loki
     - grafana
-conflicts: []
+conflicts:
+    - mongodb
+    - redpanda
+    - go
+    - java
 tags:
     - observability
     - demo
@@ -21,3 +25,4 @@ tags:
 ports:
     - 8081
 order: 4
+serviceOrder: 4

package/overlays/pandoc/README.md

@@ -116,6 +116,16 @@ variables:
     header-includes:
         - |
             \usepackage{etoolbox}
+            \ifdefined\IfFontExistsTF
+            \IfFontExistsTF{Noto Sans Symbols 2}{%
+            \newfontfamily\textfallbackfont{Noto Sans Symbols 2}%
+            \newcommand{\textfallback}[1]{{\textfallbackfont #1}}%
+            }{%
+            \newcommand{\textfallback}[1]{#1}%
+            }
+            \else
+            \newcommand{\textfallback}[1]{#1}%
+            \fi
             \setlength{\tabcolsep}{3pt}
             \renewcommand{\arraystretch}{1.05}
             \AtBeginEnvironment{longtable}{\small}

package/overlays/pandoc/devcontainer.patch.json

@@ -6,11 +6,6 @@
             "apk": "fontconfig noto-fonts-emoji|noto-emoji perl chromium"
         }
     },
-    "customizations": {
-        "vscode": {
-            "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
-        }
-    },
     "remoteEnv": {
         "PUPPETEER_EXECUTABLE_PATH": "/usr/local/bin/chromium-no-sandbox",
         "PUPPETEER_SKIP_DOWNLOAD": "true"

package/overlays/pandoc/overlay.yml

@@ -15,5 +15,7 @@ tags:
     - markdown
     - docs
     - mermaid
+imports:
+    - .shared/vscode/markdown-extensions.json
 ports: []
 order: 25

package/overlays/pandoc/setup.sh

@@ -275,6 +275,16 @@ variables:
   header-includes:
     - |
       \usepackage{etoolbox}
+      \ifdefined\IfFontExistsTF
+      \IfFontExistsTF{Noto Sans Symbols 2}{%
+      \newfontfamily\textfallbackfont{Noto Sans Symbols 2}%
+      \newcommand{\textfallback}[1]{{\textfallbackfont #1}}%
+      }{%
+      \newcommand{\textfallback}[1]{#1}%
+      }
+      \else
+      \newcommand{\textfallback}[1]{#1}%
+      \fi
       \setlength{\tabcolsep}{3pt}
       \renewcommand{\arraystretch}{1.05}
       \AtBeginEnvironment{longtable}{\small}

package/overlays/pgvector/.env.example

@@ -0,0 +1,6 @@
+# pgvector Configuration
+PGVECTOR_VERSION={{cs.PGVECTOR_VERSION}}
+PGVECTOR_DB={{cs.PGVECTOR_DB}}
+PGVECTOR_USER={{cs.PGVECTOR_USER}}
+PGVECTOR_PASSWORD={{cs.PGVECTOR_PASSWORD}}
+PGVECTOR_PORT={{cs.PGVECTOR_PORT}}