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.

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 auths as `writer`
trino-rustfs-opa-vending	static-token + OPA	rustfs (S3)	Trino	+ STS-vended per-table tokens

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 tracks main. Pin to a specific CalVer tag for reproducibility:

docker-compose.yml

services:
  puddle:
    image: ghcr.io/ragnard/puddle:2026.05.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.

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.