Initial import

Author: djthorpe

Dockerfile

@@ -0,0 +1,27 @@
+ARG VERSION=17-bookworm
+ARG OS
+ARG ARCH
+
+# Use the base image
+FROM postgres:${VERSION}
+
+LABEL org.opencontainers.image.description="PostgreSQL image with primary/replica support" \
+ org.opencontainers.image.source="https://github.com/mutablelogic/docker-postgres"
+
+# Install packages postgis and pgvector
+ENV POSTGIS_MAJOR=3
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+ ca-certificates \
+ postgresql-$PG_MAJOR-postgis-$POSTGIS_MAJOR \
+ postgresql-$PG_MAJOR-postgis-$POSTGIS_MAJOR-scripts \
+ postgresql-$PG_MAJOR-pgvector \
+ && rm -rf /var/lib/apt/lists/* 
+
+# Copy scripts
+RUN mkdir -p /docker-entrypoint-initdb.d
+COPY --chmod=755 ./scripts/10_primary.sh /docker-entrypoint-initdb.d
+COPY --chmod=755 ./scripts/20_replica.sh /docker-entrypoint-initdb.d
+
+# Set the environment
+ENV POSTGRES_REPLICATION_USER=replication \
+ POSTGRES_REPLICATION_SLOT=replica1

Makefile

@@ -0,0 +1,30 @@
+# Executables
+DOCKER ?= $(shell which docker 2>/dev/null)
+
+# Set OS and Architecture
+ARCH ?= $(shell arch | tr A-Z a-z | sed 's/x86_64/amd64/' | sed 's/i386/amd64/' | sed 's/armv7l/arm/' | sed 's/aarch64/arm64/')
+OS ?= $(shell uname | tr A-Z a-z)
+VERSION ?= 17-bookworm
+
+# Docker repository
+DOCKER_REPO ?= ghcr.io/mutablelogic/docker-postgres
+BUILD_TAG = ${DOCKER_REPO}-${OS}-${ARCH}:${VERSION}
+
+# Build the docker image
+.PHONY: docker
+docker: docker-dep
+@echo build docker image: ${BUILD_TAG} for ${OS}/${ARCH}
+@${DOCKER} build \
+--tag ${BUILD_TAG} \
+--build-arg ARCH=${ARCH} \
+--build-arg OS=${OS} \
+--build-arg VERSION=${VERSION} \
+-f Dockerfile .
+
+
+###############################################################################
+# DEPENDENCIES
+
+.PHONY: docker-dep
+docker-dep:
+@test -f "${DOCKER}" && test -x "${DOCKER}" || (echo "Missing docker binary" && exit 1)

README.md

@@ -1,2 +1,67 @@
-# docker-postgres
-PostgresSQL image with primary & replica support
+# PostgreSQL Dockerfile with primary and replica support
+
+PostgresSQL image with Primary & Replica support. In order to build the image, run:
+
+```bash
+DOCKER_REPO=ghcr.io/mutablelogic/docker-postgres make docker
+```
+
+Replacing the `DOCKER_REPO` with the repository you want to use.
+
+## Environment variables
+
+The image can be run as a primary or replica, depending on the environment variables passed on the
+docker command line:
+
+* `POSTGRES_REPLICATION_PRIMARY`: **Required for replica** The host and port that the replica will use
+ to connect to the primary, in the form `host=<hostname> port=5432`. When not set,
+ the instance role is a primary.
+* `POSTGRES_REPLICATION_PASSWORD`: **Required**: The password for the `POSTGRES_REPLICATION_USER`.
+* `POSTGRES_REPLICATION_USER`: **Default is `replicator`**: The user that the primary will use to connect
+ to the replica. 
+* `POSTGRES_REPLICATION_SLOT`: **Default is `replica1`** The replication slot for each replica.
+ On the primary, this is a comma-separated list of replication slots. On a replica, this is the name
+ of the replication slot used for syncronization.
+
+## Running a Primary server
+
+Example of running a primary instance, with two replication slots.
+You should change the password for the `POSTGRES_PASSWORD` and `POSTGRES_REPLICATION_PASSWORD`
+environment variables in this example:
+
+```bash
+docker volume create postgres-primary
+docker run \
+ --rm --name postgres-primary \
+ -e POSTGRES_REPLICATION_SLOT="replica1,replica2" \
+ -e POSTGRES_REPLICATION_PASSWORD="postgres" \
+ -e POSTGRES_PASSWORD="postgres" \
+ -p 5432:5432 \
+ -v postgres-primary:/var/lib/postgresql/data \
+ ghcr.io/mutablelogic/docker-postgres-darwin-amd64:17-bookworm
+```
+
+You can add additional replication slots later as needed.
+
+## Running a Replica server
+
+When you run a replica instance, the first time it runs it will backup from the primary instance and then start
+replication. You should change the password for the `POSTGRES_PASSWORD` and `POSTGRES_REPLICATION_PASSWORD`
+environment variables, and set the `POSTGRES_REPLICATION_PRIMARY` environment variable to the primary instance
+in this example:
+
+```bash
+docker volume create postgres-replica1
+docker run \
+ --rm --name postgres-replica1 \
+ -e POSTGRES_REPLICATION_PRIMARY="host=milou.lan port=5432" \
+ -e POSTGRES_REPLICATION_SLOT="replica1" \
+ -e POSTGRES_REPLICATION_PASSWORD="postgres" \
+ -e POSTGRES_PASSWORD="postgres" \
+ -p 5433:5432 \
+ -v postgres-replica1:/var/lib/postgresql/data \
+ ghcr.io/mutablelogic/docker-postgres-darwin-amd64:17-bookworm
+```
+
+A second replica (and so forth) can be run in the same way, but with a different port and volume name.
+You can run up to ten replicas by default.

scripts/10_primary.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -e
+
+# Script should only run on the primary node
+if [ ! -z "${POSTGRES_REPLICATION_PRIMARY}" ]; then
+ echo "Skipping primary initialisation on a replica."
+ exit 0
+fi
+
+# If there is no replication password, then quit
+if [ -z "${POSTGRES_REPLICATION_PASSWORD}" ]; then
+ echo "POSTGRES_REPLICATION_PASSWORD needs to be set."
+ exit 1
+fi
+
+# Make the data directory
+install -d "${PGDATA}" -o postgres -g postgres -m 700
+
+# Create the replication user
+psql -v ON_ERROR_STOP=1 --username "${POSTGRES_USER}" --dbname "${POSTGRES_DB}" <<-EOSQL
+ CREATE USER ${POSTGRES_REPLICATION_USER} WITH REPLICATION ENCRYPTED PASSWORD '${POSTGRES_REPLICATION_PASSWORD}';
+EOSQL
+
+# Create the replication slots
+IFS=',' read -r -a array <<< "${POSTGRES_REPLICATION_SLOT}"
+for SLOT in "${array[@]}"; do
+ psql -v ON_ERROR_STOP=1 --username "${POSTGRES_USER}" --dbname "${POSTGRES_DB}" <<-EOSQL
+ SELECT pg_create_physical_replication_slot('${SLOT}');
+EOSQL
+done
+
+# Set configuration for replication
+CONF="${PGDATA}/postgresql.conf"
+sed -i -e"s/^#wal_level.*$/wal_level=replica/" ${CONF}
+sed -i -e"s/^#max_wal_senders.*$/max_wal_senders=10/" ${CONF}
+sed -i -e"s/^#max_replication_slots.*$/max_replication_slots=10/" ${CONF}
+
+# Add the replication user to pg_hba.conf
+echo "host ${POSTGRES_REPLICATION_USER} all 0.0.0.0/0 scram-sha-256" >> "${PGDATA}/pg_hba.conf"

scripts/20_replica.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+set -e
+
+# Script should only run on the primary node
+if [ -z "${POSTGRES_REPLICATION_PRIMARY}" ]; then
+ echo "Skipping replica initialisation on a primary."
+ exit 0
+fi
+
+# If there is no replication password, then quit
+if [ -z "${POSTGRES_REPLICATION_PASSWORD}" ]; then
+ echo "POSTGRES_REPLICATION_PASSWORD needs to be set."
+ exit 1
+fi
+
+# Make the data directory
+install -d "${PGDATA}" -o postgres -g postgres -m 700
+
+# Set password for replication user
+echo "*:*:*:${POSTGRES_REPLICATION_USER}:${POSTGRES_REPLICATION_PASSWORD}" >> /var/lib/postgresql/.pgpass
+chmod 600 /var/lib/postgresql/.pgpass
+
+# Stop the server
+pg_ctl -D "${PGDATA}" stop -m fast
+
+# Perform the backup
+rm -fr ${PGDATA}/*
+pg_basebackup -v --pgdata="${PGDATA}" \
+ --write-recovery-conf \
+ --slot="${POSTGRES_REPLICATION_SLOT}" -X stream \
+ --dbname="${POSTGRES_REPLICATION_PRIMARY}" --username="${POSTGRES_REPLICATION_USER}" --no-password
+
+# Set configuration for replication
+CONF="${PGDATA}/postgresql.conf"
+sed -i -e"s/^#max_wal_senders.*$/max_wal_senders=10/" ${CONF}
+sed -i -e"s/^#max_replication_slots.*$/max_replication_slots=10/" ${CONF}
+sed -i -e"s/^#primary_conninfo.*$/primary_conninfo='user=${POSTGRES_REPLICATION_USER} ${POSTGRES_REPLICATION_PRIMARY}'/" ${CONF}
+sed -i -e"s/^#primary_slot_name.*$/primary_slot_name='${POSTGRES_REPLICATION_SLOT}'/" ${CONF}
+sed -i -e"s/^#hot_standby.*$/hot_standby=on/" ${CONF}
+sed -i -e"s/^#hot_standby_feedback.*$/hot_standby_feedback=on/" ${CONF}
+
+# Start the server
+pg_ctl -D "${PGDATA}" start