From 1f8e68d129833065eb1ccbff004295e22bb27f44 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 21 Feb 2026 12:04:44 -0800 Subject: [PATCH] Move Docker demo to examples/docker, simplify README - Move docker-compose.yml to examples/docker (integration test infra) - Add examples/docker/README.md with detailed Docker usage docs - Trim main README Docker section to prioritize published sidequery/sidemantic image - Clarify volume mount requirement and ADBC connection method --- README.md | 67 ++-------------- examples/docker/README.md | 80 +++++++++++++++++++ .../docker/docker-compose.yml | 0 3 files changed, 86 insertions(+), 61 deletions(-) create mode 100644 examples/docker/README.md rename docker-compose.yml => examples/docker/docker-compose.yml (100%) diff --git a/README.md b/README.md index db7e5652..d1761ed1 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ A universal metrics layer for consistent metrics across your data stack. Compatible with 15+ semantic model formats. - **Supported Formats:** Sidemantic (YAML, Python or SQL), Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML -- **Databases:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL, ADBC +- **Databases:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL (also via ADBC) [Documentation](https://sidemantic.com) | [GitHub](https://github.com/sidequery/sidemantic) | [Discord](https://discord.com/invite/7MZ4UgSVvF) | [Demo](https://sidemantic.com/demo) (50+ MB data download, runs in your browser with Pyodide + DuckDB) @@ -252,74 +252,19 @@ load_from_directory(layer, "my_models/") # Auto-detects formats ## Docker -Build the image (includes all database drivers, PG server, and MCP server): +The published image is [`sidequery/sidemantic`](https://hub.docker.com/r/sidequery/sidemantic) on Docker Hub. Mount your models directory as a volume at `/app/models`: ```bash -docker build -t sidemantic . +docker run -p 5433:5433 -v ./models:/app/models sidequery/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: +Demo mode (built-in sample data, no volume needed): ```bash -docker run -p 5433:5433 \ - -v ./models:/app/models \ - -e SIDEMANTIC_CONNECTION="postgres://user:pass@host:5432/db" \ - sidemantic +docker run -p 5433:5433 sidequery/sidemantic --demo ``` -### 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) | +See [`examples/docker/`](examples/docker/) for MCP mode, env vars, building from source, and integration test services. ## Testing diff --git a/examples/docker/README.md b/examples/docker/README.md new file mode 100644 index 00000000..ac0c5bb3 --- /dev/null +++ b/examples/docker/README.md @@ -0,0 +1,80 @@ +# Docker + +The published image is `sidequery/sidemantic` on Docker Hub. It includes all database drivers, the PostgreSQL wire-protocol server, and the MCP server. + +## PostgreSQL server (default) + +Mount your models directory and expose port 5433: + +```bash +docker run -p 5433:5433 -v ./models:/app/models sidequery/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" \ + sidequery/sidemantic +``` + +## MCP server + +```bash +docker run -v ./models:/app/models -e SIDEMANTIC_MODE=mcp sidequery/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 sidequery/sidemantic +``` + +## Demo mode + +```bash +docker run -p 5433:5433 sidequery/sidemantic --demo +``` + +## Baking models into the image + +```dockerfile +FROM sidequery/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) | + +## Building from source + +From the repo root: + +```bash +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: + +```bash +docker compose -f examples/docker/docker-compose.yml up +``` diff --git a/docker-compose.yml b/examples/docker/docker-compose.yml similarity index 100% rename from docker-compose.yml rename to examples/docker/docker-compose.yml