Docker Compose

Self-contained docker-compose stacks for puddle. One directory per example, one docker-compose.yml per directory — catalog config, OPA policy, and Trino properties are inlined via Compose’s configs.content: so each file can be downloaded and run on its own. The OPA presets inline a verbatim copy of the starter policy in examples/opa/rbac.rego.

Browse the source on GitHub.

Run any of them

cd examples/compose/<name>
docker compose up

Or fetch a single file directly:

curl -O https://raw.githubusercontent.com/ragnard/puddle/main/examples/compose/<name>/docker-compose.yml
docker compose up

The catalog REST API is at http://localhost:8089/api/catalog. Trino-equipped examples expose Trino’s UI at http://localhost:8080.

Examples

Example	Auth	Storage	Client	What it shows
basic	none	local file	—	Single-container puddle
opa-local	static-token + OPA	local file	—	Three roles (admin/writer/reader)
trino-rustfs	none	rustfs (S3)	Trino	Anyone-can-everything S3 demo
trino-rustfs-opa	static-token + OPA	rustfs (S3)	Trino	Trino as `writer`, plus an `admin` catalog
trino-rustfs-opa-vending	static-token + OPA	rustfs (S3)	Trino	+ STS-vended per-table tokens
observability	none	local file	—	OpenTelemetry: collector, Jaeger, Prometheus, Grafana

The list reads as a complexity ladder — start at basic and add a concern at each step.

Image source

Each example pulls image: ghcr.io/ragnard/puddle:latest, which is the newest release. Pin a release for reproducibility:

docker-compose.yml

services:
  puddle:
    image: ghcr.io/ragnard/puddle:0.2.0

To run from local source instead, drop a sibling docker-compose.override.yml:

docker-compose.override.yml

services:
  puddle:
    image: puddle:local
    build: ../../..

Compose merges it automatically when both files are present.

The image runs as the non-root uid/gid 65532. The examples keep their SQLite database and file:// warehouse in the puddle-data named volume at /var/lib/puddle, which the image creates owned by that uid. If you swap it for a bind mount, chown 65532:65532 the host directory first.

Roll your own

Copy the closest example to a new directory and edit the docker-compose.yml. Everything you need — services, volumes, inlined puddle.yaml, OPA policy, Trino properties — is in one file, so changes don’t ripple across other files.