Add Docker production setup with PostgreSQL and MCP servers

- Dockerfile: Multi-stage build with all database drivers and optional dependencies (serve, mcp, all-databases). 781MB runtime image.
- docker-entrypoint.sh: Single container with SIDEMANTIC_MODE env var to control serve/mcp/both modes
- .dockerignore: Excludes unnecessary files for faster builds
- Add --host parameter to sidemantic serve CLI and config for container networking (0.0.0.0 support)
- README: Comprehensive Docker usage section with examples

Server fully tested: psql connections work, semantic layer tables queryable, demo mode verified.

Author: nicosuave

.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/

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)