docs: review (wip)

Signed-off-by: Gabriele Bartolini <[email protected]>

Author: gbartolini

BUILD.md

@@ -18,20 +18,24 @@ image building.
 3. [Distribution Registry](https://distribution.github.io/distribution/):
 Formerly known as Docker Registry, to host and manage the built images.
 
-## Verifying Requirements
+### Verifying Requirements
 
 To confirm your environment is properly set up, run:
 
 ```bash
 docker buildx bake --check
 ```
 
-If warnings appear, you may need to switch to a different build driver (e.g.,
-`docker-container`). Use the following commands to configure it:
+If warnings appear, you may need to switch to a different build driver. For
+example, use the following commands to configure a `docker-container` build
+driver:
 
 ```bash
-docker buildx create --driver docker-container --name docker-container
-docker buildx use docker-container
+docker buildx create \
+  --name docker-container \
+  --driver docker-container \
+  --use \
+  --bootstrap
 ```
 
 ## Default Target
@@ -59,27 +63,55 @@ docker buildx bake --push
 
 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 `bullseye` base image:
+PostgreSQL 17 with the `minimal` format on the `bookworm` base image:
 
 ```bash
-docker buildx bake --push postgresql-17-minimal-bullseye
+docker buildx bake --push postgresql-17-minimal-bookworm
 ```
 
 You can also limit the build to a single platform, for example AMD64, with:
 
 ```bash
-docker buildx bake --set *.platform=linux/amd6
+docker buildx bake --push --set "*.platform=linux/amd64"
 ```
 
-## SBOMs
+The two can be mixed as well:
 
-Software Bills of Materials (SBOMs) are available for minimal and standard
-images. The SBOM for an image can be retrieved with the following command:
+```bash
+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**.
 
-```shell
-docker buildx imagetools inspect <IMAGE> --format "{{ json .SBOM.SPDX}}"
+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:
+
+```bash
+registry=<REGISTRY_URL> docker buildx ...
 ```
 
+## Local Testing
+
+You can test the image-building process locally if you meet the necessary
+[prerequisites](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](https://distribution.github.io/distribution/about/deploying/)
+with the following command:
+
+```bash
+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](https://www.postgresql.org/about/policies/trademarks/)

README.md

@@ -8,21 +8,26 @@
 
 ---
 
-# PostgreSQL Container Images
+# CNPG PostgreSQL Container Images
 
-This repository provides maintenance scripts to generate immutable application
-containers for all supported PostgreSQL versions (13 to 17).
+This repository provides maintenance scripts for generating immutable
+application containers for all supported PostgreSQL versions (13 to 17). These
+containers are designed to serve as operands for the [CloudNativePG (CNPG)
+operator](https://cloudnative-pg.io) in Kubernetes environments.
 
-These images are designed to serve as operands for the
-[CloudNativePG operator](https://cloudnative-pg.io)
-inside Kubernetes and are available on the
-[GitHub Container Registry](https://github.com/cloudnative-pg/postgres-containers/pkgs/container/postgresql).
+## Key Features
 
-Images are automatically rebuilt weekly on Mondays.
+The CNPG PostgreSQL Container Images:
+
+- Are based on Debian Linux `stable` and `oldstable`
+- Support **multi-architecture builds**, including `linux/amd64` and `linux/arm64`.
+- Include **build attestations**, such as Software Bills of Materials (SBOMs) and provenance metadata.
+- Are published on the [CloudNativePG GitHub Container Registry](https://github.com/cloudnative-pg/postgres-containers/pkgs/container/postgresql).
+- Are **automatically rebuilt weekly** (every Monday) to ensure they remain up-to-date.
 
 ## Image Types
 
-We currently build and support two primary types of images:
+We currently build and support two primary types of PostgreSQL images:
 
 - [`minimal`](#minimal-images)
 - [`standard`](#standard-images)
@@ -34,12 +39,15 @@ plugins, such as [Barman Cloud](https://github.com/cloudnative-pg/plugin-barman-
 > [`system`](#system-images) image type. Switching from `system` images to
 > `minimal` or `standard` images on an existing cluster is not supported.
 
-### Minimal images
-
-Minimal images are built on top of the [official Debian images](https://hub.docker.com/_/debian), by installing [APT PostgreSQL packages](https://wiki.postgresql.org/wiki/Apt) provided by the PostgreSQL Global Development Group (PGDG).
+### Minimal Images
 
-Minimal images include `minimal` in the tag name, e.g. `17.2-minimal-bookworm`.
+Minimal images are lightweight and built on top of the
+[official Debian images](https://hub.docker.com/_/debian).
+They use the [APT PostgreSQL packages](https://wiki.postgresql.org/wiki/Apt)
+maintained by the PostgreSQL Global Development Group (PGDG).
 
+These images are identified by the inclusion of `minimal` in their tag names,
+for example: `17.2-minimal-bookworm`.
 
 ### Standard Images
 
@@ -79,6 +87,30 @@ The [`Debian`](Debian) folder contains image catalogs, which can be used as:
 > eventually removed. Users are encouraged to migrate to `minimal` or
 > `standard` images as soon as feasible.
 
+## Build Attestations
+
+CNPG PostgreSQL Container Images are built with the following attestations to
+ensure transparency and traceability:
+
+- **[Software Bill of Materials
+  (SBOM)](https://docs.docker.com/build/metadata/attestations/sbom/):** A
+  comprehensive list of software artifacts included in the image or used during
+  its build process, formatted using the [in-toto SPDX predicate standard](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md).
+
+- **[Provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/):**
+  Metadata detailing how the image was built, following the [SLSA Provenance](https://slsa.dev)
+  framework.
+
+For example, you can retrieve the SBOM for a specific image using the following
+command:
+
+```bash
+docker buildx imagetools inspect <IMAGE> --format "{{ json .SBOM.SPDX }}"
+```
+
+This command outputs the SBOM in JSON format, providing a detailed view of the
+software components and build dependencies.
+
 ## Building Images
 
 For detailed instructions on building PostgreSQL container images, refer to the