CNPG Postgres Extension Containers

This repository builds PostgreSQL extension container images for CloudNativePG using the same base image pattern and a minimal packaging layout.

The repo currently includes two extension images:

• cron via cron/Dockerfile for pg_cron
• timescaledb via timescaledb/Dockerfile for TimescaleDB

Prerequisites

• Docker Engine
• Docker Buildx (recommended for modern builds)
• Access to a container registry such as GitHub Container Registry (ghcr.io)
• For GitHub Actions usage: a repository with packages: write permission and a valid GITHUB_TOKEN

Build architecture

Each Dockerfile follows the same pattern:

1. Start from ghcr.io/cloudnative-pg/postgresql:<major>-minimal-trixie
2. Install the extension package in a builder stage
3. Copy only the runtime libraries, share files, and license metadata into a final scratch image

This keeps the final image minimal and compatible with CloudNativePG-style extension containers.

---

1) Manual local builds

Run the builds from the repository root.

cron image (pg_cron)

docker build \
  -f cron/Dockerfile \
  -t ghcr.io/<your-user>/postgresql-ext-cron:18-1.6.7 \
  --build-arg PG_MAJOR=18 \
  --build-arg EXT_VERSION=1.6.7 \
  .

You can also use a local tag:

docker build \
  -f cron/Dockerfile \
  -t local/postgresql-ext-cron:18-1.6.7 \
  --build-arg PG_MAJOR=18 \
  --build-arg EXT_VERSION=1.6.7 \
  .

If you want to push to GHCR after building:

docker push ghcr.io/<your-user>/postgresql-ext-cron:18-1.6.7

timescaledb image

docker build \
  -f timescaledb/Dockerfile \
  -t ghcr.io/<your-user>/postgresql-ext-timescaledb:18-2.29.2 \
  --build-arg PG_MAJOR=18 \
  --build-arg EXT_VERSION=2.29.2 \
  .

Or with a local tag:

docker build \
  -f timescaledb/Dockerfile \
  -t local/postgresql-ext-timescaledb:18-2.29.2 \
  --build-arg PG_MAJOR=18 \
  --build-arg EXT_VERSION=2.29.2 \
  .

Then push it:

docker push ghcr.io/<your-user>/postgresql-ext-timescaledb:18-2.29.2

The Dockerfiles default to PG_MAJOR=18 and their own default extension versions, but you can override them with --build-arg to match your target PostgreSQL version or extension package version.

---

2) GitHub Actions usage

The repository includes a workflow at .github/workflows/build.yaml that can build and publish either extension image.

Triggering the workflow

1. Open GitHub Actions in the repository.
2. Select the Build and Push workflow.
3. Click Run workflow.
4. Supply the required inputs:
   • ext_name: cron or timescaledb
   • pg_major: PostgreSQL major version, for example 18
   • ext_version: extension package version, for example 1.6.7 or 2.29.2

Example values

Build pg_cron

ext_name: cron
pg_major: 18
ext_version: 1.6.7

This produces tags like:

• ghcr.io/<owner>/postgresql-ext-cron:18-1.6.7
• ghcr.io/<owner>/postgresql-ext-cron:18
• ghcr.io/<owner>/postgresql-ext-cron:latest

Build TimescaleDB

ext_name: timescaledb
pg_major: 18
ext_version: 2.29.2

This produces tags like:

• ghcr.io/<owner>/postgresql-ext-timescaledb:18-2.29.2
• ghcr.io/<owner>/postgresql-ext-timescaledb:18
• ghcr.io/<owner>/postgresql-ext-timescaledb:latest

What the workflow does

The workflow uses docker/build-push-action with:

• context: .
• file: ./${{ inputs.ext_name }}/Dockerfile
• push: true
• build-args:
  • PG_MAJOR=${{ inputs.pg_major }}
  • EXT_VERSION=${{ inputs.ext_version }}

This means the same Dockerfile build logic is reused for both custom images, while the action handles registry tagging and publishing automatically.

---

3) Notes

• The cron image installs postgresql-${PG_MAJOR}-cron from the PostgreSQL package repository.
• The timescaledb image installs the TimescaleDB package via the official Timescale package repository and then packages only the runtime files needed by PostgreSQL.
• Both images are designed to be used as extension images for CloudNativePG deployments, with the required license and shared object files copied into the final image.