container-superposition 0.1.7 → 0.1.8

package/overlays/ollama/overlay.yml

@@ -0,0 +1,22 @@
+id: ollama
+name: Ollama
+description: Local LLM inference server with OpenAI-compatible API
+category: dev
+supports:
+    - compose
+requires: []
+suggests:
+    - codex
+    - claude-code
+    - amp
+conflicts: []
+tags:
+    - dev
+    - ai
+    - llm
+    - inference
+    - ollama
+ports:
+    - 11434
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml

package/overlays/ollama/setup.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# Ollama CLI setup script
+# Installs the Ollama CLI in the devcontainer so developers can manage models
+# and run inference from the terminal, targeting the ollama sidecar service.
+
+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 is set to ${OLLAMA_HOST:-http://ollama:11434} — all commands target the sidecar."
+    exit 0
+fi
+
+echo "📦 Installing Ollama CLI..."
+# Prefer copying the CLI binary from the already-present Ollama sidecar image.
+# Compose-based templates include docker-outside-of-docker, so this avoids
+# re-downloading the multi-GB upstream Linux release archive in normal use.
+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 that the
+    # devcontainer does not need because the sidecar already provides the API.
+    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 "ℹ️  OLLAMA_HOST is set to ${OLLAMA_HOST:-http://ollama:11434} — all commands target the sidecar."

package/overlays/ollama/verify.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Verification script for Ollama overlay
+# Confirms Ollama CLI is installed and sidecar service is running and accessible
+
+set -e
+
+echo "🔍 Verifying Ollama overlay..."
+echo ""
+
+# Check Ollama CLI is installed
+echo "1️⃣ Checking Ollama CLI..."
+if ! command -v ollama &>/dev/null; then
+    echo "   ❌ ollama CLI not found"
+    echo ""
+    echo "❌ Ollama overlay verification failed (ollama CLI is required but not installed)"
+    exit 1
+fi
+echo "   ✅ ollama CLI found: $(ollama --version 2>/dev/null || echo 'version unavailable')"
+
+# Check OLLAMA_HOST is set
+echo ""
+echo "2️⃣ Checking OLLAMA_HOST..."
+if [[ -z "${OLLAMA_HOST:-}" ]]; then
+    echo "   ⚠️  OLLAMA_HOST is not set — CLI will target localhost instead of the sidecar"
+else
+    echo "   ✅ OLLAMA_HOST=${OLLAMA_HOST}"
+fi
+
+# Check if curl is available
+echo ""
+echo "3️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    echo ""
+    echo "❌ Ollama overlay verification failed (curl is required but not installed)"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check Ollama API
+echo ""
+echo "4️⃣ Checking Ollama service..."
+OLLAMA_HOST="${OLLAMA_HOST:-http://ollama:11434}"
+OLLAMA_READY=false
+
+set +e
+for i in {1..20}; do
+    if curl -sf "${OLLAMA_HOST}/api/tags" &> /dev/null; then
+        echo "   ✅ Ollama service is ready"
+        OLLAMA_READY=true
+        break
+    fi
+    sleep 2
+done
+set -e
+
+if [ "$OLLAMA_READY" = false ]; then
+    echo "   ❌ Ollama service not ready after 40 seconds"
+    echo ""
+    echo "❌ Ollama overlay verification failed"
+    exit 1
+fi
+
+# Smoke-test CLI against the sidecar
+echo ""
+echo "5️⃣ Listing available models via CLI..."
+set +e
+ollama list && echo "   ✅ ollama CLI can reach sidecar at ${OLLAMA_HOST}"
+CLI_STATUS=$?
+set -e
+
+if [ $CLI_STATUS -ne 0 ]; then
+    echo "   ⚠️  ollama CLI could not reach sidecar at ${OLLAMA_HOST}"
+fi
+
+# Show available models via REST API
+echo ""
+echo "6️⃣ Listing available models via API..."
+TAGS_JSON=$(curl -sf "${OLLAMA_HOST}/api/tags")
+CURL_STATUS=$?
+if [ $CURL_STATUS -ne 0 ]; then
+    echo "   ⚠️  Skipping model listing: failed to query /api/tags (curl exit code $CURL_STATUS)"
+else
+    MODELS=$(printf '%s\n' "$TAGS_JSON" | grep -o '"name":"[^"]*"' | sed 's/"name":"//;s/"//')
+    if [ -n "$MODELS" ]; then
+        echo "   ✅ Models available:"
+        echo "$MODELS" | while read -r model; do
+            echo "      - $model"
+        done
+    else
+        echo "   ℹ️  No models pulled yet. Use 'ollama pull <model>' to download a model."
+    fi
+fi
+
+echo ""
+echo "✅ Ollama overlay verification complete"
+echo "   API endpoint: ${OLLAMA_HOST}"
+echo "   Docs: https://ollama.com/library"
+

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,23 @@
+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:

package/overlays/open-webui/overlay.yml

@@ -0,0 +1,38 @@
+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
+conflicts: []
+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/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}}