NOTE: I'm still experimenting with things in this repo!

docker-postgres-rdkit

This project creates PostgreSQL docker images with the RDKit cartridge built and installed. A single main branch and a declarative matrix in versions.json drive the builds; GitHub Actions rebuilds the matrix daily and skips any tag that is already published. Images are pushed to the GitHub Container Registry (GHCR).

The image is based on the Dockerfile by rvianello.

How to Use

Assuming you have docker installed, you can pull the image using:

docker pull ghcr.io/radusuciu/docker-postgres-rdkit/postgres-rdkit:<tag>

Tags follow these rules. For the default Debian suite (the debian key in versions.json, currently bookworm):

Tag	Meaning
postgres-<pg_point>-rdkit-<rdkit>	Reproducible pin, e.g. postgres-17.11-rdkit-2026_03_6.
postgres-<pg_major>-rdkit-<rdkit>	Moving; pushed only when the build's point release is the current one for that major.
latest	Only the newest (RDKit, PostgreSQL) pair, and only when it is current.

For a build of any other Debian suite, the point tag gains a -<suite> suffix (postgres-<pg_point>-rdkit-<rdkit>-<suite>) and no moving major tag and no latest are pushed.

This is deliberate: an on-demand build must never re-point a tag the automatic matrix owns. The automatic matrix itself is single-suite, so a non-default suite is only reachable through make ... DEBIAN=<suite> locally or the Build images workflow's debian workflow_dispatch input.

The "Available Versions" table below lists the pairs that are currently rebuilt automatically. For the complete list of published tags, including older releases and on-demand builds, see this repository's GHCR package page, linked from the "Packages" section in the repository sidebar.

Every image also carries provenance labels -- notably org.rdkit.pickle-version, which is the actual client/server compatibility contract: your client's RDKit must be at least the cartridge's RDKit, or a newer pickle format will be read with only a warning and produce corrupt results. Inspect the labels with docker image inspect --format '{{json .Config.Labels}}' <image>.

To run the Docker container, use:

docker run -d -e POSTGRES_PASSWORD=<password> -p 5432:5432 ghcr.io/radusuciu/docker-postgres-rdkit/postgres-rdkit:<tag>

Replace with the version tag of the Docker image.

Available Versions

This table is generated from versions.json and shows only the (PostgreSQL, RDKit) pairs in the automatic build matrix, with the point release each major currently resolves to. It is regenerated daily and does not accumulate history: pairs removed from versions.json drop out, and images that were only built on demand never appear. Each row's tag is the moving major tag; the matching reproducible pin is postgres-<pg_point>-rdkit-<rdkit>.

RDKit 2024_09_6 is held in the matrix for managed-service parity rather than because it is current: it is the cartridge version Amazon RDS and Aurora for PostgreSQL ship, so those rows let you run locally against the same RDKit a managed deployment gives you.

PostgreSQL	RDKit	Tag
18.6	2026_03_6	postgres-18-rdkit-2026_03_6
17.11	2026_03_6	postgres-17-rdkit-2026_03_6
16.15	2026_03_6	postgres-16-rdkit-2026_03_6
15.19	2026_03_6	postgres-15-rdkit-2026_03_6
14.24	2026_03_6	postgres-14-rdkit-2026_03_6
18.6	2025_09_6	postgres-18-rdkit-2025_09_6
17.11	2025_09_6	postgres-17-rdkit-2025_09_6
16.15	2025_09_6	postgres-16-rdkit-2025_09_6
15.19	2025_09_6	postgres-15-rdkit-2025_09_6
14.24	2025_09_6	postgres-14-rdkit-2025_09_6
18.6	2024_09_6	postgres-18-rdkit-2024_09_6
17.11	2024_09_6	postgres-17-rdkit-2024_09_6
16.15	2024_09_6	postgres-16-rdkit-2024_09_6
15.19	2024_09_6	postgres-15-rdkit-2024_09_6
14.24	2024_09_6	postgres-14-rdkit-2024_09_6

Configuration

This image is based on the official postgres image, see here for details on configuration.

For details on use of the rdkit cartridge, refer to the rdkit docs on the matter.

Building the Docker Image

Builds are driven by versions.json, which declares the Debian suite, the PostgreSQL majors and the RDKit releases that are rebuilt automatically by the Build images GitHub Actions workflow. A single-line edit to that file adds or removes a pair; nothing else changes.

Any (PostgreSQL, RDKit) pair can also be built on demand without editing versions.json, either through the Build images workflow's workflow_dispatch inputs or locally with make:

make runtime POSTGRES=17.11 RDKIT=2026_03_6
make runtime POSTGRES=15    RDKIT=2025_09_6 DEBIAN=trixie
make test    POSTGRES=17.11 RDKIT=2026_03_6

POSTGRES accepts a major (17, which resolves to the current point release at build time) or a point release (17.11, which pins an immutable base image). Run make help to see the full target and variable surface: targets core build runtime test test-build test-runtime smoke labels test-scripts clean, and variables POSTGRES, RDKIT, DEBIAN (defaults come from versions.json, so a bare make runtime builds the pair that gets the latest tag). make core builds the PostgreSQL-independent RDKit compile (Dockerfile.rdkit-core) that every other target depends on, shared across every POSTGRES value for the same RDKIT/DEBIAN -- build/runtime/test-build/test-runtime all run it as a prerequisite, so it is rarely invoked directly. make smoke runs this project's functional smoke test against a built runtime image; make test-scripts runs this repo's own shell/Python test suite under tests/ and does not need Docker; make clean clears the .make/ cache that memoizes the PostgreSQL point-release lookups.

Which RDKit releases build

Not every RDKit release compiles cleanly with this Dockerfile's default configuration (RDK_BUILD_DESCRIPTORS3D=OFF, RDK_BUILD_CHEMDRAW_SUPPORT=OFF, RDK_BUILD_INCHI_SUPPORT=ON):

RDKit release	builds with the defaults?	note
2023_09_6, 2024_09_5	yes
2025_03_1 … 2025_03_6	no	unguarded Descriptors::GETAWAY in Code/GraphMol/Descriptors/catch_tests.cpp
2025_09_1, 2025_09_2	no	same, plus Code/Bench/inchi.cpp
2025_09_3 and newer	yes	upstream guarded the GETAWAY calls
2026_03_*	yes

The releases marked "no" fail a roughly 20-minute compile at around 77%. That is an upstream test-file defect in those specific releases, fixed in the next patch release, so the fix is to build that patch release instead.

To invoke docker build directly, run make core first. The main Dockerfile's builder stage starts FROM the separately-built, PostgreSQL-independent RDKit compile (Dockerfile.rdkit-core) rather than cloning and compiling RDKit itself, and the rdkit_core_image build argument defaults to the local tag make core produces (rdkit-core:<rdkit_version>-<debian_version>), so a fork never pulls this repository's published core image by accident:

docker build -t <your_tag> \
  --build-arg debian_version=bookworm \
  --build-arg postgres_major_version=17 \
  --build-arg rdkit_version=2026_03_6 \
  .

Build arguments:

• debian_version: the Debian suite of the base image. Formatted like bookworm.
• postgres_major_version: the major version of PostgreSQL. Formatted like 17.
• postgres_point_version: optional, labels only. Formatted like 17.11.
• postgres_base_image: optional; defaults to docker.io/postgres:<major>-<suite>. Set it to pin a point release or a digest.
• rdkit_core_image: optional; defaults to rdkit-core:<rdkit_version>-<debian_version>, the local tag make core builds from Dockerfile.rdkit-core. The GitHub Actions workflow sets it to the image it pushes to GHCR.
• rdkit_version: an RDKit release tag suffix. Formatted like 2026_03_6.

There is no build argument that selects a Boost version. Instead, the Boost package family is chosen automatically at build time from RDKit's own declared floor (RDK_BOOST_VERSION), picking the lowest family in the Debian suite that satisfies it.

If no family in the suite satisfies the floor, the build fails with a message naming the floor and listing what the suite offers. The fix in that case is to raise debian in versions.json.

Releases

Releases mark changes to this project, not new images. The daily build publishes new images whenever PostgreSQL or RDKit ships a release, but a GitHub release is only cut when the Dockerfiles, the build matrix in versions.json, the tagging rules or the workflow change in a way users should know about. Watching this repository's releases is the way to be notified of those changes; new image tags appear in the table above and on the GHCR package page. The history is in CHANGELOG.md, generated with git-cliff from conventional commit messages.

To cut a release: run make changelog VERSION=X.Y.Z, review the new section, commit it as chore(release): vX.Y.Z, tag vX.Y.Z and push the tag. The Release workflow renders the same commits into the GitHub release notes.

Credits and other projects

The image is based on the Dockerfile by rvianello.

Here is a non-exhaustive list of other projects that do something similar:

• docker-postgres-rdkit by rvianello
• docker-postgres-rdkit by mcs07
• docker-postgres-rdkit by v-kamerdinerov
• docker-postgres-rdkit by joelduerksen

The main difference between these projects and this one is that I'm attempting to automate the creation of images as much as possible, to ensure that all version combinations going forward (and a few historical) are covered.

This project was put together with a lot of prodding of ChatGPT.