docker-compose.yml

# All-in-one Multigres cluster for local development and CI compatibility
# testing. Brings up a single container that bootstraps a full Multigres
# cluster (etcd + multiadmin + per-cell pgctld/postgres, multipooler,
# multiorch, multigateway) via the "local" provisioner and exposes the zone1
# multigateway on the PostgreSQL wire protocol.
#
#   docker compose up --build       # start the cluster
#   PGPASSWORD=postgres psql -h 127.0.0.1 -p 15432 -U postgres -d postgres
#   docker compose down             # stop and remove the container
#
# The cluster is ephemeral by default (no volume) so every run starts clean.
# See docker/README.md for adding a persistent volume.
services:
  multigres:
    build:
      context: .
      dockerfile: Dockerfile.cluster
      args:
        # PostgreSQL base image to build the cluster on. Defaults to the
        # official Debian postgres. Point it at a prebuilt image that already
        # bundles the required extensions + pgBackRest and set
        # MULTIGRES_PROVISION_PG_PACKAGES=false to skip the apt provisioning,
        # which only works on the Debian base.
        POSTGRES_IMAGE: "${MULTIGRES_POSTGRES_IMAGE:-postgres:17.7}"
        PROVISION_PG_PACKAGES: "${MULTIGRES_PROVISION_PG_PACKAGES:-true}"
    image: multigres-cluster:local
    # Run a real init (tini) as PID 1 to reap the cluster's orphaned child
    # processes and forward signals to the entrypoint.
    init: true
    environment:
      # Number of cells (full stacks: PostgreSQL + pgctld, multipooler,
      # multiorch, multigateway). Minimum is 2 — the shard bootstraps with an
      # AtLeastN(2) durability policy, so a single pooler can never elect a
      # leader. Supported range is 2-3 (3 tolerates losing a node). Cells beyond
      # the first use offset ports (gateway PG 15433, 15434) which you would
      # need to publish below to reach them from the host.
      MULTIGRES_NUM_CELLS: "2"
      # Port the zone1 multigateway serves PostgreSQL on. Set to 5432 to use the
      # container as a drop-in PostgreSQL on the default port (e.g. for a setup
      # that hardcodes 5432). Keep ports/healthcheck below in sync.
      MULTIGRES_GATEWAY_PG_PORT: "15432"
      # PostgreSQL max_connections (default 60). Raising it also sizes the
      # connection pooler to this value minus 10. Forwarded from the host env so
      # CI / callers can override it without editing this file; empty = default.
      MULTIGRES_PG_MAX_CONNECTIONS: "${MULTIGRES_PG_MAX_CONNECTIONS:-}"
      # Extra raw postgresql.conf text (one setting per line), appended to every
      # cell's config at first init. This is how you set startup-only GUCs like
      # shared_preload_libraries (e.g. to load pg_cron/pg_net). Forwarded from
      # the host env like the knob above; empty = none.
      MULTIGRES_PG_EXTRA_CONF: "${MULTIGRES_PG_EXTRA_CONF:-}"
    ports:
      - "15432:15432" # zone1 multigateway — PostgreSQL wire protocol
      - "15100:15100" # multigateway HTTP (status/metrics)
      - "15000:15000" # multiadmin HTTP (status/metrics)
    healthcheck:
      # Uses ${MULTIGRES_GATEWAY_PG_PORT} (defaulted to 15432 if unset) so the
      # probe follows the gateway whenever the port is reconfigured above.
      test:
        - "CMD-SHELL"
        # ${MULTIGRES_GATEWAY_PG_PORT} is interpolated by compose from the host
        # env (it mirrors the port configured above). $${POSTGRES_USER} is
        # escaped ($$) so compose passes it through literally for the container
        # shell to expand against the image's env — defaulting to postgres, but
        # following a base image that sets POSTGRES_USER to a custom superuser.
        - 'PGPASSWORD=postgres psql -h 127.0.0.1 -p "${MULTIGRES_GATEWAY_PG_PORT:-15432}" -U "$${POSTGRES_USER:-postgres}" -d postgres -tAc ''SELECT 1'' || exit 1'
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 60s