Skip to content

README.md

Latest commit

 

History

History
94 lines (65 loc) · 2.7 KB

README.md

File metadata and controls

94 lines (65 loc) · 2.7 KB

Cloudflare Containers

This example runs the Sidemantic HTTP API behind a Cloudflare Worker that proxies requests into Cloudflare Containers.

Deployment shape

  • HTTPS terminates at the Worker.
  • The Worker starts a Sidemantic container and forwards requests to port 4400.
  • The container runs SIDEMANTIC_MODE=api.
  • The example image bakes demo models and a seeded demo.duckdb into /app/models.

For a real deployment, the clean shape is:

  • bake your semantic models into the container image
  • point Sidemantic at an external database with SIDEMANTIC_CONNECTION
  • keep DuckDB files out of the container unless they are disposable, because Cloudflare container disks reset on stop

Files

  • wrangler.jsonc: Cloudflare Worker and container binding config
  • src/index.ts: Worker entrypoint and container proxy
  • Dockerfile: Sidemantic container image used by Cloudflare

Prereqs

  • Bun
  • Docker
  • A Cloudflare account with Containers enabled
  • Wrangler auth: bunx wrangler whoami

Deploy the demo

cd examples/cloudflare_containers
bun install
bunx wrangler secret put SIDEMANTIC_API_TOKEN
bun run deploy

After deploy, query the worker URL:

curl -s https://YOUR-WORKER.workers.dev/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metrics":["customers.customer_count"]}'

Arrow still works through the Worker:

curl -s https://YOUR-WORKER.workers.dev/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.apache.arrow.stream" \
  -H "Content-Type: application/json" \
  -d '{"metrics":["customers.customer_count"]}' \
  > result.arrow

Switching from demo to real models

Edit Dockerfile to bake in your models:

FROM sidequery/sidemantic:latest

ENV SIDEMANTIC_MODE=api
ENV SIDEMANTIC_API_PORT=4400

COPY models/ /app/models/
WORKDIR /app/models

Then remove SIDEMANTIC_DB from the default container env in src/index.ts.

Then set your warehouse connection:

bunx wrangler secret put SIDEMANTIC_CONNECTION

The Worker passes SIDEMANTIC_CONNECTION, SIDEMANTIC_API_TOKEN, and SIDEMANTIC_CORS_ORIGINS into the container at startup.

Auth

The container already supports bearer-token auth via SIDEMANTIC_API_TOKEN.

If you want proper edge auth, put the deployed hostname behind Cloudflare Access and use service tokens or your IdP there. Keep the app bearer token as a second gate if you want defense in depth.

Notes

  • Cloudflare Containers is beta.
  • Cold starts are materially slower than plain Workers.
  • The Worker is required. The container is not exposed directly on the public Internet.