This is an automated email from the ASF dual-hosted git repository.
ritesh pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 28b95613 HDDS-11916. Building Ozone Docker Images (#126)
28b95613 is described below
commit 28b95613abfb83aec15cf7581ce6f8ffc3f25bc9
Author: Doroszlai, Attila <[email protected]>
AuthorDate: Fri Mar 21 07:11:41 2025 +0100
HDDS-11916. Building Ozone Docker Images (#126)
---
.../01-build/03-docker-images.md | 107 ++++++++++++++++++++-
1 file changed, 103 insertions(+), 4 deletions(-)
diff --git a/docs/08-developer-guide/01-build/03-docker-images.md
b/docs/08-developer-guide/01-build/03-docker-images.md
index 8f49ee45..8d5889b2 100644
--- a/docs/08-developer-guide/01-build/03-docker-images.md
+++ b/docs/08-developer-guide/01-build/03-docker-images.md
@@ -2,10 +2,109 @@
sidebar_label: Docker Images
---
+<!-- cspell:word testkrb5 -->
+
# Building Ozone Docker Images
-**TODO:** File a subtask under
[HDDS-9861](https://issues.apache.org/jira/browse/HDDS-9861) and complete this
page or section.
+This page provides an overview of the Docker images maintained by the Apache
Ozone community for developing and testing Ozone. It also describes the
workflow to be followed when making changes to one of these images.
+
+## ozone-runner
+
+[ozone-runner](https://github.com/apache/ozone-docker-runner) is the base
image with tools for running and testing Ozone, but does not include any Ozone
artifacts.
+
+Developers and CI workflows rely on it heavily to run/test custom Ozone builds
(using the local build via bind-mount). It also serves as the base image for
`apache/ozone` (see next section).
+
+Published to [Docker Hub](https://hub.docker.com/r/apache/ozone-runner) and
[GitHub](https://github.com/apache/ozone-docker-runner/pkgs/container/ozone-runner).
+
+Development happens on branch `master`, relevant changes are cherry-picked to
branch `jdk11`.
+
+### Building
+
+The image can be built simply by running the helper script `build.sh`:
+
+```bash
+./build.sh
+```
+
+### Tagging
+
+Images are tagged by date, and come in two flavors: `jdk21` (for Ozone 2.0+)
and `jdk11` (for Ozone 1.x).
+
+Publishing Docker tags:
+
+1. Add a Git tag for the commit following the existing pattern
(`<date>-<n>-<flavor>`, where `<n>` starts at 1, and is incremented if multiple
images need to be published the same day).
+2. Push the Git tag to the origin repo (`apache/ozone-docker-testkrb5`). This
will trigger a workflow run to apply the tag to the Docker image.
+
+## ozone
+
+[ozone](https://github.com/apache/ozone-docker) is built on top of
`ozone-runner`, adding the binaries built for official Ozone releases.
+
+These are used for testing compatibility of various Ozone versions, and
upgrade from one version to another. May also be useful for running quick
experiments with specific version of Ozone, without the need to download or
rebuild it.
+
+Published to [Docker Hub](https://hub.docker.com/r/apache/ozone) and
[GitHub](https://github.com/apache/ozone-docker/pkgs/container/ozone).
+
+Development branch: `latest`.
+
+### Building
+
+The image can be built simply by running the helper script `build.sh`:
+
+```bash
+./build.sh
+```
+
+This will create a single-platform image for your architecture. Build
automation in GitHub Actions creates multi-platform image for `amd64` and
`arm64`.
+
+It can be customized via environment variables defined at build time.
+
+```bash
+# the URL to download Ozone from; allows using custom tarball or local mirror
+OZONE_URL
+
+# version of Ozone to include in the image; ignored if URL is also specified
+OZONE_VERSION
+
+# the base image name in repo/image format
+OZONE_RUNNER_IMAGE
+
+# the base image version to use
+OZONE_RUNNER_VERSION
+```
+
+### Tagging
+
+Images are tagged by Ozone version numbers and optional flavor. Flavor
`-rocky` was introduced when `ozone-runner` was changed from CentOS to Rocky
Linux due to CentOS end-of-life, to avoid breaking things for existing users.
Future images will be published only with Rocky Linux, with and without flavor
suffix.
+
+Image tags are derived from branch names: push to the branch `ozone-<tag>`
gets published with `<tag>` (e.g. `ozone-1.4.1 -> 1.4.1`).
+
+Publishing Docker tags:
+
+1. Update the version-specific branch:
+ - The latest release version can usually be updated by fast-forwarding the
branch: `git merge --ff-only origin/latest`. This allows CI workflow to tag
the existing image from `latest` branch, instead of building completely new
image.
+ - For other versions branch can be updated by cherry-picking one or more
commits.
+2. Push the branch to the origin repo (`apache/ozone-docker`). This will
trigger a workflow run to publish the image.
+
+## ozone-testkrb5
+
+[ozone-testkrb5](https://github.com/apache/ozone-docker-testkrb5) is used as
KDC in tests where Kerberos is enabled.
+
+Published only to
[GitHub](https://github.com/apache/ozone-docker-testkrb5/pkgs/container/ozone-testkrb5),
because it is completely insecure, and should be used only for testing.
+
+Development branch: `master`.
+
+### Building
+
+The image can be built simply by running the helper script `build.sh`:
+
+```bash
+./build.sh
+```
+
+### Tagging
+
+Images are tagged by date.
+
+Publishing Docker tags:
-- Point to the `ozone-docker` repo and define its purpose as a testing/demo
image with Ozone binaries included.
-- Point to the `ozone-docker-runner` repo and define its purpose as a test
image where Ozone binaries can be mounted.
-- Instructions for building the images from source, customizing architecture
(arm).
+1. Add a Git tag for the commit following existing pattern (`<date>-<n>`,
where `<n>` starts at 1, and is incremented if multiple images need to be
published the same day).
+2. Push the Git tag to the origin repo (`apache/ozone-docker-testkrb5`). This
will trigger a workflow run to apply the tag to the Docker image.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
