container-superposition 0.1.7 → 0.1.9

package/overlays/qdrant/README.md

@@ -0,0 +1,216 @@
+# Qdrant Overlay
+
+Adds [Qdrant](https://qdrant.tech) as a Docker Compose service, providing a high-performance vector database for similarity search and embedding-based retrieval.
+
+## Features
+
+- **Qdrant vector database** — Store, index, and query high-dimensional embedding vectors at scale
+- **REST API on port 6333** — Full-featured HTTP API for collections, points, and search
+- **gRPC API on port 6334** — High-throughput binary protocol for production workloads
+- **Persistent storage** — Named Docker volume preserves data across container rebuilds
+- **Pre-configured `QDRANT_URL`** — Container environment variable set for easy SDK usage
+- **Health check** — Compose readiness check against `/readyz` before dependent services start
+
+## How It Works
+
+Qdrant runs as a Docker Compose service alongside your devcontainer. The devcontainer connects to it using the hostname `qdrant` on port `6333` (REST) or `6334` (gRPC).
+
+**Service configuration:**
+
+- Image: `qdrant/qdrant:latest`
+- Network: `devnet` (shared with the dev container)
+- Ports: `6333` (REST API), `6334` (gRPC)
+- Volume: `qdrant-data` for persistent vector storage
+
+The following environment variables are pre-set in the devcontainer:
+
+| Variable      | Value                |
+| ------------- | -------------------- |
+| `QDRANT_HOST` | `qdrant`             |
+| `QDRANT_PORT` | `6333`               |
+| `QDRANT_URL`  | `http://qdrant:6333` |
+
+## Common Commands
+
+### REST API
+
+```bash
+# Health check
+curl http://qdrant:6333/healthz
+
+# Create a collection
+curl -X PUT http://qdrant:6333/collections/my_collection \
+  -H "Content-Type: application/json" \
+  -d '{
+    "vectors": {
+      "size": 1536,
+      "distance": "Cosine"
+    }
+  }'
+
+# Insert points
+curl -X PUT http://qdrant:6333/collections/my_collection/points \
+  -H "Content-Type: application/json" \
+  -d '{
+    "points": [
+      {
+        "id": 1,
+        "vector": [0.1, 0.2, 0.3],
+        "payload": {"text": "example document"}
+      }
+    ]
+  }'
+
+# Search for similar vectors
+curl -X POST http://qdrant:6333/collections/my_collection/points/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "vector": [0.1, 0.2, 0.3],
+    "limit": 5
+  }'
+
+# List collections
+curl http://qdrant:6333/collections
+```
+
+### Python SDK
+
+```bash
+pip install qdrant-client
+
+python - <<'EOF'
+from qdrant_client import QdrantClient
+from qdrant_client.models import Distance, VectorParams, PointStruct
+
+client = QdrantClient(url="http://qdrant:6333")
+
+# Create collection
+client.create_collection(
+    collection_name="my_collection",
+    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
+)
+
+# Insert vectors
+client.upsert(
+    collection_name="my_collection",
+    points=[
+        PointStruct(id=1, vector=[0.1] * 1536, payload={"text": "hello"})
+    ],
+)
+
+# Search
+results = client.search(
+    collection_name="my_collection",
+    query_vector=[0.1] * 1536,
+    limit=5,
+)
+print(results)
+EOF
+```
+
+### Node.js SDK
+
+```bash
+npm install @qdrant/js-client-rest
+
+node - <<'EOF'
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+const client = new QdrantClient({ url: "http://qdrant:6333" });
+
+await client.createCollection("my_collection", {
+  vectors: { size: 1536, distance: "Cosine" },
+});
+
+const results = await client.search("my_collection", {
+  vector: Array(1536).fill(0.1),
+  limit: 5,
+});
+console.log(results);
+EOF
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable           | Default  | Description             |
+| ------------------ | -------- | ----------------------- |
+| `QDRANT_VERSION`   | `latest` | Qdrant Docker image tag |
+| `QDRANT_PORT`      | `6333`   | Host port for REST API  |
+| `QDRANT_GRPC_PORT` | `6334`   | Host port for gRPC API  |
+
+### Port Customization
+
+```bash
+# .devcontainer/.env
+QDRANT_PORT=6335
+QDRANT_GRPC_PORT=6336
+```
+
+## Use Cases
+
+- **RAG (Retrieval-Augmented Generation)** — Store embeddings for document chunks; retrieve context for LLM queries
+- **Semantic search** — Find similar documents, images, or code snippets by embedding similarity
+- **Recommendation systems** — Surface similar items based on learned embeddings
+- **Anomaly detection** — Identify outliers in high-dimensional embedding spaces
+- **Local AI pipelines** — Pair with `ollama` for fully offline embedding + retrieval workflows
+
+**Integrates well with:**
+
+- `ollama` — Generate embeddings locally (`ollama pull nomic-embed-text`)
+- `python` — LangChain, LlamaIndex, or raw `qdrant-client` integrations
+- `nodejs` — `@qdrant/js-client-rest` for JavaScript embeddings workflows
+
+## Troubleshooting
+
+### Service Not Ready
+
+```bash
+# Check service status
+docker compose ps qdrant
+
+# View Qdrant logs
+docker compose logs qdrant
+
+# Test health endpoint
+curl http://qdrant:6333/healthz
+```
+
+### Port Conflict
+
+If ports 6333 or 6334 are already in use:
+
+```bash
+# .devcontainer/.env
+QDRANT_PORT=6335
+QDRANT_GRPC_PORT=6336
+```
+
+### Data Persistence
+
+Qdrant data is stored in the `qdrant-data` named Docker volume. It persists across container rebuilds but is scoped to the Docker environment:
+
+```bash
+# Inspect the volume
+docker volume inspect qdrant-data
+
+# Backup data
+docker run --rm -v qdrant-data:/data -v $(pwd):/backup alpine \
+  tar czf /backup/qdrant-backup.tar.gz /data
+```
+
+## References
+
+- [Qdrant Documentation](https://qdrant.tech/documentation/)
+- [Qdrant REST API Reference](https://qdrant.github.io/qdrant/redoc/index.html)
+- [Qdrant Docker Hub](https://hub.docker.com/r/qdrant/qdrant)
+- [Python SDK](https://python-client.qdrant.tech/)
+- [JavaScript SDK](https://github.com/qdrant/qdrant-js)
+
+**Related Overlays:**
+
+- [`pgvector`](../pgvector/README.md) — PostgreSQL-native vector storage (alternative; conflicts with `postgres`)
+- [`ollama`](../ollama/README.md) — Local LLM and embedding generation
+- [`python`](../python/README.md) — Python development environment
+- [`nodejs`](../nodejs/README.md) — Node.js development environment

package/overlays/qdrant/devcontainer.patch.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["qdrant"],
+    "forwardPorts": [6333, 6334],
+    "portsAttributes": {
+        "6333": {
+            "label": "Qdrant REST API",
+            "onAutoForward": "notify"
+        },
+        "6334": {
+            "label": "Qdrant gRPC",
+            "onAutoForward": "ignore"
+        }
+    },
+    "containerEnv": {
+        "QDRANT_HOST": "qdrant",
+        "QDRANT_PORT": "6333",
+        "QDRANT_URL": "http://qdrant:6333"
+    }
+}

package/overlays/qdrant/docker-compose.yml

@@ -0,0 +1,26 @@
+version: '3.8'
+
+services:
+    qdrant:
+        image: qdrant/qdrant:${QDRANT_VERSION:-{{cs.QDRANT_VERSION}}}
+        restart: unless-stopped
+        volumes:
+            - qdrant-data:/qdrant/storage
+        ports:
+            - '${QDRANT_PORT:-{{cs.QDRANT_PORT}}}:6333'
+            - '${QDRANT_GRPC_PORT:-{{cs.QDRANT_GRPC_PORT}}}:6334'
+        networks:
+            - devnet
+        healthcheck:
+            test: ['CMD-SHELL', 'curl -sf http://localhost:6333/readyz || exit 1']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
+
+volumes:
+    qdrant-data:
+
+networks:
+    devnet:
+        name: devnet

package/overlays/qdrant/overlay.yml

@@ -0,0 +1,44 @@
+id: qdrant
+name: Qdrant
+description: High-performance vector database for similarity search and embeddings
+category: database
+supports:
+    - compose
+requires: []
+suggests:
+    - ollama
+    - python
+    - nodejs
+    - prometheus
+    - grafana
+    - otel-collector
+conflicts: []
+serviceOrder: 0
+tags:
+    - database
+    - vector
+    - embeddings
+    - search
+    - qdrant
+ports:
+    - port: 6333
+      service: qdrant
+      protocol: http
+      description: Qdrant REST API
+      onAutoForward: notify
+      connectionStringTemplate: 'http://{host}:{port}'
+    - port: 6334
+      service: qdrant
+      protocol: grpc
+      description: Qdrant gRPC API
+      onAutoForward: ignore
+parameters:
+    QDRANT_VERSION:
+        description: Qdrant Docker image tag
+        default: v1.9.0
+    QDRANT_PORT:
+        description: Host port mapped to Qdrant REST API (6333 inside container)
+        default: '6333'
+    QDRANT_GRPC_PORT:
+        description: Host port mapped to Qdrant gRPC API (6334 inside container)
+        default: '6334'

package/overlays/rabbitmq/docker-compose.yml

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

package/overlays/rabbitmq/overlay.yml

@@ -1,12 +1,35 @@
 id: rabbitmq
 name: RabbitMQ
 description: Message broker with AMQP protocol and management UI
-category: database
+category: messaging
 supports:
     - compose
 requires: []
-suggests: []
+suggests:
+    - prometheus
+    - grafana
 conflicts: []
+serviceOrder: 0
+parameters:
+    RABBITMQ_VERSION:
+        description: RabbitMQ image version tag (management variant used)
+        default: 3-management
+    RABBITMQ_PORT:
+        description: Host port mapped to AMQP (5672 inside container)
+        default: '5672'
+    RABBITMQ_MANAGEMENT_PORT:
+        description: Host port mapped to management UI (15672 inside container)
+        default: '15672'
+    RABBITMQ_USER:
+        description: RabbitMQ default username
+        default: guest
+    RABBITMQ_PASSWORD:
+        description: RabbitMQ default password
+        default: guest
+        sensitive: true
+    RABBITMQ_VHOST:
+        description: RabbitMQ default virtual host
+        default: /
 tags:
     - database
     - messaging

package/overlays/redis/docker-compose.yml

@@ -13,9 +13,16 @@ services:
             REDIS_PASSWORD: ${REDIS_PASSWORD:-}
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'redis-cli', 'ping']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
 
 volumes:
     redis-data:
 
 networks:
     devnet:
+        name: devnet

package/overlays/redis/overlay.yml

@@ -5,8 +5,22 @@ category: database
 supports:
     - compose
 requires: []
-suggests: []
+suggests:
+    - prometheus
+    - grafana
 conflicts: []
+serviceOrder: 0
+parameters:
+    REDIS_VERSION:
+        description: Redis image version tag
+        default: '7'
+    REDIS_PORT:
+        description: Host port mapped to Redis (6379 inside container)
+        default: '6379'
+    REDIS_PASSWORD:
+        description: Redis password (leave empty to disable authentication)
+        default: ''
+        sensitive: true
 tags:
     - database
     - cache

package/overlays/redpanda/docker-compose.yml

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

package/overlays/redpanda/overlay.yml

@@ -1,12 +1,24 @@
 id: redpanda
 name: Redpanda
 description: Kafka-compatible event streaming with web console
-category: database
+category: messaging
 supports:
     - compose
 requires: []
-suggests: []
-conflicts: []
+suggests:
+    - prometheus
+    - grafana
+conflicts:
+    - mysql
+    - mongodb
+    - nodejs
+    - bun
+    - go
+    - java
+    - dotnet
+    - otel-demo-nodejs
+    - otel-demo-python
+serviceOrder: 0
 tags:
     - database
     - messaging

package/overlays/rocm/overlay.yml

@@ -4,7 +4,8 @@ description: AMD ROCm libraries and GPU passthrough for containerized ML/inferen
 category: dev
 supports: []
 requires: []
-suggests: []
+suggests:
+    - comfyui
 conflicts:
     - cuda
 tags:

package/overlays/rust/overlay.yml

@@ -5,7 +5,9 @@ category: language
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - grafana
+    - open-webui
 tags:
     - language
     - rust

package/overlays/skaffold/README.md

@@ -0,0 +1,256 @@
+# Skaffold Overlay
+
+Installs [Skaffold](https://skaffold.dev), Google's command-line tool for continuous development on Kubernetes — handling the build, push, and deploy lifecycle automatically as source files change.
+
+> **Note:** This overlay conflicts with `tilt` because both tools serve the same "continuous Kubernetes development" role. Choose `skaffold` for a configuration-file-driven, CI-friendly pipeline, or `tilt` for a more interactive, UI-driven workflow.
+
+## Features
+
+- **`skaffold dev`** — Watch source files and automatically rebuild, push, and redeploy on changes
+- **`skaffold run`** — One-shot build and deploy pipeline for CI/CD integration
+- **Declarative config** — `skaffold.yaml` defines the entire build-test-deploy pipeline as code
+- **Multiple builders** — Docker, Buildpacks, Bazel, Jib (Maven/Gradle), and more
+- **Multiple deployers** — `kubectl`, Helm, Kustomize, and Cloud Run
+- **Test integration** — Container Structure Tests and custom test steps built in
+- **Profile support** — Swap out configs per environment (dev, staging, prod)
+
+## How It Works
+
+Skaffold is installed as a static binary in the devcontainer during `setup.sh`. It orchestrates the build-push-deploy cycle against whichever Kubernetes cluster is active in your `kubeconfig` (e.g. a k3d or kind cluster).
+
+**Suggested overlays:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm used as Skaffold deployers
+- `kind` — Full-conformance local Kubernetes cluster
+- `k3d` — Lightweight local Kubernetes cluster
+
+## Installation
+
+Skaffold is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads the Skaffold binary for your architecture (amd64/arm64)
+- Installs to `/usr/local/bin/skaffold`
+- Verifies the installation
+
+## Common Commands
+
+### Development Workflow
+
+```bash
+# Continuous development — rebuild and redeploy on file changes
+skaffold dev
+
+# One-shot build + deploy
+skaffold run
+
+# Delete all resources deployed by Skaffold
+skaffold delete
+
+# Preview what Skaffold would deploy (dry run)
+skaffold render
+```
+
+### Build and Test
+
+```bash
+# Build images only (no deploy)
+skaffold build
+
+# Run tests only
+skaffold test
+
+# Build and push to a registry
+skaffold build --push
+```
+
+### Profiles
+
+```bash
+# Use a specific profile
+skaffold dev --profile staging
+
+# Combine multiple profiles
+skaffold run --profile prod --profile feature-flag
+```
+
+### Debugging
+
+```bash
+# Enable port-forwarding for services
+skaffold dev --port-forward
+
+# Verbose output
+skaffold dev -v debug
+
+# Show rendered manifests
+skaffold render --output manifests.yaml
+```
+
+## Configuration
+
+### skaffold.yaml
+
+Create a `skaffold.yaml` in your project root:
+
+```yaml
+apiVersion: skaffold/v4beta11
+kind: Config
+metadata:
+    name: my-app
+build:
+    artifacts:
+        - image: my-app
+          docker:
+              dockerfile: Dockerfile
+deploy:
+    kubectl:
+        manifests:
+            - k8s/*.yaml
+test:
+    - image: my-app
+      structureTests:
+          - ./structure-test.yaml
+profiles:
+    - name: prod
+      deploy:
+          helm:
+              releases:
+                  - name: my-app
+                    chartPath: helm/my-app
+```
+
+### Common Builders
+
+```yaml
+# Docker (default)
+build:
+  artifacts:
+    - image: my-app
+      docker:
+        dockerfile: Dockerfile
+
+# Buildpacks (no Dockerfile needed)
+build:
+  artifacts:
+    - image: my-app
+      buildpacks:
+        builder: gcr.io/buildpacks/builder:v1
+
+# Jib (Java/Maven)
+build:
+  artifacts:
+    - image: my-app
+      jib:
+        project: my-module
+```
+
+### Common Deployers
+
+```yaml
+# kubectl (plain manifests)
+deploy:
+  kubectl:
+    manifests:
+      - k8s/**/*.yaml
+
+# Helm
+deploy:
+  helm:
+    releases:
+      - name: my-app
+        chartPath: helm/my-app
+        valuesFiles:
+          - helm/values.yaml
+
+# Kustomize
+deploy:
+  kustomize:
+    paths:
+      - k8s/overlays/dev
+```
+
+## Benefits vs Tilt
+
+| Feature               | Skaffold (this overlay)           | Tilt                             |
+| --------------------- | --------------------------------- | -------------------------------- |
+| **Primary interface** | ✅ CLI + skaffold.yaml config     | Interactive UI (port 10350)      |
+| **CI/CD suitability** | ✅ First-class CI support         | ⚠️ UI-oriented, less CI-friendly |
+| **Config format**     | ✅ Declarative YAML               | Starlark/Python (Tiltfile)       |
+| **Build systems**     | ✅ Docker, Buildpacks, Jib, Bazel | Docker, Buildpacks               |
+| **Deploy targets**    | ✅ kubectl, Helm, Kustomize, Run  | kubectl, Helm                    |
+| **Learning curve**    | Lower (declarative YAML)          | Programmable (more flexible)     |
+| **Debugging support** | ✅ Built-in debug mode            | ✅ Built-in live updates         |
+
+**Choose Skaffold when:**
+
+- You want a declarative, portable, config-file-driven pipeline
+- CI/CD integration is a priority
+- You need support for multiple build systems (Jib, Buildpacks, Bazel)
+
+**Choose Tilt when:**
+
+- You prefer an interactive browser UI for development
+- You want fine-grained control over the update pipeline via a Tiltfile
+
+## Use Cases
+
+- **Inner loop acceleration** — Rebuild and redeploy Kubernetes workloads on save, without manual `docker build && kubectl apply`
+- **Multi-service applications** — Manage build and deploy of multiple microservices from a single `skaffold.yaml`
+- **CI/CD integration** — Use `skaffold run` in pipelines for consistent build-test-deploy flows
+- **Helm chart development** — Iterate on Helm charts with live cluster feedback
+- **GitOps preview environments** — Render manifests for inspection or PR previews
+
+**Integrates well with:**
+
+- `kubectl-helm` — Used by Skaffold's deploy pipeline
+- `k3d` — Lightweight local cluster for development
+- `kind` — Full-conformance local cluster for testing
+
+## Troubleshooting
+
+### No kubeconfig Found
+
+```bash
+# Ensure kubectl is configured (kubectl-helm overlay must be selected)
+kubectl cluster-info
+
+# If using k3d, merge cluster config
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# If using kind, kubeconfig is set automatically on cluster creation
+kind create cluster --name dev
+```
+
+### Build Failures
+
+```bash
+# Check Docker is accessible
+docker info
+
+# Run with verbose logging
+skaffold dev -v debug
+```
+
+### Deploy Failures
+
+```bash
+# View Kubernetes events
+kubectl get events --sort-by='.lastTimestamp'
+
+# Tail pod logs
+kubectl logs -f deployment/my-app
+```
+
+## References
+
+- [Skaffold Documentation](https://skaffold.dev/docs/)
+- [Skaffold GitHub](https://github.com/GoogleContainerTools/skaffold)
+- [skaffold.yaml Reference](https://skaffold.dev/docs/references/yaml/)
+- [Kubernetes Documentation](https://kubernetes.io/docs/)
+
+**Related Overlays:**
+
+- [`kubectl-helm`](../kubectl-helm/README.md) — Kubernetes CLI and Helm (recommended with Skaffold)
+- [`kind`](../kind/README.md) — Full-conformance local Kubernetes cluster
+- [`k3d`](../k3d/README.md) — Lightweight local Kubernetes cluster
+- [`tilt`](../tilt/README.md) — Alternative interactive Kubernetes development tool (conflicts)