Quickly Set Up PostgreSQL HA with the Bitnami postgresql-repmgr Docker Image

Overview

Bitnami postgresql-repmgr Docker image bundles PostgreSQL with the open‑source Replication Manager (repmgr) for streaming replication and automatic failover, enabling a high‑availability PostgreSQL cluster.

Pulling the image

Retrieve the pre‑built image from Docker Hub: $ docker pull bitnami/postgresql-repmgr:latest Specific versions can be pulled by replacing latest with a tag listed in the Docker Hub registry, e.g.:

$ docker pull bitnami/postgresql-repmgr:[TAG]

Building the image

If a custom build is required, use the source repository:

$ docker build -t bitnami/postgresql-repmgr:latest 'https://github.com/bitnami/bitnami-docker-postgresql-repmgr.git#master:14/debian-10'

Persisting data

Mount a host directory to /bitnami/postgresql so that data survives container removal:

$ docker run \
    -v /path/to/postgresql-repmgr-persistence:/bitnami/postgresql \
    bitnami/postgresql-repmgr:latest

Because the container runs as a non‑root user, the mounted directory must be owned by UID 1001 .

Docker network

Create a bridge network and attach the containers:

$ docker network create my-network --driver bridge

Run the primary node:

$ docker run --detach --name pg-0 \
  --network my-network \
  --env REPMGR_PARTNER_NODES=pg-0 \
  --env REPMGR_NODE_NAME=pg-0 \
  --env REPMGR_NODE_NETWORK_NAME=pg-0 \
  --env REPMGR_PRIMARY_HOST=pg-0 \
  --env REPMGR_PASSWORD=repmgrpass \
  --env POSTGRESQL_PASSWORD=secretpass \
  bitnami/postgresql-repmgr:latest

Run a standby node:

$ docker run --detach --name pg-1 \
  --network my-network \
  --env REPMGR_PARTNER_NODES=pg-0,pg-1 \
  --env REPMGR_NODE_NAME=pg-1 \
  --env REPMGR_NODE_NETWORK_NAME=pg-1 \
  --env REPMGR_PRIMARY_HOST=pg-0 \
  --env REPMGR_PASSWORD=repmgrpass \
  --env POSTGRESQL_PASSWORD=secretpass \
  bitnami/postgresql-repmgr:latest

These commands start a two‑node primary/standby streaming‑replication cluster that can be expanded without downtime.

Docker Compose alternative

Download the provided docker-compose.yml and start the stack:

$ curl -sSL https://raw.githubusercontent.com/bitnami/bitnami-docker-postgresql-repmgr/master/docker-compose.yml > docker-compose.yml
$ docker-compose up -d

Initialization

On first start the container executes scripts in /docker-entrypoint-initdb.d with extensions .sh, .sql, or .sql.gz. Custom scripts can be supplied by mounting a volume.

Set the superuser password via POSTGRESQL_PASSWORD and the repmgr password via REPMGR_PASSWORD when the container first runs:

$ docker run --name pg-0 \
    --env REPMGR_PASSWORD=repmgrpass \
    --env POSTGRESQL_PASSWORD=secretpass \
    bitnami/postgresql-repmgr:latest

To create a non‑privileged database user, provide POSTGRESQL_USERNAME (and optionally POSTGRESQL_DATABASE).

Creating a database at first run is possible by setting POSTGRESQL_DATABASE:

$ docker run --name pg-0 --env POSTGRESQL_DATABASE=my_database bitnami/postgresql-repmgr:latest

Creating a restricted user for the created database is possible by setting POSTGRESQL_USERNAME together with POSTGRESQL_PASSWORD and POSTGRESQL_DATABASE:

$ docker run --name pg-0 \
    --env POSTGRESQL_USERNAME=my_user \
    --env POSTGRESQL_PASSWORD=password123 \
    --env POSTGRESQL_DATABASE=my_database \
    bitnami/postgresql-repmgr:latest

Streaming replication and HA

Configure streaming replication and automatic failover with the following environment variables: REPMGR_PRIMARY_HOST: hostname of the primary node. REPMGR_PARTNER_NODES: comma‑separated list of all nodes in the cluster. REPMGR_NODE_NAME and REPMGR_NODE_NETWORK_NAME: identifiers for each node. REPMGR_PASSWORD and POSTGRESQL_PASSWORD: passwords for the repmgr and postgres users.

The cluster can have one primary (read‑write) and any number of standby (read‑only) nodes; reads are typically directed to standbys for better performance.

For PostgreSQL versions prior to 9.6, REPMGR_USE_PASSFILE and REPMGR_PASSFILE_PATH are ignored.

TLS encryption

Enable TLS by setting POSTGRESQL_ENABLE_TLS=yes and mounting certificate files:

$ docker run \
    -v /path/to/certs:/opt/bitnami/postgresql/certs \
    -e POSTGRESQL_ENABLE_TLS=yes \
    -e POSTGRESQL_TLS_CERT_FILE=/opt/bitnami/postgresql/certs/postgres.crt \
    -e POSTGRESQL_TLS_KEY_FILE=/opt/bitnami/postgresql/certs/postgres.key \
    bitnami/postgresql-repmgr:latest

The same variables can be added to a docker‑compose.yml file to enable TLS in a compose deployment.

Configuration files

Configuration files reside under /opt/bitnami/repmgr/conf/ and /opt/bitnami/postgresql/conf/. To replace or extend postgresql.conf, repmgr.conf, and pg_hba.conf, mount a custom directory to the appropriate path. Because the container runs as a non‑root user, ensure the host directory has group ownership UID 1001 and appropriate permissions (e.g.,

chgrp -R 1001 /path/to/custom-conf && chmod -R g+rwX /path/to/custom-conf

).

Logs

Container logs are sent to stdout. View them with: $ docker logs pg-0 The logging backend can be changed with Docker’s --log-driver option (default is json-file).

Upgrade procedure

Pull the new image: $ docker pull bitnami/postgresql-repmgr:latest Stop the running containers (or use docker-compose stop).

Snapshot the persistent volume, for example with

rsync -a /path/to/postgresql-persistence /path/to/postgresql-persistence.bkp.$(date +%Y%m%d-%H.%M.%S)

.

Remove the old containers (or docker-compose rm -v).

Start new containers with the updated image, using the same run commands or docker-compose up -d.