container-superposition 0.1.7 → 0.1.9

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}"

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

package/overlays/go/overlay.yml

@@ -5,7 +5,12 @@ category: language
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - mysql
+    - redpanda
+    - mongodb
+    - otel-demo-nodejs
+    - otel-demo-python
 tags:
     - language
     - go

package/overlays/grafana/devcontainer.patch.json

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

package/overlays/grafana/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     grafana:
         image: grafana/grafana:${GRAFANA_VERSION:-latest}
+        restart: unless-stopped
         environment:
             - GF_SECURITY_ADMIN_USER=${GRAFANA_ADMIN_USER:-admin}
             - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:-admin}
@@ -15,13 +16,18 @@ services:
             - '${GRAFANA_PORT:-3000}:3000'
         depends_on:
             - prometheus
-            - loki
-            - jaeger
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/api/health']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 20s
 
 volumes:
     grafana_data:
 
 networks:
     devnet:
+        name: devnet

package/overlays/grafana/overlay.yml

@@ -11,7 +11,11 @@ suggests:
     - jaeger
     - tempo
     - promtail
-conflicts: []
+conflicts:
+    - open-webui
+    - nodejs
+    - bun
+    - rust
 tags:
     - observability
     - ui
@@ -24,3 +28,4 @@ ports:
       path: /
       onAutoForward: openBrowser
 order: 3
+serviceOrder: 3

package/overlays/jaeger/.env.example

@@ -5,3 +5,14 @@ JAEGER_VERSION=latest
 JAEGER_UI_PORT=16686
 JAEGER_OTLP_GRPC_PORT=4317
 JAEGER_OTLP_HTTP_PORT=4318
+
+# OpenTelemetry SDK defaults for apps running in the devcontainer
+# These are pre-set in the devcontainer via remoteEnv; see devcontainer.patch.json
+# Customize after generation by editing remoteEnv in .devcontainer/devcontainer.json
+OTEL_SERVICE_NAME=my-service
+OTEL_SERVICE_VERSION=0.1.0
+OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp

package/overlays/jaeger/README.md

@@ -33,10 +33,35 @@ graph TD
 ### Ports
 
 - `16686` - Jaeger UI (web interface)
-- `4317` - OTLP gRPC receiver (when used without otel-collector)
-- `4318` - OTLP HTTP receiver (when used without otel-collector)
+- `4317` - OTLP gRPC receiver (internal Docker network only; not published to host)
+- `4318` - OTLP HTTP receiver (internal Docker network only; not published to host)
 
-⚠️ **Note:** When using with **otel-collector**, OTLP ports (4317/4318) are not exposed to avoid conflicts. Send telemetry to otel-collector, which forwards to Jaeger.
+⚠️ **Note:** When using with **otel-collector**, send telemetry to `otel-collector:4317` instead — the collector forwards to Jaeger internally.
+
+### Pre-configured OpenTelemetry Environment
+
+The devcontainer is pre-configured with OTEL environment variables so that any properly-instrumented app running inside the devcontainer sends traces to Jaeger automatically:
+
+| Variable                      | Default value                        | Purpose                                |
+| ----------------------------- | ------------------------------------ | -------------------------------------- |
+| `OTEL_SERVICE_NAME`           | `my-service`                         | Service name shown in Jaeger UI        |
+| `OTEL_SERVICE_VERSION`        | `0.1.0`                              | Service version in resource attributes |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://jaeger:4317`                 | OTLP gRPC endpoint (Docker network)    |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`                               | Transport protocol                     |
+| `OTEL_RESOURCE_ATTRIBUTES`    | `deployment.environment=development` | Additional resource metadata           |
+| `OTEL_TRACES_SAMPLER`         | `always_on`                          | Capture every trace in development     |
+| `OTEL_TRACES_EXPORTER`        | `otlp`                               | Export traces via OTLP                 |
+
+These values are set via `remoteEnv` in `devcontainer.json`. To override them for your project, edit `.devcontainer/devcontainer.json` after generation and update the `remoteEnv` block, then rebuild the container:
+
+```json
+"remoteEnv": {
+    "OTEL_SERVICE_NAME": "my-app",
+    "OTEL_SERVICE_VERSION": "1.0.0"
+}
+```
+
+When the **otel-collector** overlay is also selected, `OTEL_EXPORTER_OTLP_ENDPOINT` is automatically set to `http://otel-collector:4317` (otel-collector overlay is applied after jaeger and overrides this value).
 
 ### Environment Variables
 
@@ -74,12 +99,16 @@ container-superposition --port-offset 100
 
 ## Accessing Jaeger UI
 
-Once your devcontainer starts, open your browser to:
+Once your devcontainer starts, VS Code automatically opens <http://localhost:16686> in your browser (via `onAutoForward: openBrowser`). You can also open it manually:
 
 ```
 http://localhost:16686
 ```
 
+Port `16686` is published by the `jaeger` Docker Compose service to your local machine, so it is accessible both from the host and from within the devcontainer via `http://jaeger:16686`.
+
+The `devcontainer` service has `depends_on: jaeger: condition: service_healthy`, so Docker Compose waits for Jaeger to pass its healthcheck before starting the devcontainer. This ensures the UI is reachable by the time VS Code opens the browser.
+
 ### UI Features
 
 **1. Search Traces**

package/overlays/jaeger/devcontainer.patch.json

@@ -1,12 +1,20 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["jaeger"],
-    "_serviceOrder": 1,
     "forwardPorts": [16686],
     "portsAttributes": {
         "16686": {
             "label": "Jaeger UI",
             "onAutoForward": "openBrowser"
         }
+    },
+    "remoteEnv": {
+        "OTEL_SERVICE_NAME": "my-service",
+        "OTEL_SERVICE_VERSION": "0.1.0",
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://jaeger:4317",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
+        "OTEL_RESOURCE_ATTRIBUTES": "deployment.environment=development",
+        "OTEL_TRACES_SAMPLER": "always_on",
+        "OTEL_TRACES_EXPORTER": "otlp"
     }
 }

package/overlays/jaeger/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     jaeger:
         image: jaegertracing/all-in-one:${JAEGER_VERSION:-latest}
+        restart: unless-stopped
         environment:
             - COLLECTOR_OTLP_ENABLED=true
         ports:
@@ -12,6 +13,22 @@ services:
             # Apps should send telemetry to otel-collector, which forwards to Jaeger if both are used
         networks:
             - devnet
+        healthcheck:
+            test:
+                [
+                    'CMD-SHELL',
+                    'wget --no-verbose --tries=1 --spider http://localhost:14269/ || exit 1',
+                ]
+            interval: 5s
+            timeout: 5s
+            retries: 10
+            start_period: 10s
+
+    devcontainer:
+        depends_on:
+            jaeger:
+                condition: service_healthy
 
 networks:
     devnet:
+        name: devnet

package/overlays/jaeger/overlay.yml

@@ -19,16 +19,5 @@ ports:
       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
-imports:
-    - .shared/otel/instrumentation.env
+serviceOrder: 1

package/overlays/java/overlay.yml

@@ -5,7 +5,12 @@ category: language
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - mysql
+    - redpanda
+    - mongodb
+    - otel-demo-nodejs
+    - otel-demo-python
 tags:
     - language
     - java

package/overlays/jupyter/docker-compose.yml

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

package/overlays/jupyter/overlay.yml

@@ -8,6 +8,7 @@ requires:
     - python
 suggests: []
 conflicts: []
+serviceOrder: 3
 tags:
     - language
     - jupyter