Running dbmazz with Docker

The ez-cdc CLI is the recommended path for most users — it bundles the demo, the live dashboard, and the e2e verification suite. If you'd rather run the daemon directly — CI pipelines, Kubernetes, custom orchestration, or as a sidecar to your application — the official Docker image is a single docker run away.

Pull the image

Official images are published to GitHub Container Registry on every release.

docker pull ghcr.io/ez-cdc/dbmazz:latest

Tags follow semver: pin to a specific version (e.g. v2.1.0) for reproducible deploys, or use latest for the most recent stable release. Both linux/amd64 and linux/arm64 are published.

Run

A minimal CDC pipeline needs four environment variables:

docker run --rm \
  -e SOURCE_URL='postgresql://user:pass@source-host:5432/mydb' \
  -e SINK_URL='http://sink-host:8030' \
  -e SINK_TYPE=starrocks \
  -e SINK_DATABASE=analytics \
  -p 50051:50051 \
  ghcr.io/ez-cdc/dbmazz:latest

The container starts streaming CDC events immediately. Port 50051 exposes the control API (healthcheck, status, metrics).

Required configuration

Variable	Required	Description
SOURCE_URL	yes	PostgreSQL connection string for the source DB
SINK_URL	yes	Target sink URL
SINK_TYPE	yes	starrocks, postgres, or snowflake
SINK_DATABASE	yes	Database / schema name on the sink

For the full env var reference — snapshot tuning, batch sizes, sink-specific settings, replication slot and publication overrides — see docs/configuration.md in the dbmazz repository.

Stateless by design

dbmazz persists its LSN checkpoint inside the source PostgreSQL database (table dbmazz_checkpoints), not on local disk. The container itself is stateless: you can stop, replace, or restart it without losing position in the WAL. No volume mounts are required.

Healthcheck

The image ships with a built-in Docker HEALTHCHECK that polls the control API at /api/v1/health every 10 seconds. You can also hit it manually:

curl -sf http://127.0.0.1:50051/api/v1/health

If you publish the daemon behind a load balancer or orchestrator, point its liveness probe at the same path.

Build your own image

The Dockerfile in the dbmazz repository is what produces the official image. To build a custom image (for example, with a patched binary), pre-compile the binary against musl and feed it into the build context:

cargo build --release --target x86_64-unknown-linux-musl
cp target/x86_64-unknown-linux-musl/release/dbmazz dbmazz-linux-amd64
docker buildx build --platform linux/amd64 -t dbmazz:local .

The image is fully static (musl libc, vendored openssl, static curl), so no extra runtime dependencies are baked in beyond ca-certificates.

Where to next

• CLI — ez-cdc: the recommended interactive workflow, with bundled demo, dashboard, and verification suite.
• Adding connectors: implement a new sink in six trait methods.