Skip to content

Latest commit

 

History

History
129 lines (93 loc) · 4.06 KB

BUILD.md

File metadata and controls

129 lines (93 loc) · 4.06 KB

Building PostgreSQL Container Images for CloudNativePG

This guide outlines the process for building PostgreSQL operand images for CloudNativePG using Docker Bake and a GitHub workflow.

The central component of this framework is the Bake file (docker-bake.hcl).

Prerequisites

Ensure the following tools and components are available before proceeding:

  1. Docker Buildx: A CLI plugin for advanced image building.
  2. Build Driver for Multi-Architecture Images: For example, docker-container (see Build Drivers and "Install QEMU Manually").
  3. Distribution Registry: Formerly known as Docker Registry, to host and manage the built images.

Verifying Requirements

To confirm your environment is properly set up, run:

docker buildx bake --check

If errors appear, you may need to switch to a different build driver. For example, use the following commands to configure a docker-container build driver:

docker buildx create \
  --name docker-container \
  --driver docker-container \
  --use \
  --driver-opt network=host \
  --bootstrap

Note: The --driver-opt network=host setting is required only for testing when you push to a distribution registry listening on localhost.

Note: This page is not intended to serve as a comprehensive guide for building multi-architecture images with Docker and Bake. If you encounter any issues, please refer to the resources listed above for detailed instructions and troubleshooting.

Default Target

The default target in Bake represents a Cartesian product of the following dimensions:

  • Base Image
  • Type (e.g. minimal or standard)
  • Platforms
  • PostgreSQL Versions

Building Images

To build PostgreSQL images using the default target — that is, for all the combinations of base image, format, platforms, and PostgreSQL versions — run:

docker buildx bake --push

Note: The --push flag is required to upload the images to the registry. Without it, the images will remain cached within the builder container, making testing impossible.

If you want to limit the build to a specific combination, you can specify the target in the VERSION-TYPE-BASE format. For example, to build an image for PostgreSQL 17 with the minimal format on the bookworm base image:

docker buildx bake --push postgresql-17-minimal-bookworm

You can also limit the build to a single platform, for example AMD64, with:

docker buildx bake --push --set "*.platform=linux/amd64"

The two can be mixed as well:

docker buildx bake --push \
  --set "*.platform=linux/amd64" \
  postgresql-17-minimal-bookworm

The Distribution Registry

The images must be pushed to any registry server that complies with the OCI Distribution Specification.

By default, the build process assumes a registry server running locally at localhost:5000. To use a different registry, set the registry environment variable when executing the docker command, as shown:

registry=<REGISTRY_URL> docker buildx ...

Local Testing

You can test the image-building process locally if you meet the necessary prerequisites.

To do this, you'll need a local registry server. If you don't already have one, you can deploy a temporary, disposable distribution registry with the following command:

docker run -d --rm -p 5000:5000 --name registry registry:2

This command runs a lightweight, temporary instance of the registry:2 container on port 5000.

Trademarks

Postgres, PostgreSQL and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada, and used with their permission.