container-superposition 0.1.1 → 0.1.4

package/overlays/grpc-tools/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "protobuf-compiler",
+            "apk": "protobuf"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["zxh404.vscode-proto3", "bufbuild.vscode-buf"]
+        }
+    }
+}

package/overlays/grpc-tools/overlay.yml

@@ -0,0 +1,14 @@
+id: grpc-tools
+name: gRPC Tools
+description: Protocol Buffers compiler, Buf, and grpcurl for gRPC development
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - grpc
+    - protobuf
+    - api
+ports: []

package/overlays/grpc-tools/setup.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# gRPC Tools setup script
+# Installs buf CLI and grpcurl
+
+set -e
+
+echo "🔧 Setting up gRPC Tools..."
+
+# Install buf CLI
+echo "📦 Installing buf CLI..."
+BUF_VERSION="${BUF_VERSION:-1.47.2}"
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64) BUF_ARCH="x86_64" ;;
+    aarch64 | arm64) BUF_ARCH="aarch64" ;;
+    *) echo "   ⚠️  Unsupported architecture: $ARCH, skipping buf installation" ; BUF_ARCH="" ;;
+esac
+
+if [ -n "$BUF_ARCH" ]; then
+    BUF_URL="https://github.com/bufbuild/buf/releases/download/v${BUF_VERSION}/buf-Linux-${BUF_ARCH}"
+    curl -sSL "$BUF_URL" -o /tmp/buf
+    sudo install -m 755 /tmp/buf /usr/local/bin/buf
+    rm -f /tmp/buf
+    echo "   ✅ buf installed: $(buf --version)"
+fi
+
+# Install grpcurl
+echo "📦 Installing grpcurl..."
+GRPCURL_VERSION="${GRPCURL_VERSION:-1.9.2}"
+
+GRPCURL_ARCH="$(uname -m)"
+case "$GRPCURL_ARCH" in
+    x86_64) GRPCURL_ARCH="x86_64" ;;
+    aarch64 | arm64) GRPCURL_ARCH="arm64" ;;
+    *) echo "   ⚠️  Unsupported architecture: $GRPCURL_ARCH, skipping grpcurl installation" ; GRPCURL_ARCH="" ;;
+esac
+
+if [ -n "$GRPCURL_ARCH" ]; then
+    GRPCURL_URL="https://github.com/fullstorydev/grpcurl/releases/download/v${GRPCURL_VERSION}/grpcurl_${GRPCURL_VERSION}_linux_${GRPCURL_ARCH}.tar.gz"
+    curl -sSL "$GRPCURL_URL" | sudo tar -xz -C /usr/local/bin grpcurl
+    echo "   ✅ grpcurl installed: $(grpcurl --version 2>&1 | head -1)"
+fi
+
+echo ""
+echo "✅ gRPC Tools setup complete"
+echo ""
+echo "💡 Quick start:"
+echo "   protoc --version          # Protocol Buffers compiler"
+echo "   buf --version             # Buf CLI (schema management)"
+echo "   grpcurl --version         # gRPC curl"
+echo ""
+echo "📚 Resources:"
+echo "   https://protobuf.dev/       # Protocol Buffers documentation"
+echo "   https://buf.build/docs/     # Buf CLI documentation"
+echo "   https://github.com/fullstorydev/grpcurl  # grpcurl documentation"

package/overlays/grpc-tools/verify.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Verification script for gRPC Tools overlay
+# Confirms protoc, buf, and grpcurl are installed
+
+set -e
+
+echo "🔍 Verifying gRPC Tools overlay..."
+echo ""
+
+ALL_CHECKS_PASSED=true
+
+# Check protoc
+echo "1️⃣ Checking protoc (Protocol Buffers compiler)..."
+if command -v protoc &> /dev/null; then
+    echo "   ✅ protoc found: $(protoc --version)"
+else
+    echo "   ❌ protoc not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check buf
+echo ""
+echo "2️⃣ Checking buf CLI..."
+if command -v buf &> /dev/null; then
+    echo "   ✅ buf found: $(buf --version)"
+else
+    echo "   ❌ buf not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check grpcurl
+echo ""
+echo "3️⃣ Checking grpcurl..."
+if command -v grpcurl &> /dev/null; then
+    echo "   ✅ grpcurl found: $(grpcurl --version 2>&1 | head -1)"
+else
+    echo "   ❌ grpcurl not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+echo ""
+if [ "$ALL_CHECKS_PASSED" = true ]; then
+    echo "✅ gRPC Tools overlay verification complete"
+else
+    echo "❌ Some gRPC tools are missing"
+    exit 1
+fi

package/overlays/jaeger/overlay.yml

@@ -13,7 +13,20 @@ tags:
     - tracing
     - jaeger
 ports:
-    - 16686
-    - 14250
-    - 14268
+    - port: 16686
+      service: jaeger
+      protocol: http
+      description: Jaeger UI
+      path: /
+      onAutoForward: openBrowser
+    - port: 14250
+      service: jaeger
+      protocol: grpc
+      description: Jaeger gRPC receiver
+      onAutoForward: ignore
+    - port: 14268
+      service: jaeger
+      protocol: http
+      description: Jaeger HTTP receiver
+      onAutoForward: ignore
 order: 1

package/overlays/jupyter/.env.example

@@ -0,0 +1,6 @@
+# Jupyter Configuration
+JUPYTER_VERSION=latest
+JUPYTER_ENABLE_LAB=yes
+JUPYTER_TOKEN=
+JUPYTER_PORT=8888
+JUPYTER_NOTEBOOKS_PATH=./notebooks

package/overlays/jupyter/README.md

@@ -0,0 +1,210 @@
+# Jupyter Overlay
+
+Jupyter notebook server for interactive computing and data science.
+
+## Features
+
+- **Jupyter Notebook/Lab** - Interactive computing environment
+- **Python kernel** - Run Python code interactively
+- **Persistent notebooks** - Work saved across container restarts
+- **Volume mounting** - Access notebooks from host filesystem
+- **No authentication** - Pre-configured for development use
+- **Docker Compose service** - Runs as separate container
+
+## How It Works
+
+This overlay adds Jupyter as a Docker Compose service running in its own container. Jupyter is accessible from your development container and your browser via port 8888.
+
+**Dependencies:**
+
+- `python` (required) - Python runtime for notebooks
+
+**Architecture:**
+
+- Jupyter service runs on port 8888
+- Notebooks stored in Docker volume (`jupyter-data`)
+- Optional local directory mounting for notebooks
+- JupyterLab interface enabled by default
+
+## Configuration
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy it to `.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Default values (.env.example):**
+
+```bash
+# Jupyter Configuration
+JUPYTER_VERSION=latest
+JUPYTER_ENABLE_LAB=yes
+JUPYTER_TOKEN=
+JUPYTER_PORT=8888
+JUPYTER_NOTEBOOKS_PATH=./notebooks
+```
+
+### Notebook Directory
+
+By default, notebooks can be created in the Jupyter container. To use notebooks from your host:
+
+1. Create a `notebooks` directory in your project root
+2. Notebooks in this directory will be available at `/home/jovyan/notebooks` in Jupyter
+
+### Authentication
+
+By default, authentication is disabled for local development:
+
+- No token required
+- No password required
+
+For production or shared environments, set `JUPYTER_TOKEN`:
+
+```bash
+JUPYTER_TOKEN=your-secure-token
+```
+
+### Port Configuration
+
+The default port (8888) can be changed via the `--port-offset` option:
+
+```bash
+npm run init -- --port-offset 100 --stack compose --language python,jupyter
+# Jupyter will be on port 8988
+```
+
+## Common Commands
+
+### Accessing Jupyter
+
+```bash
+# Open in browser
+http://localhost:8888
+
+# Or use container hostname from dev container
+curl http://jupyter:8888
+```
+
+### Notebook Management
+
+Jupyter provides a web interface for all notebook operations:
+
+- Create new notebooks
+- Upload existing notebooks
+- Download notebooks
+- Organize in folders
+- Run code cells
+- Export to various formats (HTML, PDF, etc.)
+
+### Using Python in Notebooks
+
+```python
+# Install packages
+!pip install pandas numpy matplotlib seaborn
+
+# Import and use
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Your analysis code
+df = pd.read_csv('data.csv')
+df.head()
+```
+
+### JupyterLab Features
+
+JupyterLab is enabled by default and provides:
+
+- Multiple tabs
+- File browser
+- Terminal
+- Text editor
+- Markdown preview
+- Extension manager
+
+## Use Cases
+
+- **Data analysis** - Explore and visualize datasets
+- **Machine learning** - Develop and train models
+- **Scientific computing** - Mathematical and statistical analysis
+- **Documentation** - Create executable documentation
+- **Teaching** - Interactive tutorials and examples
+- **Prototyping** - Quick experimentation with code
+
+**Integrates well with:**
+
+- `python` - Python runtime (required)
+- `postgres` - Database for data analysis
+- `duckdb` - Analytics database
+- `redis` - Caching and data structures
+
+## Available Images
+
+Jupyter provides different base images:
+
+- `jupyter/minimal-notebook` - Minimal Jupyter with Python (default)
+- `jupyter/scipy-notebook` - Scientific Python stack
+- `jupyter/datascience-notebook` - Julia, Python, R
+- `jupyter/tensorflow-notebook` - TensorFlow and Keras
+- `jupyter/pyspark-notebook` - PySpark
+
+Change via `JUPYTER_VERSION`:
+
+```bash
+JUPYTER_VERSION=scipy-notebook
+```
+
+## Troubleshooting
+
+### Jupyter Not Starting
+
+Check service logs:
+
+```bash
+docker-compose logs jupyter
+```
+
+### Port Already in Use
+
+Change the port in `.env`:
+
+```bash
+JUPYTER_PORT=8889
+```
+
+Or use port offset when generating.
+
+### Notebooks Not Persisting
+
+Ensure you're saving notebooks to the mounted volume or directory:
+
+- `/home/jovyan/work` - Persistent volume
+- `/home/jovyan/notebooks` - Mounted from host
+
+### Package Installation
+
+Packages installed with `!pip install` are lost on container restart. To persist:
+
+1. Create a `requirements.txt` in your notebooks directory
+2. Install in a notebook: `!pip install -r /home/jovyan/notebooks/requirements.txt`
+
+Or extend the Jupyter image with a custom Dockerfile.
+
+## References
+
+- [Jupyter Documentation](https://jupyter.org/documentation)
+- [JupyterLab Documentation](https://jupyterlab.readthedocs.io/)
+- [Jupyter Docker Stacks](https://jupyter-docker-stacks.readthedocs.io/)
+- [Jupyter Notebook Basics](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html)
+
+**Related Overlays:**
+
+- `python` - Python runtime (required)
+- `postgres` - Database for analysis
+- `duckdb` - Analytics database
+- `redis` - Data structures

package/overlays/jupyter/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["jupyter"],
+    "forwardPorts": [8888],
+    "portsAttributes": {
+        "8888": {
+            "label": "Jupyter Notebook",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "JUPYTER_URL": "http://jupyter:8888"
+    }
+}

package/overlays/jupyter/docker-compose.yml

@@ -0,0 +1,23 @@
+version: '3.8'
+
+services:
+    jupyter:
+        image: jupyter/minimal-notebook:${JUPYTER_VERSION:-latest}
+        restart: unless-stopped
+        volumes:
+            - jupyter-data:/home/jovyan/work
+            - ${JUPYTER_NOTEBOOKS_PATH:-./notebooks}:/home/jovyan/notebooks
+        environment:
+            JUPYTER_ENABLE_LAB: ${JUPYTER_ENABLE_LAB:-yes}
+            JUPYTER_TOKEN: ${JUPYTER_TOKEN:-}
+        ports:
+            - '${JUPYTER_PORT:-8888}:8888'
+        networks:
+            - devnet
+        command: start-notebook.sh --NotebookApp.token='' --NotebookApp.password=''
+
+volumes:
+    jupyter-data:
+
+networks:
+    devnet:

package/overlays/jupyter/overlay.yml

@@ -0,0 +1,18 @@
+id: jupyter
+name: Jupyter
+description: Jupyter notebook server for interactive computing and data science
+category: language
+supports:
+    - compose
+requires:
+    - python
+suggests: []
+conflicts: []
+tags:
+    - language
+    - jupyter
+    - python
+    - notebook
+    - data-science
+ports:
+    - 8888

package/overlays/jupyter/verify.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Verification script for Jupyter overlay
+# Confirms Jupyter is running
+
+set -e
+
+echo "🔍 Verifying Jupyter overlay..."
+echo ""
+
+# Check if Jupyter service is running
+echo "1️⃣ Checking Jupyter service..."
+if command -v curl &> /dev/null; then
+    # Wait up to 30 seconds for Jupyter to be ready
+    JUPYTER_READY=false
+    for i in {1..30}; do
+        if curl -s http://jupyter:8888 &> /dev/null; then
+            echo "   ✅ Jupyter service is ready"
+            JUPYTER_READY=true
+            break
+        fi
+        sleep 1
+    done
+
+    if [ "$JUPYTER_READY" = false ]; then
+        echo "   ❌ Jupyter service not ready after 30 seconds"
+        exit 1
+    fi
+else
+    echo "   ⚠️  curl not found, skipping service check"
+fi
+
+echo ""
+echo "✅ Jupyter overlay verification complete"
+echo ""
+echo "ℹ️  Access Jupyter at http://localhost:8888"

package/overlays/keycloak/.env.example

@@ -0,0 +1,5 @@
+# Keycloak Configuration
+KEYCLOAK_VERSION=26.0
+KEYCLOAK_PORT=8180
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=admin