docker

Docker

The published image is sidequery/sidemantic on Docker Hub. It includes all database drivers, the PostgreSQL wire-protocol server, the HTTP API server, and the MCP server.

Mounting your models

The container looks for model files (YAML, SQL, etc.) in /app/models. Use a volume mount (-v) to point it at your local models directory:

# If your models are in ~/my-project/models/
docker run -p 5433:5433 -v ~/my-project/models:/app/models sidequery/sidemantic

# Or from the current directory
docker run -p 5433:5433 -v $(pwd)/models:/app/models sidequery/sidemantic

The -v local/path:/app/models flag maps a folder on your machine into the container. Any .yml, .sql, or other semantic model files in that folder will be auto-detected and loaded.

PostgreSQL server (default)

Mount your models directory and expose port 5433:

docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic

Connect with any PostgreSQL client:

psql -h localhost -p 5433 -U any -d sidemantic

With a backend database connection:

docker run -p 5433:5433 \
  -v ./models:/app/models \
  -e SIDEMANTIC_CONNECTION="postgres://user:pass@host:5432/db" \
  sidequery/sidemantic

MCP server

docker run -v ./models:/app/models -e SIDEMANTIC_MODE=mcp sidequery/sidemantic

HTTP API server

docker run -p 4400:4400 \
  -v ./models:/app/models \
  -e SIDEMANTIC_MODE=api \
  -e SIDEMANTIC_API_TOKEN=secret \
  sidequery/sidemantic

JSON query:

curl -s http://localhost:4400/query \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"metrics":["orders.order_count"]}'

Arrow query:

curl -s http://localhost:4400/query \
  -H "Authorization: Bearer secret" \
  -H "Accept: application/vnd.apache.arrow.stream" \
  -H "Content-Type: application/json" \
  -d '{"metrics":["orders.order_count"]}' > result.arrow

Both servers simultaneously

Runs the PG server in the background and MCP on stdio:

docker run -p 5433:5433 -v ./models:/app/models -e SIDEMANTIC_MODE=both sidequery/sidemantic

Demo mode

docker run -p 5433:5433 sidequery/sidemantic --demo

Baking models into the image

FROM sidequery/sidemantic
COPY my_models/ /app/models/

Environment variables

Variable	Description
SIDEMANTIC_MODE	serve (default), mcp, api, 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)
SIDEMANTIC_API_PORT	HTTP API port (default 4400)
SIDEMANTIC_API_TOKEN	HTTP API bearer token
SIDEMANTIC_CORS_ORIGINS	Comma-separated list of allowed CORS origins
SIDEMANTIC_MAX_REQUEST_BODY_BYTES	Max HTTP request body size in bytes

Building from source

From the repo root:

docker build -t sidemantic .

Integration test services (docker-compose)

The docker-compose.yml in this directory spins up Postgres, BigQuery emulator, Spark, and ClickHouse for local integration testing:

docker compose -f examples/docker/docker-compose.yml up