pgEdge Postgres Images

This repository provides build scripts for generating pgEdge Postgres container images supporting Postgres versions 16, 17 and 18.

Images are built from pgEdge Enterprise Postgres packages using a rockylinux9-ubi base image.

Images are published on the pgEdge Github Container Registry.

Image Flavors

There are currently 2 supported image flavors: minimal and standard.

Package lists contained under packagelists show the exact contents of each image version.

Minimal Images

Minimal images contain Postgres, and the following extensions:

• Spock
• LOLOR
• Snowflake

Standard Images

Standard images are based on minimal images, and contain additional extension and tools.

• pgAudit
• PostGIS
• pgVector
• pgEdge Vectorizer
• pg_tokenizer
• vchord_bm25
• pg_vectorize
• pgmq
• pg_cron
• pg_stat_monitor
• Patroni
• pgBackRest
• psycopg2

Entry Points

The default entry point for this image is based on the official Postgres image entrypoint. Documentation on supported entrypoint behavior is located in the docker-library/docs repo. Running the container as root is not currently supported.

In addition to the default entry point, Patroni (/usr/local/bin/patroni) can also be used as an entrypoint in the standard image.

Examples

docker run

To run a single instance you can use this command:

docker run --name pgedge-postgres \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_USER=admin \
  -e POSTGRES_DB=example_db \
  -p 6432:5432 \
  -d ghcr.io/pgedge/pgedge-postgres:17-spock5-standard

You can then log in using psql with the following command:

docker exec -it pgedge-postgres psql -U admin example_db

docker compose

This repository includes two Docker Compose examples you can try out:

• Enterprise Example

  • This example runs a single Postgres instance using the standard image and initializes extensions.

• Distributed Example

  • This example runs two Postgres instances as pgEdge nodes (n1 / n2) with Spock logical replication pre-configured.

Data Volumes

This image is compatible with Docker volumes and bind mounts. The configuration for both is similar. Because Postgres requires the data directory to be owned by the user running the database, the PGDATA directory should be specified as a subdirectory of the volume mount.

By default, this image uses the following approach for volume configuration:

• /var/lib/pgsql is the recommended volume mount point
• /var/lib/pgsql/<pg_major_version>/data is the default Postgres data directory (PGDATA)

An example Docker compose spec that shows this looks like this:

pgedge-postgres:
  image: ghcr.io/pgedge/pgedge-postgres:17-spock5-standard
  restart: always
  environment:
    POSTGRES_USER: ${POSTGRES_USER:-admin}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password}
    POSTGRES_DB: ${POSTGRES_DB:-example_db}
  volumes:
    - data:/var/lib/pgsql

volumes:
  data:

Image Tags

• Every image will have an immutable tag, <postgres major.minor>-spock<major.minor.patch>-<flavor>-<epoch>, e.g. 17.6-spock5.0.0-standard-1
• Mutable tags also exist for:
  • The latest image for a given Postgres major.minor + spock major version, pg<postgres major.minor>-spock<major>-<flavor> , e.g. 17.6-spock5-standard
  • The latest image for a given Postgres major + spock major version, pg<postgres major>-spock<major>-<flavor>, e.g. 17-spock5-standard

Testing

This repository includes a comprehensive test suite to validate Postgres images. The tests verify:

• Default entrypoint functionality
• Patroni entrypoint (standard images only)
• PostgreSQL connectivity and version checks
• Extension availability and functionality (Spock, LOLOR, Snowflake, pgvector, PostGIS, pgaudit)
• pgBackRest installation (standard images only)

Running Tests Locally

To run tests locally, you'll need:

• Go 1.24.11 or later
• Docker installed and running
• Access to pull the image you want to test

Run the test suite using the Makefile:

make test-image IMAGE=<image> FLAVOR=<minimal|standard>

Example:

make test-image IMAGE=ghcr.io/pgedge/pgedge-postgres:17-spock5-standard FLAVOR=standard

Or run directly with Go:

cd tests && go run main.go -image <image> -flavor <minimal|standard>

Local Testing Limitations

Architecture Limitations: When running tests locally, you can only test images that match your local machine's architecture. For example:

• On an x86_64/amd64 machine, you can only test amd64 images
• On an ARM64 machine, you can only test arm64 images

To test images for multiple architectures, use the GitHub Actions workflow which runs tests on architecture-specific runners:

• ubuntu-latest runner (amd64/x86_64 architecture)
• ubuntu-24.04-arm runner (arm64 architecture)

CI/CD Testing

The GitHub Actions workflow (.github/workflows/test_images.yaml) can be triggered manually to test images across multiple architectures. The workflow uses specific runner labels to target CPU architectures:

• amd64/x86_64: Uses ubuntu-latest runner
• arm64: Uses ubuntu-24.04-arm runner

The workflow accepts:

• Package Repository: The container registry repository name
• Tags: Comma-separated list of image tags to test
• Architectures: Comma-separated list of architectures (x86,arm or amd64,arm64)

The workflow will automatically test each tag on each specified architecture by mapping the architecture names to the appropriate runner labels.