/docker-postgis

(test) Docker image for PostGIS

Primary LanguageShellMIT LicenseMIT

🚧🔧💡🧹 WIP: Experimental development:

🐳🐘🌍 postgis/postgis

Build Status Join the chat at https://gitter.im/postgis/docker-postgis

Important: Please note that this README document is larger than the 25,000 character limit set by Docker Hub. As a result, the version available on Docker Hub will be trimmed and not complete. For the complete and untrimmed version of the README, it is recommended to visit the project GitHub page: https://github.com/ImreSamu/docker-postgis/blob/master/README.md

The imresamu/postgis image provides tags for running Postgres with PostGIS extensions installed. This image is based on the official postgres image and provides debian and alpine variants for PostGIS 3.4.x, which is compatible with PostgreSQL versions 12, 13, 14, 15, 16 and 17beta. Additionally, an image version is provided which is built from the latest two versions of Postgres (15, 16) with versions of PostGIS and its dependencies built from their respective master branches.

This image ensures that the default database created by the parent postgres image will have the following extensions installed:

installed extensions initialized
postgis yes
postgis_topology yes
postgis_tiger_geocoder yes
postgis_raster
postgis_sfcgal
address_standardizer
address_standardizer_data_us

Unless -e POSTGRES_DB is passed to the container at startup time, this database will be named after the admin user (either postgres or the user specified with -e POSTGRES_USER). If you would prefer to use the older template database mechanism for enabling PostGIS, the image also provides a PostGIS-enabled template database called template_postgis.

Versions (2024-09-28)

We provide multi-platform image support for the following architectures:

  • amd64: Also known as x86-64.
    • Use --platform=linux/amd64 when specifying the platform.
  • arm64: Also known as AArch64.
    • Use --platform=linux/arm64 when specifying the platform.

Notes:

  • The arm64 architecture support is still experimental. Please refer to the 'arch' column in the version information to determine whether an arm64 version is available for a specific release.
  • We currently do not support 32-bit architectures. Our images are only available for 64-bit architectures.

Build Status

Arch Build system Status
Amd64 GithubCI-logs Build PostGIS images
Arm64 CircleCI-logs CircleCI

🌟Recommended Versions for New Users

For those new to PostGIS, we recommend the following image versions:

  • imresamu/postgis:16-3.4-bookworm: This image includes a minimal setup of PostgreSQL with the PostGIS extension. ( debian bookworm based, easy to extend with debian packages )
  • imresamu/postgis:16-recent-bookworm: (experimental) Latest postgis with the latest geos,proj,gdal,sfcgal. ( debian based, extending is complex ! )
  • imresamu/postgis:16-3.4-bundle0-bookworm: (experimental) This image includes additional geospatial-related extras along with PostgreSQL and PostGIS.

🥇Debian - bookworm (recommended)

  • This Docker-PostGIS version has a cautious release cycle to guarantee high stability.
    • By "cautious", we mean it does not always have the latest versions of geos, proj, gdal, and sfcgal packages.
  • We use PostGIS, geos, proj, gdal, and sfcgal packages from the Debian repository.
    • In the Debian Bullseye repository, the versions are: geos=3.11, gdal=3.6, proj=9.1, and sfcgal=1.4.
  • This version is easy to extend and has matured over time.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
12-3.4-bookworm, 12-3.4.3-bookworm, 12-3.4 Dockerfile amd64 arm64 bookworm 12 3.4.3
13-3.4-bookworm, 13-3.4.3-bookworm, 13-3.4 Dockerfile amd64 arm64 bookworm 13 3.4.3
14-3.4-bookworm, 14-3.4.3-bookworm, 14-3.4 Dockerfile amd64 arm64 bookworm 14 3.4.3
15-3.4-bookworm, 15-3.4.3-bookworm, 15-3.4 Dockerfile amd64 arm64 bookworm 15 3.4.3
16-3.4-bookworm, 16-3.4.3-bookworm, 16-3.4 Dockerfile amd64 arm64 bookworm 16 3.4.3

📘Debian - bullseye

  • We use PostGIS, geos, proj, gdal, and sfcgal packages from the Debian repository.
    • In the Debian Bullseye repository, the versions are: geos=3.9, gdal=3.2, proj=7.2, and sfcgal=1.3.9.
  • This version is easy to extend and has matured over time.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
12-3.4-bullseye, 12-3.4.3-bullseye Dockerfile amd64 arm64 bullseye 12 3.4.3
13-3.4-bullseye, 13-3.4.3-bullseye Dockerfile amd64 arm64 bullseye 13 3.4.3
14-3.4-bullseye, 14-3.4.3-bullseye Dockerfile amd64 arm64 bullseye 14 3.4.3
15-3.4-bullseye, 15-3.4.3-bullseye Dockerfile amd64 arm64 bullseye 15 3.4.3
16-3.4-bullseye, 16-3.4.3-bullseye Dockerfile amd64 arm64 bullseye 16 3.4.3

🧪Recent ( experimental )

  • These images are similar to the debian-based *-master images ( same Dockerfile template ) However, for every build, we use the latest released tag from each library (such as postgis, geos, proj, gdal, cgal, sfcgal).
  • These images are ideal for testing purposes, but expanding them is not straightforward.
  • The specific versions of the libraries used (like postgis, geos, proj, gdal, cgal, sfcgal) can be found in the tags of the image or in the Dockerfile.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
16-recent-bookworm, 16-recent-postgis3.5.0-geos3.13.0-proj9.5.0-gdal3.9.2-cgal5.6.1-sfcgal1.5.2-bookworm, 16-recent-postgis3.5-geos3.13-proj9.5-gdal3.9-cgal5.6-sfcgal1.5-bookworm, 16-recent Dockerfile amd64 arm64 bookworm 16 postgis=tags/3.5.0, geos=tags/3.13.0, proj=tags/9.5.0, gdal=tags/v3.9.2, cgal=tags/v5.6.1, sfcgal=tags/v1.5.2
17-recent-bookworm, 17-recent-postgis3.5.0-geos3.13.0-proj9.5.0-gdal3.9.2-cgal5.6.1-sfcgal1.5.2-bookworm, 17-recent-postgis3.5-geos3.13-proj9.5-gdal3.9-cgal5.6-sfcgal1.5-bookworm, 17-recent, recent Dockerfile amd64 arm64 bookworm 17 postgis=tags/3.5.0, geos=tags/3.13.0, proj=tags/9.5.0, gdal=tags/v3.9.2, cgal=tags/v5.6.1, sfcgal=tags/v1.5.2

🧪Debian Geo Bundle ( experimental )

This repository provides Debian-based PostGIS Docker images enriched with additional geospatial packages such as pgRouting, h3-pg, pgsql-ogr-fdw, MobilityDB, PL/Python3, pgPointcloud, pgVector, TimeScaleDB and others. These images serve as a comprehensive solution for various server side geospatial needs. Please note that the included package list is subject to change as we continue to refine the 'bundle0'.

docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
15-3.4-bundle0-bookworm, 15-3.4.3-bundle0-bookworm, 15-3.4-bundle0 Dockerfile amd64 arm64 bookworm 15 3.4.3
16-3.4-bundle0-bookworm, 16-3.4.3-bundle0-bookworm, 16-3.4-bundle0 Dockerfile amd64 arm64 bookworm 16 3.4.3

⛰️Alpine 3.19 based

  • The base operating system is Alpine Linux. It is designed to be small, simple, and secure, and it's based on musl libc.
  • In the Alpine 3.19 version, the package versions are: geos=3.12.1, gdal=3.8.1, proj=9.3.1, and sfcgal=1.5.0
  • PostGIS is compiled from source, making it a bit more challenging to extend.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
12-3.4-alpine3.19, 12-3.4.3-alpine3.19 Dockerfile amd64 arm64 alpine3.19 12 3.4.3
12-3.5-alpine3.19, 12-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 12 3.5.0
13-3.4-alpine3.19, 13-3.4.3-alpine3.19 Dockerfile amd64 arm64 alpine3.19 13 3.4.3
13-3.5-alpine3.19, 13-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 13 3.5.0
14-3.4-alpine3.19, 14-3.4.3-alpine3.19 Dockerfile amd64 arm64 alpine3.19 14 3.4.3
14-3.5-alpine3.19, 14-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 14 3.5.0
15-3.4-alpine3.19, 15-3.4.3-alpine3.19 Dockerfile amd64 arm64 alpine3.19 15 3.4.3
15-3.5-alpine3.19, 15-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 15 3.5.0
16-3.4-alpine3.19, 16-3.4.3-alpine3.19 Dockerfile amd64 arm64 alpine3.19 16 3.4.3
16-3.5-alpine3.19, 16-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 16 3.5.0
17-3.5-alpine3.19, 17-3.5.0-alpine3.19 Dockerfile amd64 arm64 alpine3.19 17 3.5.0

⛰️Alpine 3.20 based

  • The base operating system is Alpine Linux. It is designed to be small, simple, and secure, and it's based on musl libc.
  • In the Alpine 3.20 version, the package versions are: geos=3.12.1, gdal=3.9.0, proj=9.4.0, and sfcgal=1.5.1
  • PostGIS is compiled from source, making it a bit more challenging to extend.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
12-3.3-alpine3.20, 12-3.3.7-alpine3.20, 12-3.3-alpine Dockerfile amd64 arm64 alpine3.20 12 3.3.7
12-3.4-alpine3.20, 12-3.4.3-alpine3.20, 12-3.4-alpine Dockerfile amd64 arm64 alpine3.20 12 3.4.3
12-3.5-alpine3.20, 12-3.5.0-alpine3.20, 12-3.5-alpine Dockerfile amd64 arm64 alpine3.20 12 3.5.0
13-3.3-alpine3.20, 13-3.3.7-alpine3.20, 13-3.3-alpine Dockerfile amd64 arm64 alpine3.20 13 3.3.7
13-3.4-alpine3.20, 13-3.4.3-alpine3.20, 13-3.4-alpine Dockerfile amd64 arm64 alpine3.20 13 3.4.3
13-3.5-alpine3.20, 13-3.5.0-alpine3.20, 13-3.5-alpine Dockerfile amd64 arm64 alpine3.20 13 3.5.0
14-3.3-alpine3.20, 14-3.3.7-alpine3.20, 14-3.3-alpine Dockerfile amd64 arm64 alpine3.20 14 3.3.7
14-3.4-alpine3.20, 14-3.4.3-alpine3.20, 14-3.4-alpine Dockerfile amd64 arm64 alpine3.20 14 3.4.3
14-3.5-alpine3.20, 14-3.5.0-alpine3.20, 14-3.5-alpine Dockerfile amd64 arm64 alpine3.20 14 3.5.0
15-3.3-alpine3.20, 15-3.3.7-alpine3.20, 15-3.3-alpine Dockerfile amd64 arm64 alpine3.20 15 3.3.7
15-3.4-alpine3.20, 15-3.4.3-alpine3.20, 15-3.4-alpine Dockerfile amd64 arm64 alpine3.20 15 3.4.3
15-3.5-alpine3.20, 15-3.5.0-alpine3.20, 15-3.5-alpine Dockerfile amd64 arm64 alpine3.20 15 3.5.0
16-3.3-alpine3.20, 16-3.3.7-alpine3.20, 16-3.3-alpine Dockerfile amd64 arm64 alpine3.20 16 3.3.7
16-3.4-alpine3.20, 16-3.4.3-alpine3.20, 16-3.4-alpine Dockerfile amd64 arm64 alpine3.20 16 3.4.3
16-3.5-alpine3.20, 16-3.5.0-alpine3.20, 16-3.5-alpine Dockerfile amd64 arm64 alpine3.20 16 3.5.0
17-3.4-alpine3.20, 17-3.4.3-alpine3.20, 17-3.4-alpine, alpine Dockerfile amd64 arm64 alpine3.20 17 3.4.3
17-3.5-alpine3.20, 17-3.5.0-alpine3.20, 17-3.5-alpine Dockerfile amd64 arm64 alpine3.20 17 3.5.0

🧪Locked ( experimental )

  • Locked old postgis versions for testing.
  • Definition in the ./locked.yml
    • and the image identifiers : <pg_version>-l<any_unique_postgis_id>
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
14-l3.1.9gcp-bookworm, 14-l3.1.9gcp-postgis3.1.9-geos3.6.6-proj6.3.1-bookworm Dockerfile amd64 arm64 bookworm 14 postgis=tags/3.1.9, geos=tags/3.6.6, proj=tags/6.3.1, gdal=tags/v3.6.4, cgal=tags/v5.6, sfcgal=tags/v1.5.1

📋Test images

  • We provide alpha, beta, release candidate (rc), and development (identified as ~master) versions.
  • The template for the *-master images is updated manually, which might lead to a delay of a few weeks sometimes.
  • The ~master SFCGAL version is 1.5 or higher. The cgal version is locked on the 5.6.x-branch.
docker.io/imresamu/postgis: tags Dockerfile Arch OS Postgres PostGIS
16-master-bookworm, 16-master Dockerfile amd64 arm64 bookworm 16 development: postgis, geos, proj, gdal, cgal, sfcgal
17-master-bookworm, 17-master Dockerfile amd64 arm64 bookworm 17 development: postgis, geos, proj, gdal, cgal, sfcgal

🚀Usage

In order to run a basic container capable of serving a PostGIS-enabled database, start a container as follows:

docker run --name some-postgis -e POSTGRES_PASSWORD=mysecretpassword -d imresamu/postgis

For more detailed instructions about how to start and control your Postgres container, see the documentation for the postgres image here.

Once you have started a database container, you can then connect to the database either directly on the running container:

docker exec -ti some-postgis psql -U postgres

... or starting a new container to run as a client. In this case you can use a user-defined network to link both containers:

docker network create some-network

# Server container
docker run --name some-postgis --network some-network -e POSTGRES_PASSWORD=mysecretpassword -d imresamu/postgis

# Client container
docker run -it --rm --network some-network imresamu/postgis psql -h some-postgis -U postgres

Check the documentation on the postgres image and Docker networking for more details and alternatives on connecting different containers.

See the PostGIS documentation for more details on your options for creating and using a spatially-enabled database.

🔧Supported Environment Variables:

Since the docker-postgis repository is an extension of the official Docker PostgreSQL repository, all environment variables supported there are also supported here:

  • POSTGRES_PASSWORD
  • POSTGRES_USER
  • POSTGRES_DB
  • POSTGRES_INITDB_ARGS
  • POSTGRES_INITDB_WALDIR
  • POSTGRES_HOST_AUTH_METHOD
  • PGDATA

Read more: https://github.com/docker-library/docs/blob/master/postgres/README.md

Warning: the Docker specific variables will only have an effect if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup.

It's important to note that the environment variables for the Docker image are different from those of the libpq — C Library (PGDATABASE,PGUSER,PGPASSWORD )

⚠️ Troubleshooting tips:

Troubleshooting can often be challenging. It's important to know that the docker-postgis repository is an extension of the official Docker PostgreSQL repository. Therefore, if you encounter any issues, it's worth testing whether the problem can be reproduced with the official PostgreSQL Docker images. If so, it's recommended to search for solutions based on this. The following websites are suggested:

If your problem is Postgis related:

And if you don't have a postgres docker experience - read this blog post:

🔒Security

It's crucial to be aware that in a cloud environment, with default settings, these images are vulnerable, and there's a high risk of cryptominer infection if the ports are left open. ( Read More )

  • Note that ports which are not bound to the host (i.e., -p 5432:5432 instead of -p 127.0.0.1:5432:5432) will be accessible from the outside. This also applies if you configured UFW to block this specific port, as Docker manages its own iptables rules. ( Read More )

Recomendations:

  • You can add options for using SSL ( see postgres example )
    • -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
  • Or you can use SSH Tunnels with -p 127.0.0.1:5432:5432

Security scanner information:

Limitations on Updates:

Unfortunately, we don't have control over updates to Debian and Alpine distributions or the upstream postgres image. Because of this, there might be some issues that we cannot fix right away. On the positive side, the postgis/postgis images are regenerated every Monday. This process is to ensure they include the latest changes and improvements. As a result, these images are consistently kept up-to-date.

Suggestions Welcome:

We are always open to suggestions to enhance security. If you have any ideas, please let us know.

❗Known Issues / Errors

When You encouter errors due to PostGIS update OperationalError: could not access file "$libdir/postgis-X.X, run:

docker exec some-postgis update-postgis.sh

It will update to Your newest PostGIS. Update is idempotent, so it won't hurt when You run it more than once, You will get notification like:

Updating PostGIS extensions template_postgis to X.X.X
NOTICE:  version "X.X.X" of extension "postgis" is already installed
NOTICE:  version "X.X.X" of extension "postgis_topology" is already installed
NOTICE:  version "X.X.X" of extension "postgis_tiger_geocoder" is already installed
ALTER EXTENSION
Updating PostGIS extensions docker to X.X.X
NOTICE:  version "X.X.X" of extension "postgis" is already installed
NOTICE:  version "X.X.X" of extension "postgis_topology" is already installed
NOTICE:  version "X.X.X" of extension "postgis_tiger_geocoder" is already installed
ALTER EXTENSION