Add Docker setup with PG and MCP servers

.dockerignore

@@ -0,0 +1,26 @@
+.git
+.github
+.venv
+.mypy_cache
+.pytest_cache
+.ruff_cache
+__pycache__
+*.egg-info
+*.pyc
+
+# Rust/DuckDB extension builds (not needed for Python image)
+sidemantic-rs/
+sidemantic-duckdb/
+
+# Docs and examples not needed at runtime
+docs/
+examples/superset_demo/
+examples/rill_demo/
+examples/cube_demo/
+
+# Dev/test artifacts
+Dockerfile.test
+docker-compose.yml
+*.md
+!README.md
+.context/

.github/workflows/docker.yml

@@ -0,0 +1,64 @@
+name: Docker
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'Dockerfile'
+      - 'docker-entrypoint.sh'
+      - '.dockerignore'
+      - 'sidemantic/**'
+      - 'pyproject.toml'
+  pull_request:
+    paths:
+      - 'Dockerfile'
+      - 'docker-entrypoint.sh'
+      - '.dockerignore'
+      - 'sidemantic/**'
+      - 'pyproject.toml'
+
+jobs:
+  docker:
+    name: Docker build and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t sidemantic .
+
+      - name: Start server (demo mode)
+        run: |
+          docker run -d --name sidemantic-test -p 5433:5433 sidemantic --demo
+          for i in $(seq 1 30); do
+            if docker logs sidemantic-test 2>&1 | grep -q "Listening on"; then
+              echo "Server ready"
+              break
+            fi
+            echo "Waiting for server... ($i/30)"
+            sleep 1
+          done
+
+      - name: Verify server logs
+        run: docker logs sidemantic-test 2>&1
+
+      - name: Install psql
+        run: sudo apt-get update && sudo apt-get install -y postgresql-client
+
+      - name: Test connection
+        run: PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c "SELECT 1 AS test"
+
+      - name: Test metric aggregation (products)
+        run: |
+          PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c \
+            "SELECT category, product_count, avg_price, total_catalog_value FROM semantic_layer.products GROUP BY category ORDER BY category"
+
+      - name: Test metric aggregation (customers)
+        run: |
+          PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c \
+            "SELECT region, customer_count FROM semantic_layer.customers GROUP BY region ORDER BY region"
+
+      - name: Stop server
+        if: always()
+        run: docker stop sidemantic-test || true

Dockerfile

@@ -0,0 +1,41 @@
+FROM python:3.12-slim AS builder
+
+# Install build deps for riffq (Rust/maturin) and other native extensions
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY sidemantic/ sidemantic/
+COPY examples/ examples/
+
+RUN uv pip install --system --no-cache ".[serve,mcp,all-databases]"
+
+# --- Runtime stage (no build tools) ---
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin/sidemantic /usr/local/bin/sidemantic
+
+WORKDIR /app
+
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+RUN mkdir -p /app/models
+WORKDIR /app/models
+
+EXPOSE 5433
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
+# Mode is controlled by SIDEMANTIC_MODE env var (serve, mcp, both)

README.md

@@ -252,6 +252,77 @@ load_from_directory(layer, "my_models/")  # Auto-detects formats
 | Databricks | ✅ | `uv add sidemantic[databricks]` |
 | Spark SQL | ✅ | `uv add sidemantic[spark]` |
 
+## Docker
+
+Build the image (includes all database drivers, PG server, and MCP server):
+
+```bash
+docker build -t sidemantic .
+```
+
+### PostgreSQL server (default)
+
+Mount your models directory and expose port 5433:
+
+```bash
+docker run -p 5433:5433 -v ./models:/app/models sidemantic
+```
+
+Connect with any PostgreSQL client:
+
+```bash
+psql -h localhost -p 5433 -U any -d sidemantic
+```
+
+With a backend database connection:
+
+```bash
+docker run -p 5433:5433 \
+  -v ./models:/app/models \
+  -e SIDEMANTIC_CONNECTION="postgres://user:pass@host:5432/db" \
+  sidemantic
+```
+
+### MCP server
+
+```bash
+docker run -v ./models:/app/models -e SIDEMANTIC_MODE=mcp sidemantic
+```
+
+### Both servers simultaneously
+
+Runs the PG server in the background and MCP on stdio:
+
+```bash
+docker run -p 5433:5433 -v ./models:/app/models -e SIDEMANTIC_MODE=both sidemantic
+```
+
+### Demo mode
+
+```bash
+docker run -p 5433:5433 sidemantic --demo
+```
+
+### Baking models into the image
+
+Create a `Dockerfile` that copies your models at build time:
+
+```dockerfile
+FROM sidemantic
+COPY my_models/ /app/models/
+```
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SIDEMANTIC_MODE` | `serve` (default), `mcp`, or `both` |
+| `SIDEMANTIC_CONNECTION` | Database connection string |
+| `SIDEMANTIC_DB` | Path to DuckDB file (inside container) |
+| `SIDEMANTIC_USERNAME` | PG server auth username |
+| `SIDEMANTIC_PASSWORD` | PG server auth password |
+| `SIDEMANTIC_PORT` | PG server port (default 5433) |
+
 ## Testing
 
 ```bash

docker-entrypoint.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+set -e
+
+# SIDEMANTIC_MODE: "serve" (default), "mcp", or "both"
+MODE="${SIDEMANTIC_MODE:-serve}"
+
+# Build shared args from environment variables
+ARGS=""
+if [ -n "$SIDEMANTIC_CONNECTION" ]; then
+    ARGS="$ARGS --connection $SIDEMANTIC_CONNECTION"
+fi
+if [ -n "$SIDEMANTIC_DB" ]; then
+    ARGS="$ARGS --db $SIDEMANTIC_DB"
+fi
+
+# Serve-specific args
+SERVE_ARGS=""
+if [ -n "$SIDEMANTIC_USERNAME" ]; then
+    SERVE_ARGS="$SERVE_ARGS --username $SIDEMANTIC_USERNAME"
+fi
+if [ -n "$SIDEMANTIC_PASSWORD" ]; then
+    SERVE_ARGS="$SERVE_ARGS --password $SIDEMANTIC_PASSWORD"
+fi
+if [ -n "$SIDEMANTIC_PORT" ]; then
+    SERVE_ARGS="$SERVE_ARGS --port $SIDEMANTIC_PORT"
+fi
+
+case "$MODE" in
+    serve)
+        exec sidemantic serve --host 0.0.0.0 $ARGS $SERVE_ARGS "$@"
+        ;;
+    mcp)
+        exec sidemantic mcp-serve $ARGS "$@"
+        ;;
+    both)
+        # Start PG server in background, MCP on stdio in foreground
+        sidemantic serve --host 0.0.0.0 $ARGS $SERVE_ARGS &
+        SERVE_PID=$!
+        trap "kill $SERVE_PID 2>/dev/null" EXIT
+        exec sidemantic mcp-serve $ARGS "$@"
+        ;;
+    *)
+        echo "Unknown SIDEMANTIC_MODE: $MODE (use serve, mcp, or both)" >&2
+        exit 1
+        ;;
+esac

sidemantic/cli.py

@@ -422,6 +422,7 @@ def serve(
         None, "--connection", help="Database connection string (e.g., postgres://host/db, bigquery://project/dataset)"
     ),
     db: Path = typer.Option(None, "--db", help="Path to DuckDB database file (shorthand for duckdb:/// connection)"),
+    host: str = typer.Option(None, "--host", "-H", help="Host/IP to bind to (overrides config, default 127.0.0.1)"),
     port: int = typer.Option(None, "--port", "-p", help="Port to listen on (overrides config)"),
     username: str = typer.Option(None, "--username", "-u", help="Username for authentication (overrides config)"),
     password: str = typer.Option(None, "--password", help="Password for authentication (overrides config)"),
@@ -482,7 +483,8 @@ def serve(
         # Use connection from config
         connection_str = build_connection_string(_loaded_config)
 
-    # Resolve port, username, password from args or config
+    # Resolve host, port, username, password from args or config
+    host_resolved = host or (_loaded_config.pg_server.host if _loaded_config else "127.0.0.1")
     port_resolved = port if port is not None else (_loaded_config.pg_server.port if _loaded_config else 5433)
     username_resolved = username or (_loaded_config.pg_server.username if _loaded_config else None)
     password_resolved = password or (_loaded_config.pg_server.password if _loaded_config else None)
@@ -535,7 +537,7 @@ def serve(
                 layer.conn.executemany(f"INSERT INTO {table} VALUES ({placeholders})", rows)
 
     # Start the server
-    start_server(layer, port=port_resolved, username=username_resolved, password=password_resolved)
+    start_server(layer, host=host_resolved, port=port_resolved, username=username_resolved, password=password_resolved)
 
 
 @app.command(hidden=True)

sidemantic/config.py

@@ -104,6 +104,7 @@ class PostgresServerConfig(BaseModel):
     This feature is experimental and may change.
     """
 
+    host: str = Field(default="127.0.0.1", description="Host/IP to bind to (use 0.0.0.0 for Docker)")
     port: int = Field(default=5433, description="Port to listen on")
     username: str | None = Field(default=None, description="Username for authentication (optional)")
     password: str | None = Field(default=None, description="Password for authentication (optional)")

sidemantic/server/server.py

@@ -33,6 +33,7 @@ def map_type(duckdb_type: str) -> str:
 
 def start_server(
     layer: SemanticLayer,
+    host: str = "127.0.0.1",
     port: int = 5433,
     username: str | None = None,
     password: str | None = None,
@@ -41,6 +42,7 @@ def start_server(
 
     Args:
         layer: Semantic layer instance
+        host: Host/IP to bind to (use 0.0.0.0 for Docker)
         port: Port to listen on
         username: Username for authentication (optional)
         password: Password for authentication (optional)
@@ -52,7 +54,7 @@ def __init__(self, connection_id, executor):
             super().__init__(connection_id, executor, layer, username, password)
 
     # Start server
-    server = riffq.RiffqServer(f"127.0.0.1:{port}", connection_cls=BoundConnection)
+    server = riffq.RiffqServer(f"{host}:{port}", connection_cls=BoundConnection)
 
     # Register catalog
     typer.echo("Registering semantic layer catalog...", err=True)
@@ -134,12 +136,13 @@ def __init__(self, connection_id, executor):
         server._server.register_table("sidemantic", "semantic_layer", "metrics", metric_columns)
         typer.echo("  Registered table: semantic_layer.metrics", err=True)
 
-    typer.echo(f"\nStarting PostgreSQL-compatible server on 127.0.0.1:{port}", err=True)
+    typer.echo(f"\nStarting PostgreSQL-compatible server on {host}:{port}", err=True)
     if username:
         typer.echo(f"Authentication: username={username}", err=True)
     else:
         typer.echo("Authentication: disabled (any username/password accepted)", err=True)
-    typer.echo(f"\nConnect with: psql -h 127.0.0.1 -p {port} -U {username or 'any'} -d sidemantic\n", err=True)
+    connect_host = "localhost" if host == "0.0.0.0" else host
+    typer.echo(f"\nConnect with: psql -h {connect_host} -p {port} -U {username or 'any'} -d sidemantic\n", err=True)
 
     # Disable catalog_emulation and handle catalog queries manually in our Python handler
     # This prevents riffq from intercepting queries with its DataFusion parser (which fails on multi-statement queries)