Docker Development Environment

PostGIS has two container families that are useful for development and testing. Production images are documented separately at https://github.com/postgis/docker-postgis and should not be treated as build environments.

OSGeo Build-Test Images

The OSGeo development images are hosted at repo.osgeo.org/postgis/build-test. They contain multiple PostgreSQL versions and preinstalled PostGIS versions for upgrade testing. They are large, but useful for testing dependency combinations and older upgrade paths.

docker pull repo.osgeo.org/postgis/build-test:universal
mkdir -p ~/projects
docker run -d \
  --name postgis-dev \
  --mount type=bind,source="$HOME/projects",target=/projects \
  -p 6432:5432/tcp \
  -p 6433:5433/tcp \
  -p 6434:5434/tcp \
  -p 6435:5435/tcp \
  -p 6436:5436/tcp \
  -p 6437:5437/tcp \
  repo.osgeo.org/postgis/build-test:universal tail -f /dev/null
docker exec -it postgis-dev /bin/bash

Inside the container:

cd /projects
git clone https://gitea.osgeo.org/postgis/postgis.git
cd postgis
export PGVER=15
service postgresql start "${PGVER}"
export PGPORT="$(grep ^port /etc/postgresql/${PGVER}/main/postgresql.conf | awk '{print $3}')"
export PATH="/usr/lib/postgresql/${PGVER}/bin:${PATH}"
./autogen.sh
./configure
make -j"$(nproc)"
make check

For interactive debugging, keep the container alive and enter it with:

docker exec -it postgis-dev /bin/bash
pg_lsclusters

pg_lsclusters shows which PostgreSQL major uses each port inside the container. To connect from the host, expose the matching port in docker run, allow PostgreSQL to listen beyond the container loopback interface, and reload the cluster:

export PGVER=15
export PGPORT="$(grep ^port /etc/postgresql/${PGVER}/main/postgresql.conf | awk '{print $3}')"
psql -d postgres -c "ALTER SYSTEM SET listen_addresses='*';"
printf '%s\n' "host all all 0.0.0.0/0 scram-sha-256" >> "/etc/postgresql/${PGVER}/main/pg_hba.conf"
psql -d postgres -c "ALTER ROLE postgres PASSWORD 'change-me';"
service postgresql restart "${PGVER}"

Use a stronger password and narrower pg_hba.conf rule on shared hosts. The example is intended for a short-lived local development container.

From the host, connect to the PostgreSQL version whose container port you exposed. For example, if PostgreSQL inside the container listens on 5436 and the host port mapping is 6436:5436, use:

psql -U postgres -h localhost -p 6436

Stop and remove the container with:

docker stop postgis-dev
docker rm postgis-dev

postgis-build-env Images

The postgis/postgis-build-env images are used by GitHub Actions. They contain the dependencies needed to compile PostGIS, but do not install PostGIS as a ready-to-use database image.

docker pull postgis/postgis-build-env:latest
mkdir -p ~/projects
# The container expects the PostGIS checkout at /projects/postgis. Reuse an
# existing checkout there, or clone one before starting the container.
test -d "$HOME/projects/postgis/.git" || \
  git clone https://gitea.osgeo.org/postgis/postgis.git "$HOME/projects/postgis"
docker run -d \
  --name postgis-build-env \
  -v "$HOME/projects:/projects" \
  postgis/postgis-build-env:latest tail -f /dev/null
docker exec -it postgis-build-env /bin/bash

Inside the container, prefer an out-of-tree build when iterating:

SRCDIR=/projects/postgis
BUILDDIR=/src/postgis
cd "${SRCDIR}"
./autogen.sh
mkdir -p "${BUILDDIR}"
cd "${BUILDDIR}"
"${SRCDIR}/configure" --without-interrupt-tests --enable-lto
make -j"$(nproc)"
/usr/local/pgsql/bin/pg_ctl -c -l /tmp/logfile -o '-F' start
make check

Use these images for development and CI reproduction, not production service deployment.