Sign inSign up

nextstage/postgres

By nextstage

•Updated 8 days ago

Image
1

10K+

nextstage/postgres repository overview

⁠nextstage/postgres-ha

Production-ready PostgreSQL image with:

  • Streaming replication support (primary/standby)
  • PostGIS preinstalled
  • Restore and seed hooks on first boot

This README is a Docker Hub consumer guide.

⁠Quick start (single node)

docker pull nextstage/postgres-ha:18

docker run -d --name postgres-ha \
  -e POSTGRES_PASSWORD='StrongPasswordHere' \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/18/docker \
  nextstage/postgres-ha:18

Test connection:

psql "postgresql://postgres:[email protected]:5432/postgres"

⁠Environment variables

VariableDefaultNotes
POSTGRES_USERpostgresMain admin user.
POSTGRES_PASSWORDNOTDEFINEDSet a strong password in production.
PG_PASSWORD_ENCRYPTIONscram-sha-256Auth method used in generated pg_hba.conf.
REPLICATION_MODEmastermaster or slave.
REPLICATION_USERreplicatorReplication user name.
REPLICATION_PASSWORDNONE:16Must be explicitly set for replication to work.
REPLICATION_HOST(empty)Required on standby (slave) to point to primary host/service.
REPLICATION_PORT5432Primary PostgreSQL port used by standby.

⁠Persistent volumes and container paths

Path in containerPurpose
/var/lib/postgresql/18/dockerMain data directory (PG18+). Persist this path.
/etc/postgresql/18/main/conf.dExtra PostgreSQL config files.
/to-restoreOptional backups and seed files (*.backup, *.seed.sql).
/pg_tablespace/indexOptional index tablespace disk.
/pg_tablespace/tmpOptional temp tablespace disk.

⁠Docker Compose example (based on stack installer)

services:
  db_master:
    image: nextstage/postgres-ha:18
    container_name: db_master_18
    restart: always
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      REPLICATION_MODE: master
      PG_PASSWORD_ENCRYPTION: scram-sha-256
      REPLICATION_USER: replicator
      REPLICATION_PASSWORD: ${REPLICATION_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - ./persist/master:/var/lib/postgresql/18/docker
      - ./conf/master:/etc/postgresql/18/main/conf.d
      - ./backups:/to-restore
    healthcheck:
      test: ["CMD-SHELL", "/scripts/healthcheck.sh"]
      interval: 10s
      timeout: 5s
      retries: 30

⁠Replication example (primary + standby)

services:
  db_master:
    image: nextstage/postgres-ha:18
    container_name: db_master_18
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      REPLICATION_MODE: master
      REPLICATION_USER: replicator
      REPLICATION_PASSWORD: ${REPLICATION_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - ./persist/master:/var/lib/postgresql/18/docker
    healthcheck:
      test: ["CMD-SHELL", "/scripts/healthcheck.sh"]
      interval: 10s
      timeout: 5s
      retries: 60

  db_slave:
    image: nextstage/postgres-ha:18
    container_name: db_slave_18
    depends_on:
      db_master:
        condition: service_healthy
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      REPLICATION_MODE: slave
      REPLICATION_USER: replicator
      REPLICATION_PASSWORD: ${REPLICATION_PASSWORD}
      REPLICATION_HOST: db_master
      REPLICATION_PORT: 5432
    ports:
      - "5433:5432"
    volumes:
      - ./persist/slave:/var/lib/postgresql/18/docker

⁠Failover: promote standby to primary

docker exec -it db_slave_18 bash /scripts/promoteToMaster.sh

After promotion, update deployment variables so this node runs with REPLICATION_MODE=master.

⁠Restore and seed

When a database is created (for example with /scripts/createDatabase.sh), the image checks /to-restore for files that match the database name:

  • /to-restore/<database>.backup
  • /to-restore/<database>.seed.sql

Behavior:

  1. Restores <database>.backup when present
  2. Executes <database>.seed.sql when present

⁠Security notes

  • Always set strong values for POSTGRES_PASSWORD and REPLICATION_PASSWORD
  • Expose database ports only when necessary
  • Restrict network access with firewall/security groups/policies

Tag summary

Content type

Image

Digest

sha256:648bcf93a…

Size

255.3 MB

Last updated

8 days ago

docker pull nextstage/postgres:18-ha