Skip to content

Commit 2d4ec1e

Browse files
gbartolinigbartolini
committed
docs: review (wip)
Signed-off-by: Gabriele Bartolini <[email protected]>
1 parent 086b72f commit 2d4ec1e

File tree

2 files changed

+90
-26
lines changed

2 files changed

+90
-26
lines changed

‎BUILD.md

+45-13
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,24 @@ image building.
1818
3. [Distribution Registry](https://distribution.github.io/distribution/):
1919
Formerly known as Docker Registry, to host and manage the built images.
2020

21-
## Verifying Requirements
21+
### Verifying Requirements
2222

2323
To confirm your environment is properly set up, run:
2424

2525
```bash
2626
docker buildx bake --check
2727
```
2828

29-
If warnings appear, you may need to switch to a different build driver (e.g.,
30-
`docker-container`). Use the following commands to configure it:
29+
If warnings appear, you may need to switch to a different build driver. For
30+
example, use the following commands to configure a `docker-container` build
31+
driver:
3132

3233
```bash
33-
docker buildx create --driver docker-container --name docker-container
34-
docker buildx use docker-container
34+
docker buildx create \
35+
--name docker-container \
36+
--driver docker-container \
37+
--use \
38+
--bootstrap
3539
```
3640

3741
## Default Target
@@ -59,27 +63,55 @@ docker buildx bake --push
5963
6064
If you want to limit the build to a specific combination, you can specify the
6165
target in the `VERSION-TYPE-BASE` format. For example, to build an image for
62-
PostgreSQL 17 with the `minimal` format on the `bullseye` base image:
66+
PostgreSQL 17 with the `minimal` format on the `bookworm` base image:
6367

6468
```bash
65-
docker buildx bake --push postgresql-17-minimal-bullseye
69+
docker buildx bake --push postgresql-17-minimal-bookworm
6670
```
6771

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

7074
```bash
71-
docker buildx bake --set *.platform=linux/amd6
75+
docker buildx bake --push --set "*.platform=linux/amd64"
7276
```
7377

74-
## SBOMs
78+
The two can be mixed as well:
7579

76-
Software Bills of Materials (SBOMs) are available for minimal and standard
77-
images. The SBOM for an image can be retrieved with the following command:
80+
```bash
81+
docker buildx bake --push \
82+
--set "*.platform=linux/amd64" \
83+
postgresql-17-minimal-bookworm
84+
```
85+
86+
## The Distribution Registry
87+
88+
The images must be pushed to any registry server that complies with the **OCI
89+
Distribution Specification**.
7890

79-
```shell
80-
docker buildx imagetools inspect <IMAGE> --format "{{ json .SBOM.SPDX}}"
91+
By default, the build process assumes a registry server running locally at
92+
`localhost:5000`. To use a different registry, set the `registry` environment
93+
variable when executing the `docker` command, as shown:
94+
95+
```bash
96+
registry=<REGISTRY_URL> docker buildx ...
8197
```
8298

99+
## Local Testing
100+
101+
You can test the image-building process locally if you meet the necessary
102+
[prerequisites](prerequisites).
103+
104+
To do this, you'll need a local registry server. If you don't already have one,
105+
you can deploy a temporary, disposable [distribution registry](https://distribution.github.io/distribution/about/deploying/)
106+
with the following command:
107+
108+
```bash
109+
docker run -d --rm -p 5000:5000 --name registry registry:2
110+
```
111+
112+
This command runs a lightweight, temporary instance of the `registry:2`
113+
container on port `5000`.
114+
83115
## Trademarks
84116

85117
*[Postgres, PostgreSQL and the Slonik Logo](https://www.postgresql.org/about/policies/trademarks/)

‎README.md

+45-13
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,26 @@
88
99
---
1010

11-
# PostgreSQL Container Images
11+
# CNPG PostgreSQL Container Images
1212

13-
This repository provides maintenance scripts to generate immutable application
14-
containers for all supported PostgreSQL versions (13 to 17).
13+
This repository provides maintenance scripts for generating immutable
14+
application containers for all supported PostgreSQL versions (13 to 17). These
15+
containers are designed to serve as operands for the [CloudNativePG (CNPG)
16+
operator](https://cloudnative-pg.io) in Kubernetes environments.
1517

16-
These images are designed to serve as operands for the
17-
[CloudNativePG operator](https://cloudnative-pg.io)
18-
inside Kubernetes and are available on the
19-
[GitHub Container Registry](https://github.com/cloudnative-pg/postgres-containers/pkgs/container/postgresql).
18+
## Key Features
2019

21-
Images are automatically rebuilt weekly on Mondays.
20+
The CNPG PostgreSQL Container Images:
21+
22+
- Are based on Debian Linux `stable` and `oldstable`
23+
- Support **multi-architecture builds**, including `linux/amd64` and `linux/arm64`.
24+
- Include **build attestations**, such as Software Bills of Materials (SBOMs) and provenance metadata.
25+
- Are published on the [CloudNativePG GitHub Container Registry](https://github.com/cloudnative-pg/postgres-containers/pkgs/container/postgresql).
26+
- Are **automatically rebuilt weekly** (every Monday) to ensure they remain up-to-date.
2227

2328
## Image Types
2429

25-
We currently build and support two primary types of images:
30+
We currently build and support two primary types of PostgreSQL images:
2631

2732
- [`minimal`](#minimal-images)
2833
- [`standard`](#standard-images)
@@ -34,12 +39,15 @@ plugins, such as [Barman Cloud](https://github.com/cloudnative-pg/plugin-barman-
3439
> [`system`](#system-images) image type. Switching from `system` images to
3540
> `minimal` or `standard` images on an existing cluster is not supported.
3641
37-
### Minimal images
38-
39-
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).
42+
### Minimal Images
4043

41-
Minimal images include `minimal` in the tag name, e.g. `17.2-minimal-bookworm`.
44+
Minimal images are lightweight and built on top of the
45+
[official Debian images](https://hub.docker.com/_/debian).
46+
They use the [APT PostgreSQL packages](https://wiki.postgresql.org/wiki/Apt)
47+
maintained by the PostgreSQL Global Development Group (PGDG).
4248

49+
These images are identified by the inclusion of `minimal` in their tag names,
50+
for example: `17.2-minimal-bookworm`.
4351

4452
### Standard Images
4553

@@ -79,6 +87,30 @@ The [`Debian`](Debian) folder contains image catalogs, which can be used as:
7987
> eventually removed. Users are encouraged to migrate to `minimal` or
8088
> `standard` images as soon as feasible.
8189
90+
## Build Attestations
91+
92+
CNPG PostgreSQL Container Images are built with the following attestations to
93+
ensure transparency and traceability:
94+
95+
- **[Software Bill of Materials
96+
(SBOM)](https://docs.docker.com/build/metadata/attestations/sbom/):** A
97+
comprehensive list of software artifacts included in the image or used during
98+
its build process, formatted using the [in-toto SPDX predicate standard](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md).
99+
100+
- **[Provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/):**
101+
Metadata detailing how the image was built, following the [SLSA Provenance](https://slsa.dev)
102+
framework.
103+
104+
For example, you can retrieve the SBOM for a specific image using the following
105+
command:
106+
107+
```bash
108+
docker buildx imagetools inspect <IMAGE> --format "{{ json .SBOM.SPDX }}"
109+
```
110+
111+
This command outputs the SBOM in JSON format, providing a detailed view of the
112+
software components and build dependencies.
113+
82114
## Building Images
83115

84116
For detailed instructions on building PostgreSQL container images, refer to the

0 commit comments

Comments
 (0)