container-superposition 0.1.7 → 0.1.9

package/overlays/pgvector/README.md

@@ -0,0 +1,215 @@
+# pgvector Overlay
+
+Adds a PostgreSQL 16 database pre-loaded with the [pgvector](https://github.com/pgvector/pgvector) extension, enabling vector similarity search directly within a familiar SQL environment.
+
+> **Note:** This overlay conflicts with the `postgres` overlay because both provide a PostgreSQL service on port 5432. Choose `pgvector` when you need vector search, or `postgres` for a plain database.
+
+## Features
+
+- **pgvector extension** — `CREATE EXTENSION vector;` is available immediately; no manual installation required
+- **Full PostgreSQL 16** — All standard SQL features alongside vector operations
+- **`psql` client in devcontainer** — `postgresql-client` package installed for interactive SQL sessions
+- **Pre-configured environment** — `PGHOST`, `PGPORT`, `PGDATABASE`, and `PGUSER` set automatically
+- **Persistent storage** — Named Docker volume preserves data across container rebuilds
+- **Health check** — Compose readiness check using `pg_isready` before dependent services start
+
+## How It Works
+
+pgvector runs as a Docker Compose service (`pgvector`) alongside your devcontainer, using the official `pgvector/pgvector:pg16` image, which bundles PostgreSQL 16 with the pgvector extension pre-compiled and ready to use.
+
+**Service configuration:**
+
+- Image: `pgvector/pgvector:pg16`
+- Network: `devnet` (shared with the dev container)
+- Port: `5432` (customisable via `PGVECTOR_PORT`)
+- Volume: `pgvector-data` for persistent data
+
+The following environment variables are pre-set in the devcontainer for seamless `psql` usage:
+
+| Variable     | Value      |
+| ------------ | ---------- |
+| `PGHOST`     | `pgvector` |
+| `PGPORT`     | `5432`     |
+| `PGDATABASE` | `devdb`    |
+| `PGUSER`     | `postgres` |
+
+## Getting Started
+
+```bash
+# Connect to the database
+psql -h pgvector -U postgres -d devdb
+
+# Enable the vector extension (run once per database)
+psql -h pgvector -U postgres -d devdb -c "CREATE EXTENSION IF NOT EXISTS vector;"
+
+# Verify the extension is installed
+psql -h pgvector -U postgres -d devdb -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
+```
+
+## Common Commands
+
+### Vector Operations in SQL
+
+```sql
+-- Enable the extension in your database
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create a table with a vector column (1536 dimensions for OpenAI embeddings)
+CREATE TABLE documents (
+    id       SERIAL PRIMARY KEY,
+    content  TEXT,
+    embedding vector(1536)
+);
+
+-- Insert a record with an embedding
+INSERT INTO documents (content, embedding)
+VALUES ('Hello, world!', '[0.1, 0.2, 0.3, ...]');
+
+-- Cosine similarity search (find closest neighbours)
+SELECT id, content, 1 - (embedding <=> '[0.1, 0.2, 0.3, ...]') AS similarity
+FROM documents
+ORDER BY embedding <=> '[0.1, 0.2, 0.3, ...]'
+LIMIT 5;
+
+-- Create an HNSW index for faster approximate search
+CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
+
+-- Create an IVFFlat index for large datasets
+CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+```
+
+### Database Management
+
+```bash
+# Connect interactively
+psql
+
+# Run a SQL file
+psql -f schema.sql
+
+# Dump the database
+pg_dump -h pgvector -U postgres devdb > backup.sql
+
+# Restore from dump
+psql -h pgvector -U postgres devdb < backup.sql
+```
+
+### Python Integration
+
+```bash
+pip install psycopg2-binary pgvector
+
+python - <<'EOF'
+import psycopg2
+from pgvector.psycopg2 import register_vector
+import numpy as np
+
+conn = psycopg2.connect(
+    host="pgvector", port=5432,
+    dbname="devdb", user="postgres", password="postgres"
+)
+register_vector(conn)
+cur = conn.cursor()
+
+cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+cur.execute("CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, embedding vector(3))")
+cur.execute("INSERT INTO items (embedding) VALUES (%s)", (np.array([1, 2, 3]),))
+conn.commit()
+
+cur.execute("SELECT * FROM items ORDER BY embedding <-> %s LIMIT 5", (np.array([1, 2, 4]),))
+print(cur.fetchall())
+conn.close()
+EOF
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable            | Default    | Description                                |
+| ------------------- | ---------- | ------------------------------------------ |
+| `PGVECTOR_VERSION`  | `pg16`     | pgvector image tag (e.g. `pg16`, `pg17`)   |
+| `PGVECTOR_DB`       | `devdb`    | Name of the database to create             |
+| `PGVECTOR_USER`     | `postgres` | PostgreSQL superuser name                  |
+| `PGVECTOR_PASSWORD` | `postgres` | PostgreSQL superuser password              |
+| `PGVECTOR_PORT`     | `5432`     | Host port mapped to the PostgreSQL service |
+
+Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize.
+
+## pgvector vs Qdrant
+
+| Feature              | pgvector (this overlay)         | Qdrant                   |
+| -------------------- | ------------------------------- | ------------------------ |
+| **Storage model**    | ✅ Relational + vector          | Vector-only              |
+| **SQL support**      | ✅ Full PostgreSQL SQL          | ❌ REST/gRPC API only    |
+| **Familiar tooling** | ✅ psql, ORMs, existing schema  | New client SDKs required |
+| **Query language**   | ✅ SQL with `<->`, `<=>`, `<#>` | ⚠️ JSON query DSL        |
+| **Filtering**        | ✅ SQL WHERE clause             | ✅ Payload-based filters |
+| **Scale**            | ⚠️ Vertical scaling preferred   | ✅ Distributed by design |
+| **Index types**      | IVFFlat, HNSW                   | HNSW                     |
+
+**Choose pgvector when:**
+
+- You already use PostgreSQL and want to add vectors to existing tables
+- You need to join vector results with relational data
+- Your team is comfortable with SQL
+
+**Choose Qdrant when:**
+
+- Vectors are your primary data model
+- You need purpose-built vector search performance at scale
+- You want advanced filtering and payload storage
+
+## Use Cases
+
+- **RAG pipelines** — Store document embeddings alongside metadata; retrieve context with SQL joins
+- **Semantic search** — Add vector search to an existing PostgreSQL application without a second database
+- **Hybrid search** — Combine full-text search (`tsvector`) with vector similarity in a single query
+- **Recommendation systems** — Store and query user or item embeddings with familiar SQL tooling
+
+**Integrates well with:**
+
+- `ollama` — Generate embeddings locally with `nomic-embed-text` or similar models
+- `python` — `psycopg2` + `pgvector` Python package for seamless integration
+- `nodejs` — `pg` driver with raw SQL for vector operations
+
+## Troubleshooting
+
+### Extension Not Found
+
+If `CREATE EXTENSION vector` fails:
+
+```bash
+# Confirm pgvector image (not plain postgres) is in use
+docker compose ps pgvector
+
+# Check available extensions
+psql -h pgvector -U postgres -c "SELECT name FROM pg_available_extensions WHERE name = 'vector';"
+```
+
+### Port Conflict with postgres Overlay
+
+The `pgvector` and `postgres` overlays both bind port 5432 and conflict with each other. Select only one.
+
+### Connection Refused
+
+```bash
+# Check service health
+docker compose ps pgvector
+docker compose logs pgvector
+```
+
+## References
+
+- [pgvector GitHub](https://github.com/pgvector/pgvector)
+- [pgvector Docker Image](https://hub.docker.com/r/pgvector/pgvector)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/16/)
+- [pgvector Python package](https://github.com/pgvector/pgvector-python)
+- [pgvector Node.js package](https://github.com/pgvector/pgvector-node)
+
+**Related Overlays:**
+
+- [`postgres`](../postgres/README.md) — Plain PostgreSQL without pgvector (conflicts)
+- [`qdrant`](../qdrant/README.md) — Purpose-built vector database (alternative)
+- [`ollama`](../ollama/README.md) — Local embedding generation
+- [`python`](../python/README.md) — Python development environment

package/overlays/pgvector/devcontainer.patch.json

@@ -0,0 +1,29 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["pgvector"],
+    "forwardPorts": [5432],
+    "portsAttributes": {
+        "5432": {
+            "label": "pgvector database",
+            "onAutoForward": "notify"
+        }
+    },
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "postgresql-client",
+            "apk": "postgresql-client"
+        }
+    },
+    "remoteEnv": {
+        "PGVECTOR_HOST": "pgvector",
+        "PGVECTOR_PORT": "5432",
+        "PGVECTOR_DB": "{{cs.PGVECTOR_DB}}",
+        "PGVECTOR_USER": "{{cs.PGVECTOR_USER}}",
+        "PGVECTOR_PASSWORD": "{{cs.PGVECTOR_PASSWORD}}",
+        "POSTGRES_HOST": "pgvector",
+        "POSTGRES_PORT": "5432",
+        "POSTGRES_DB": "{{cs.PGVECTOR_DB}}",
+        "POSTGRES_USER": "{{cs.PGVECTOR_USER}}",
+        "POSTGRES_PASSWORD": "{{cs.PGVECTOR_PASSWORD}}"
+    }
+}

package/overlays/pgvector/docker-compose.yml

@@ -0,0 +1,33 @@
+version: '3.8'
+
+services:
+    pgvector:
+        image: pgvector/pgvector:${PGVECTOR_VERSION:-{{cs.PGVECTOR_VERSION}}}
+        restart: unless-stopped
+        volumes:
+            - pgvector-data:/var/lib/postgresql/data
+        environment:
+            POSTGRES_DB: ${PGVECTOR_DB:-{{cs.PGVECTOR_DB}}}
+            POSTGRES_USER: ${PGVECTOR_USER:-{{cs.PGVECTOR_USER}}}
+            POSTGRES_PASSWORD: ${PGVECTOR_PASSWORD:-{{cs.PGVECTOR_PASSWORD}}}
+        ports:
+            - '${PGVECTOR_PORT:-{{cs.PGVECTOR_PORT}}}:5432'
+        networks:
+            - devnet
+        healthcheck:
+            test:
+                [
+                    'CMD-SHELL',
+                    'pg_isready -U ${PGVECTOR_USER:-{{cs.PGVECTOR_USER}}} -d ${PGVECTOR_DB:-{{cs.PGVECTOR_DB}}}',
+                ]
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
+
+volumes:
+    pgvector-data:
+
+networks:
+    devnet:
+        name: devnet

package/overlays/pgvector/overlay.yml

@@ -0,0 +1,47 @@
+id: pgvector
+name: pgvector (PostgreSQL + vector)
+description: PostgreSQL 16 with the pgvector extension for vector similarity search
+category: database
+supports:
+    - compose
+requires: []
+suggests:
+    - ollama
+    - python
+    - nodejs
+    - prometheus
+    - grafana
+conflicts:
+    - postgres
+serviceOrder: 0
+tags:
+    - database
+    - sql
+    - vector
+    - embeddings
+    - postgres
+    - pgvector
+ports:
+    - port: 5432
+      service: pgvector
+      protocol: tcp
+      description: pgvector database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'postgresql://{pgvector_user}:{pgvector_password}@{host}:{port}/{pgvector_db}'
+parameters:
+    PGVECTOR_DB:
+        description: Name of the database to create
+        default: devdb
+    PGVECTOR_USER:
+        description: PostgreSQL superuser name
+        default: postgres
+    PGVECTOR_PASSWORD:
+        description: PostgreSQL superuser password
+        default: postgres
+        sensitive: true
+    PGVECTOR_PORT:
+        description: Host port mapped to pgvector (5432 inside container)
+        default: '5432'
+    PGVECTOR_VERSION:
+        description: pgvector/pgvector image tag (e.g. pg16, pg17)
+        default: pg16

package/overlays/playwright/devcontainer.patch.json

@@ -1,10 +1,5 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "ghcr.io/devcontainers/features/node:1": {
-            "version": "lts"
-        }
-    },
     "postCreateCommand": {
         "setup-playwright": "bash .devcontainer/scripts/setup-playwright.sh"
     }

package/overlays/playwright/overlay.yml

@@ -3,7 +3,8 @@ name: Playwright
 description: Browser automation and testing framework
 category: dev
 supports: []
-requires: []
+requires:
+    - nodejs
 suggests: []
 conflicts: []
 tags:

package/overlays/postgres/.env.example

@@ -1,6 +1,6 @@
 # PostgreSQL Configuration
-POSTGRES_VERSION=16
-POSTGRES_DB=devdb
-POSTGRES_USER=postgres
-POSTGRES_PASSWORD=postgres
-POSTGRES_PORT=5432
+POSTGRES_VERSION={{cs.POSTGRES_VERSION}}
+POSTGRES_DB={{cs.POSTGRES_DB}}
+POSTGRES_USER={{cs.POSTGRES_USER}}
+POSTGRES_PASSWORD={{cs.POSTGRES_PASSWORD}}
+POSTGRES_PORT={{cs.POSTGRES_PORT}}

package/overlays/postgres/devcontainer.patch.json

@@ -13,9 +13,9 @@
     },
     "remoteEnv": {
         "POSTGRES_HOST": "postgres",
-        "POSTGRES_PORT": "5432",
-        "POSTGRES_DB": "devdb",
-        "POSTGRES_USER": "postgres",
-        "POSTGRES_PASSWORD": "postgres"
+        "POSTGRES_PORT": "{{cs.POSTGRES_PORT}}",
+        "POSTGRES_DB": "{{cs.POSTGRES_DB}}",
+        "POSTGRES_USER": "{{cs.POSTGRES_USER}}",
+        "POSTGRES_PASSWORD": "{{cs.POSTGRES_PASSWORD}}"
     }
 }

package/overlays/postgres/docker-compose.yml

@@ -2,20 +2,24 @@ version: '3.8'
 
 services:
     postgres:
-        image: postgres:${POSTGRES_VERSION:-16}-alpine
+        image: postgres:${POSTGRES_VERSION:-{{cs.POSTGRES_VERSION}}}-alpine
         restart: unless-stopped
         volumes:
             - postgres-data:/var/lib/postgresql/data
         environment:
-            POSTGRES_DB: ${POSTGRES_DB:-devdb}
-            POSTGRES_USER: ${POSTGRES_USER:-postgres}
-            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+            POSTGRES_DB: ${POSTGRES_DB:-{{cs.POSTGRES_DB}}}
+            POSTGRES_USER: ${POSTGRES_USER:-{{cs.POSTGRES_USER}}}
+            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-{{cs.POSTGRES_PASSWORD}}}
         ports:
-            - '${POSTGRES_PORT:-5432}:5432'
+            - '${POSTGRES_PORT:-{{cs.POSTGRES_PORT}}}:5432'
         networks:
             - devnet
         healthcheck:
-            test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-devdb}']
+            test:
+                [
+                    'CMD-SHELL',
+                    'pg_isready -U ${POSTGRES_USER:-{{cs.POSTGRES_USER}}} -d ${POSTGRES_DB:-{{cs.POSTGRES_DB}}}',
+                ]
             interval: 10s
             timeout: 5s
             retries: 5
@@ -26,3 +30,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/postgres/overlay.yml

@@ -5,8 +5,12 @@ category: database
 supports:
     - compose
 requires: []
-suggests: []
-conflicts: []
+suggests:
+    - prometheus
+    - grafana
+conflicts:
+    - pgvector
+serviceOrder: 0
 tags:
     - database
     - sql
@@ -18,3 +22,20 @@ ports:
       description: PostgreSQL database connection
       onAutoForward: notify
       connectionStringTemplate: 'postgresql://{postgres_user}:{postgres_password}@{host}:{port}/{postgres_db}'
+parameters:
+    POSTGRES_DB:
+        description: Name of the database to create
+        default: devdb
+    POSTGRES_USER:
+        description: PostgreSQL superuser name
+        default: postgres
+    POSTGRES_PASSWORD:
+        description: PostgreSQL superuser password
+        default: postgres
+        sensitive: true
+    POSTGRES_PORT:
+        description: Host port mapped to PostgreSQL (5432 inside container)
+        default: '5432'
+    POSTGRES_VERSION:
+        description: PostgreSQL major version
+        default: '16'

package/overlays/pre-commit/devcontainer.patch.json

@@ -1,9 +1,3 @@
 {
-    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "ghcr.io/devcontainers/features/python:1": {
-            "version": "3.12",
-            "installTools": true
-        }
-    }
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
 }

package/overlays/prometheus/devcontainer.patch.json

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

package/overlays/prometheus/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     prometheus:
         image: prom/prometheus:${PROMETHEUS_VERSION:-latest}
+        restart: unless-stopped
         command:
             - '--config.file=/etc/prometheus/prometheus.yml'
             - '--storage.tsdb.path=/prometheus'
@@ -14,9 +15,16 @@ services:
             - '${PROMETHEUS_PORT:-9090}:9090'
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:9090/-/ready']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 15s
 
 volumes:
     prometheus_data:
 
 networks:
     devnet:
+        name: devnet

package/overlays/prometheus/overlay.yml

@@ -20,5 +20,6 @@ ports:
       path: /
       onAutoForward: openBrowser
 order: 1
+serviceOrder: 1
 imports:
     - .shared/otel/instrumentation.env

package/overlays/promtail/devcontainer.patch.json

@@ -1,5 +1,4 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "runServices": ["promtail"],
-    "_serviceOrder": 2
+    "runServices": ["promtail"]
 }

package/overlays/promtail/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     promtail:
         image: grafana/promtail:${PROMTAIL_VERSION:-latest}
+        restart: unless-stopped
         command: -config.file=/etc/promtail/promtail-config.yaml
         volumes:
             - ./promtail-config-promtail.yaml:/etc/promtail/promtail-config.yaml
@@ -11,6 +12,13 @@ services:
             - loki
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:9080/ready']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
 
 networks:
     devnet:
+        name: devnet

package/overlays/promtail/overlay.yml

@@ -15,3 +15,4 @@ tags:
     - loki
 ports: []
 order: 2
+serviceOrder: 2

package/overlays/qdrant/.env.example

@@ -0,0 +1,4 @@
+# Qdrant Configuration
+QDRANT_VERSION={{cs.QDRANT_VERSION}}
+QDRANT_PORT={{cs.QDRANT_PORT}}
+QDRANT_GRPC_PORT={{cs.QDRANT_GRPC_PORT}}