container-superposition 0.1.6 → 0.1.8

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

@@ -5,6 +5,5 @@
             "apt": "curl",
             "apk": "curl"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-openapi-tools.sh"
+    }
 }

package/overlays/openapi-tools/setup.sh

@@ -3,19 +3,20 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "🔧 Setting up OpenAPI Tools..."
 
 # Install OpenAPI tools globally via npm
 echo "📦 Installing OpenAPI tools..."
 
-# Install swagger-cli (OpenAPI validation)
-npm install -g @apidevtools/swagger-cli || echo "⚠️ swagger-cli already installed or failed"
-
-# Install spectral (OpenAPI linting)
-npm install -g @stoplight/spectral-cli || echo "⚠️ spectral already installed or failed"
-
-# Install redocly CLI (documentation and bundling)
-npm install -g @redocly/cli || echo "⚠️ redocly already installed or failed"
+# Wrap each install in run_spinner to suppress noisy deprecation warnings
+run_spinner "swagger-cli"  npm install -g @apidevtools/swagger-cli
+run_spinner "spectral"     npm install -g @stoplight/spectral-cli
+run_spinner "redocly"      npm install -g @redocly/cli
 
 # Verify installations
 echo ""

package/overlays/opencode/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing opencode AI coding agent..."
 
 # Install opencode-ai globally

package/overlays/otel-collector/overlay.yml

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

package/overlays/otel-collector/setup.sh

@@ -5,23 +5,10 @@ set -e
 
 echo "🔧 Configuring OpenTelemetry Collector trace backend..."
 
-# Determine workspace root dynamically
-WORKSPACE_ROOT="${LOCAL_WORKSPACE_FOLDER:-$PWD}"
-
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ]; then
-    if [ -d "/workspaces" ]; then
-        FIRST_WORKSPACE_DIR="$(find /workspaces -maxdepth 1 -mindepth 1 -type d 2>/dev/null | head -n 1)"
-        if [ -n "$FIRST_WORKSPACE_DIR" ] && [ -d "$FIRST_WORKSPACE_DIR/.devcontainer" ]; then
-            WORKSPACE_ROOT="$FIRST_WORKSPACE_DIR"
-        fi
-    fi
-fi
-
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ] && [ -d "/workspace/.devcontainer" ]; then
-    WORKSPACE_ROOT="/workspace"
-fi
+# Resolve the .devcontainer directory relative to this script.
+DEVCONTAINER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)"
 
-OTEL_CONFIG="$WORKSPACE_ROOT/.devcontainer/otel-collector-config-otel-collector.yaml"
+OTEL_CONFIG="$DEVCONTAINER_DIR/otel-collector-config-otel-collector.yaml"
 
 if [ ! -f "$OTEL_CONFIG" ]; then
     echo "⚠️ OTel Collector config not found"

package/overlays/otel-demo-nodejs/verify.sh

@@ -6,19 +6,18 @@ echo "🔍 Verifying OTel Demo (Node.js) installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if service is running
-if docker ps --format '{{.Names}}' | grep -q otel-demo-nodejs; then
-    echo "✓ OTel Demo (Node.js) service is running"
+# Check if HTTP health endpoint is accessible (primary health signal).
+# docker ps is informational only — not reliably accessible in all devcontainers.
+if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-nodejs:8080/health 2>/dev/null | grep -q "200"; then
+    echo "✓ Demo app HTTP endpoint is accessible"
 else
-    echo "✗ OTel Demo (Node.js) service is not running"
+    echo "✗ Demo app HTTP endpoint not responding (http://otel-demo-nodejs:8080/health)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if HTTP endpoint is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-nodejs:8080/health 2>/dev/null | grep -q "200"; then
-    echo "✓ Demo app HTTP endpoint is accessible"
-else
-    echo "⚠️ Demo app HTTP endpoint not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q otel-demo-nodejs; then
+    echo "✓ OTel Demo (Node.js) container visible in docker ps"
 fi
 
 # Final result

package/overlays/otel-demo-python/verify.sh

@@ -6,19 +6,25 @@ echo "🔍 Verifying OTel Demo (Python) installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if service is running
-if docker ps --format '{{.Names}}' | grep -q otel-demo-python; then
-    echo "✓ OTel Demo (Python) service is running"
-else
-    echo "✗ OTel Demo (Python) service is not running"
+# Wait for demo app HTTP health endpoint (primary health signal).
+# docker ps is informational only — not reliably accessible in all devcontainers.
+APP_READY=false
+for i in {1..40}; do
+    if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-python:8081/health 2>/dev/null | grep -q "200"; then
+        echo "✓ Demo app HTTP endpoint is accessible"
+        APP_READY=true
+        break
+    fi
+    sleep 3
+done
+if [ "$APP_READY" = false ]; then
+    echo "✗ Demo app HTTP endpoint not responding after 120 s (http://otel-demo-python:8081/health)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if HTTP endpoint is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-python:8081/health 2>/dev/null | grep -q "200"; then
-    echo "✓ Demo app HTTP endpoint is accessible"
-else
-    echo "⚠️ Demo app HTTP endpoint not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q otel-demo-python; then
+    echo "✓ OTel Demo (Python) container visible in docker ps"
 fi
 
 # Final result

package/overlays/pandoc/README.md

@@ -6,9 +6,10 @@ Adds a complete Markdown → PDF pipeline to your devcontainer, powered by Pando
 
 - **Pandoc 3.x** — Latest release binary from GitHub (not the outdated apt version)
 - **TeX Live / XeLaTeX** — Full Unicode-capable PDF engine (`texlive-xetex`, `texlive-fonts-extra`, `texlive-latex-extra`)
-- **Quality fonts** — Carlito (body), JetBrains Mono (code), Noto Sans Symbols 2 (Unicode fallback) via system packages
+- **Quality fonts** — Carlito (body), JetBrains Mono (code), Noto Sans Symbols 2 (Unicode fallback), and Noto Color Emoji via system packages
     - Uses the `cross-distro-packages` feature with fallback package names for Carlito (`fonts-carlito|fonts-crosextra-carlito`)
 - **`diagram.lua`** — Lua filter from [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram) for rendering code-block diagrams
+- **`emoji-fallback.lua`** — Built-in Lua filter that rewrites unsupported emoji and flag glyphs to plain-text placeholders for reliable XeLaTeX PDF builds
 - **Mermaid CLI (`mmdc`)** — Installed when the `nodejs` overlay is present; skipped gracefully otherwise
 - **`~/.pandoc/pandoc.yaml`** — Ready-to-use defaults file (XeLaTeX engine, font settings, table tweaks)
 - **VS Code Extensions:** Markdown All in One (`yzhang.markdown-all-in-one`), markdownlint (`DavidAnson.vscode-markdownlint`)
@@ -30,13 +31,17 @@ Markdown
 
 Font discovery is updated with `fc-cache -fv` after installation so XeLaTeX can locate the apt-installed fonts.
 
+The generated defaults also enable an emoji fallback filter for LaTeX output. The overlay now installs Noto Color Emoji as well, which may improve glyph coverage in some contexts, but the fallback filter remains enabled because XeLaTeX still is not reliable for full emoji and flag rendering. The filter converts unsupported glyphs such as `🇵🇹` to `[PT]` and generic emoji such as `😀` to `[emoji]` before XeLaTeX runs, preventing the `Unicode character ... not set up for use with LaTeX` failure.
+
+The setup script also installs a `/usr/local/bin/pandoc` wrapper that automatically applies `~/.pandoc/pandoc.yaml` unless you explicitly pass `-d` or `--defaults`. That makes plain commands like `pandoc doc.md -o doc.pdf` use the overlay defaults.
+
 ## Common Commands
 
 ### Basic PDF export
 
 ```bash
-# Use the default pandoc.yaml
-pandoc -d ~/.pandoc/pandoc.yaml document.md -o document.pdf
+# Uses the installed wrapper, which applies ~/.pandoc/pandoc.yaml automatically
+pandoc document.md -o document.pdf
 
 # Override the output font on the fly
 pandoc -d ~/.pandoc/pandoc.yaml -V mainfont="DejaVu Serif" document.md -o document.pdf
@@ -45,8 +50,7 @@ pandoc -d ~/.pandoc/pandoc.yaml -V mainfont="DejaVu Serif" document.md -o docume
 ### PDF with Mermaid diagrams (requires nodejs overlay)
 
 ```bash
-pandoc -d ~/.pandoc/pandoc.yaml \
-  --lua-filter ~/.pandoc/filters/diagram.lua \
+pandoc --lua-filter ~/.pandoc/filters/diagram.lua \
   document.md -o document.pdf
 ```
 
@@ -95,6 +99,8 @@ The setup script writes a defaults file with proven settings:
 
 ```yaml
 pdf-engine: xelatex
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
 
 variables:
     mainfont: 'Carlito'
@@ -129,8 +135,9 @@ variables:
 toc: true
 toc-depth: 3
 number-sections: true
-lua-filter:
-    - ~/.pandoc/filters/diagram.lua
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
+    - /home/your-user/.pandoc/filters/diagram.lua
 ```
 
 Then build with:
@@ -154,21 +161,21 @@ number-sections: true
 Uncomment in `~/.pandoc/pandoc.yaml`:
 
 ```yaml
-lua-filter:
-    - ~/.pandoc/filters/diagram.lua
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
+    - /home/your-user/.pandoc/filters/diagram.lua
 ```
 
 ## Unicode and Emoji
 
-XeLaTeX handles Unicode well with the Noto and Carlito fonts, but emoji (🎉 🚀) require a colour emoji font (e.g. `fonts-noto-color-emoji`) which is not installed by default due to size. For documents with emoji, either:
+XeLaTeX handles normal Unicode text well with the bundled fonts. The overlay now also installs Noto Color Emoji, which can help with emoji coverage, but the failure mode in PDF builds is still usually emoji or regional-indicator flags, for example `🇵🇹`, which XeLaTeX may reject before font fallback can help.
 
-1. Replace emoji with text equivalents before generating the PDF:
+The overlay now enables `~/.pandoc/filters/emoji-fallback.lua` by default for LaTeX output. It keeps normal Unicode text intact and rewrites unsupported emoji to plain-text placeholders:
 
-    ```bash
-    sed 's/🎉/[celebration]/g; s/🚀/[rocket]/g' doc.md | pandoc -d ~/.pandoc/pandoc.yaml -o doc.pdf
-    ```
+- `🇵🇹 Porto` becomes `[PT] Porto`
+- `😀` becomes `[emoji]`
 
-2. Install `fonts-noto-color-emoji` and add `\setmainfont{Noto Color Emoji}` for the emoji font fallback in your `header-includes`.
+If you want to experiment with more native emoji rendering, keep the installed emoji font and override the default Pandoc/LaTeX settings in a project-local `pandoc.yaml`, but the placeholder filter is still the reliable default for PDF generation.
 
 ## Use Cases
 

package/overlays/pandoc/devcontainer.patch.json

@@ -2,13 +2,17 @@
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "features": {
         "./features/cross-distro-packages": {
-            "apt": "texlive-xetex texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra texlive-lang-european fonts-carlito|fonts-crosextra-carlito fonts-noto fonts-noto-extra fonts-noto-mono fonts-jetbrains-mono fontconfig perl chromium",
-            "apk": "fontconfig perl chromium"
+            "apt": "texlive-xetex texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra texlive-lang-european lmodern fonts-carlito|fonts-crosextra-carlito fonts-noto fonts-noto-extra fonts-noto-mono fonts-jetbrains-mono fonts-noto-color-emoji fontconfig librsvg2-bin perl chromium",
+            "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"
     }
 }