The repository provides scripts and workflows to:
- Build AlmaLinux Container Images (Docker Images)
- Test these images
- Push them into different registries, the Client Library:
- Extract root filesystem (RootFS) from default and minimal images
- Publish the images to the Docker Official Library.
These Container Images can be used with all OCI complaint container runtime environments such as Docker, Podman and Kubernetes as well as serve as drop-in replacements for CentOS images as they reach End of Life.
Personal, Organization or Enterprise account on GitHub is the only requirement. Please read more about accounts on GitHub.
The project utilizes GitHub Actions to provide public, transparent and fast workflows that are easy to understand, use and modify.
There are two workflows on GitHub Actions designed to achieve the idea:
- Build, test, push all types of container images into the Client Library, and extract RootFS from
defaultandminimalimages. - Use these RootFS to request Docker to create images for the Official Library.
You can read more about how the workflows work in the section below.
The AlmaLinux Client Library includes the following registries/organizations:
- Docker.io/almalinux (Sponsored by OSS)
- Quay.io/almalinuxorg
- Ghcr.io/AlmaLinux
The AlmaLinux Official Library is maintained by Docker.
Each image pushed to the Client Library is built from a corresponding Containerfile that is a unique file for each AlmaLinux release and configuration type: base, default, init, micro, minimal.
These files match Dockerfile standard and contain commands and instructions on how to install AlmaLinux's whole root filesystem in them.
Images for the Docker Official Library are built using other Dockerfiles that are also designed for each AlmaLinux release but only default and minimal types:
- 8 default and minimal per platform;
- 9 default and minimal per platform. These Dockerfiles are to build images from scratch using platform's corresponding RootFS.
Container images are built for AlmaLinux OS 8 and 9. The Major version of the release must be set for the Build, Test and Push workflow. The Minor version is automatically set by the workflow as the latest.
Publish Images workflow pushes build requests to the Docker also for both AlmaLinux releases, 8 and 9.
AlmaLinux container images types match Red Hat Universal Base Image:
basedefault(the image is also available via the Docker Official Library)initmicrominimal(the image is also available via the Docker Official Library)
Build, Test and Push workflow builds container images of the following platforms simultaneously with docker buildx. They result in the following machine hardware names (uname -m):
| docker platform | hardware name |
|---|---|
| linux/amd64 | x86_64 |
| linux/ppc64le | ppc64le |
| linux/s390x | s390x |
| linux/arm64 | aarch64 |
The containerd image store store for Docker Engine together with buildx are used to build and push multiple platforms at once.
The following repositories are created on all registries (Docker.io/almalinux, Quay.io/almalinuxorg, Ghcr.io/AlmaLinux) for all supported images types:
/almalinux- Quay.io/almalinuxorg only. Is built from thedefaultimage./8-base/9-base/8-init/9-init/8-micro/9-micro/8-minimal/9-minimal
They are the Client Library.
The following tags are created under each repository (AlmaLinux 9.3 example as of 24 Nov 2023):
| tag | example |
|---|---|
| latest | latest |
| MAJOR | 9 |
| MAJOR.MINOR | 9.3 |
| MAJOR.MINOR-DATE_STAMP | 9.3-20231124 |
The /almalinux repository includes the latest tag for AlmaLinux release 9.x only.
- Branch 'main'
.
├── .github
│ └── workflows
│ ├── build-test-push.yml
│ └── publish-docker-library.yml
├── Containerfiles
│ ├── 8
│ │ ├── Containerfile.base
│ │ ├── Containerfile.default
│ │ ├── Containerfile.init
│ │ ├── Containerfile.micro
│ │ └── Containerfile.minimal
│ └── 9
│ ├── Containerfile.base
│ ├── Containerfile.default
│ ├── Containerfile.init
│ ├── Containerfile.micro
│ └── Containerfile.minimal
├── LICENSE
└── README.md- Branch for AlmaLinux release '8'
.
├── docker-library-definition.tmpl
│
├── default
│ ├── amd64
│ │ ├── Dockerfile
│ │ └── almalinux-8-default-amd64.tar.gz
│ ├── arm64
│ │ ├── Dockerfile
│ │ └── almalinux-8-default-arm64.tar.gz
│ ├── ppc64le
│ │ ├── Dockerfile
│ │ └── almalinux-8-default-ppc64le.tar.gz
│ └── s390x
│ ├── Dockerfile
│ └── almalinux-8-default-s390x.tar.gz
└── minimal
├── amd64
│ ├── Dockerfile
│ └── almalinux-8-minimal-amd64.tar.gz
├── arm64
│ ├── Dockerfile
│ └── almalinux-8-minimal-arm64.tar.gz
├── ppc64le
│ ├── Dockerfile
│ └── almalinux-8-minimal-ppc64le.tar.gz
└── s390x
├── Dockerfile
└── almalinux-8-minimal-s390x.tar.gz- Branch for AlmaLinux release '9'
.
├── docker-library-definition.tmpl
│
├── default
│ ├── amd64
│ │ ├── Dockerfile
│ │ └── almalinux-9-default-amd64.tar.gz
│ ├── arm64
│ │ ├── Dockerfile
│ │ └── almalinux-9-default-arm64.tar.gz
│ ├── ppc64le
│ │ ├── Dockerfile
│ │ └── almalinux-9-default-ppc64le.tar.gz
│ └── s390x
│ ├── Dockerfile
│ └── almalinux-9-default-s390x.tar.gz
└── minimal
├── amd64
│ ├── Dockerfile
│ └── almalinux-9-minimal-amd64.tar.gz
├── arm64
│ ├── Dockerfile
│ └── almalinux-9-minimal-arm64.tar.gz
├── ppc64le
│ ├── Dockerfile
│ └── almalinux-9-minimal-ppc64le.tar.gz
└── s390x
├── Dockerfile
└── almalinux-9-minimal-s390x.tar.gzThe .github/workflows/build-test-push.yml workflow is used to Build, Test and Push images to the Client Library, and extract RootFS:
name: Build, test and push to the Client Library
on:
workflow_dispatch:
inputs:
production:
description: |
'Push to production registries'
'not checked - to testing'
required: true
type: boolean
default: true
...The
.github/workflows/publish-docker-library.yml workflow is used to Publish Images to the Docker Official Library:
name: Publish images to the Docker Library
on:
workflow_dispatch:
inputs:
pr:
description: 'Publish to Docker Official Library'
required: true
type: boolean
default: true
...Both workflows are triggered manually by the workflow_dispatch event of GitHub Actions.
This Containerfiles/9/Containerfile.minimal file is a Containerfile example for AlmaLinux release 9 and minimal type used to build container image for the Client Library:
ARG SYSBASE=almalinux:9
FROM ${SYSBASE} as system-build
RUN mkdir /mnt/sys-root; \
dnf install -y \
--installroot /mnt/sys-root \
--releasever 9 \
--setopt install_weak_deps=false \
--nodocs \
almalinux-release \
bash \
...
FROM scratch
COPY --from=system-build /mnt/sys-root/ /
CMD ["/bin/bash"]This minimal/amd64/Dockerfile file is a Dockerfile example for AlmaLinux release 9 minimal type and amd64 (x86_64) platform used to build container image for the Docker Official Library:
# Tags: minimal, 9-minimal, 9.3-minimal, 9.3-minimal-20231124
FROM scratch
ADD almalinux-9-minimal-amd64.tar.xz /
CMD ["/bin/bash"]The Docker Official Library uses Definition File to request building of official images. Changing the file triggers a new image(s) building on the Docker side. The docker-library-definition.tmpl template is used to generate the Definition file:
Tags: {{ .tags }}
GitFetch: refs/heads/{{ .version_major }}
GitCommit: {{ .commit_hash }}
amd64-Directory: {{ .image_type }}/amd64/
arm64v8-Directory: {{ .image_type }}/arm64/
ppc64le-Directory: {{ .image_type }}/ppc64le/
s390x-Directory: {{ .image_type }}/s390x/
Architectures: amd64, arm64v8, ppc64le, s390xFork the following repositories:
- container-images, you will need the
main, the8and the9branches. - docker-library
Read more about GitHub forks here.
❗ Please, note, that you won't be able to create a Pull Request to this repository as only AlmaLinux organization members have access to do it.
To set secrets needed for this repository, go to your GitHub account Settings -> expand Secrets and variables (located under the Security section) -> select Actions. Read more about Github Secrets in Actions.
The following Repository secrets are required. Set them with your personal data and only for registries you are using.
For production Client Library please define secrets:
| Secret name | Description |
|---|---|
DOCKERHUB_USERNAME |
docker.io user |
DOCKERHUB_TOKEN |
docker.io token |
QUAY_IO_USERNAME |
quay.io user |
QUAY_IO_CLI_PASSWORD |
quay.io CLI password |
GIT_HUB_USERNAME |
GitHub user |
GIT_HUB_TOKEN |
GitHub token |
The same secrets with TEST_ prefix in secret names (like TEST_DOCKERHUB_USERNAME) should be set for corresponded registries if testing Client Library (testing mode).
On how to create tokens/CLI passwords please read:
- Manage Quay.io Access Tokens
- Create and manage access tokens on Docker
- Managing your personal access tokens on GitHub.
When creating a new personal access token on GitHub, please, select:
- write:packages scope, to allow packages uploading to GitHub Package Registry;
- admin:org scope, to allow Pull Request creation to docker-library.
On needed registries create your own accounts in case you don't have any as you won't be able to use AlmaLinux accounts.
According to your list of needed registries and knowing your user names edit the .github/workflows/build-test-push.yml workflow file (branch master):
registries: 'docker.io/<user_name>, quay.io/<user_name>, ghcr.io/<user_name>'Separate the registries with commas.
<user_name> - is your user name on the specific registry.
If you don't need to build images for all platforms, you can edit the list of platforms to meet your needs in the .github/workflows/build-test-push.yml workflow file (branch master):
platforms: 'linux/amd64, linux/ppc64le, linux/s390x, linux/arm64'Separate the platforms with commas.
Edit the .github/workflows/build-test-push.yml workflow file (branch master) to change type of images which are built:
- Add/modify/delete input for specific type name of image:
type_<type_name>:
description: '<type_name>'
required: true
type: boolean- Add/modify/delete the image type in the matrix for the
buildjob:
image_types: ${{ fromJSON(format('["{0}"]', ( inputs.type_<type_name> && '<type_name>' ) )) }}Where <type_name> is the name of your image type.
Default are: base, default, init, micro, minimal
If a new AlmaLinux major release is available, edit the .github/workflows/build-test-push.yml workflow file (branch master), to set this major version:
inputs.version_majorlike:
version_major:
description: 'AlmaLinux major version'
required: true
default: '<version_latest>'
type: choice
options:
- <version_latest>
- 9
- 8env.version_latestlike:
version_latest: <version_latest>Where <version_latest> is an AlmaLinux version major version, for example 10.
If a new AlmaLinux minor release is available, edit the .github/workflows/build-test-push.yml workflow file (branch master) to set it. To do so, you need the "DeployPrepare AlmaLinux Minor version number" step:
case ${{ inputs.version_major }} in
8)
version_minor="<8_minor>" ;;
9)
version_minor="<9_minor>" ;;
10)
version_minor="<10_minor>" ;;
Where <8_minor>, <9_minor>, <10_minor> are AlmaLinux's corresponding minor versions.
For example Minors are 10, 4 or 1 for new 8.10, 9.4 or 10.1 versions respectively.
❗ Only AlmaLinux organization members have access to create Pull Requests and publish container images into the Docker Official Library.
❗ Build, test and push to the Client Library workflow will work only for your Client Library, but not for AlmaLinux-owned ones.
Tree illustration of the workflow Jobs and Steps for AlmaLinux 9 minimal image:
Build, test and push to the Client Library
│
├── Deploy 9 minimal images
│ ├── Set up job
│ ├── DeployPrepare AlmaLinux Minor version number
│ ├── Prepare date stamp
│ ├── Generate list of Docker images to use as base name for tags
│ ├── Enable containerd image store on Docker Engine
│ ├── Checkout _container-images, branch 'main'
│ ├── Checkout _container-images, branch '9', path '9'
│ ├── Set up QEMU
│ ├── Set up Docker Buildx
│ ├── Login to Docker.io
│ ├── Login to Quay.io
│ ├── Login to Ghcr.io
│ ├── Generate tags and prepare metadata to build and push
│ ├── Build images
│ ├── Test images
│ ├── Push images to Client Library
│ ├── Extract RootFS (default and minimal only)
│ ├── Change date stamp in Dockerfile (default and minimal only)
│ ├── Commit and push minimal/*/* Dockerfile and RootFS (branch 9)"
│ ├── Post Push images to Client Library
│ ├── Post Build images
│ ├── Post Login to Ghcr.io
│ ├── Post Set up Docker Buildx
│ ├── Post Checkout _container-images, branch '9', path '9'
│ ├── Post Checkout _container-images, branch 'main'
│ └── Complete job
│
└── Optimize size of repository
├── Checkout almalinux/container-images, branch '9', path '9'
├── Optimize size of branch the '9'
└── Commit and push almalinux/container-images, branch '9'
The workflow inputs are:
-
production- boolean 'Push to production registries' with the default valuetrue(checked). Container images are pushed into the production Client Library: Docker.io/almalinux, Quay.io/almalinuxorg and Ghcr.io/AlmaLinux. Otherwise, images are pushed into the testing Client Library: Quay.io/almalinuxautobot -
version_major- dropdown 'AlmaLinux major version' with the default value9. This is a major number of AlmaLinux version to build images for. -
Checklist of image types: base, default, init, micro, minimal. At least one should be checked.
Job proceeds to input version_major and iterates with selected image_types using matrix. Multiple jobs run simultaneously for each image type.
The step sets AlmaLinux version_minor according to set on inputs version_major.
Generates date_stamp in format YYYYMMDD. It is used in image tags.
Generates env.IMAGE_NAMES for each registry including image type like: docker.io/***/8-minimal quay.io/***/8-minimal
Modifies the /etc/docker/daemon.json as:
"features":
{
"containerd-snapshotter": true
}Restarts the docker service to get a new image store working.
The successful switch is printed in the docker info:
[[driver-type io.containerd.snapshotter.v1]]Checkouts container-images into branch 'main'. The repository directory is located at /home/runner/work/container-images/container-images. Please note, the only last commit is checked out.
The actions/checkout@v4 is used.
Checkouts container-images into branch '${version_major}'. The repository directory is located at /home/runner/work/container-images/${version_major}.
The actions/checkout@v4 is used.
Installs QEMU static binaries. The docker/setup-qemu-action@v3 is used. The QEMU static binaries are required to build different platforms within one machine.
Sets up Docker Buildx. It uses docker/setup-buildx-action@v3
The docker/login-action@v3 is used. The following secrets are used:
production mode:
- DOCKERHUB_USERNAME
- DOCKERHUB_TOKEN
testing mode:
- TEST_DOCKERHUB_USERNAME
- TEST_DOCKERHUB_TOKEN
The docker/login-action@v3 is used. The following secrets are used:
production mode:
- QUAY_IO_USERNAME
- QUAY_IO_CLI_PASSWORD
testing mode:
- TEST_QUAY_IO_USERNAME
- TEST_QUAY_IO_CLI_PASSWORD
The docker/login-action@v3 is used. The following secrets are used:
production mode:
- GIT_HUB_USERNAME
- GIT_HUB_TOKEN
testing mode:
- TEST_GIT_HUB_USERNAME
- TEST_GIT_HUB_TOKEN
The docker/metadata-action@v5 is used to generate tags, labels and annotations for images. Here is an example of AlmaLinux 8 minimal image's tags:
"tags": [
"docker.io/***/8-minimal:latest",
"docker.io/***/8-minimal:8",
"docker.io/***/8-minimal:8.9",
"docker.io/***/8-minimal:8.9-20240319",
"quay.io/***/8-minimal:latest",
"quay.io/***/8-minimal:8",
"quay.io/***/8-minimal:8.9",
"quay.io/***/8-minimal:8.9-20240319",
],The docker/build-push-action@v5 is used to build images. This step builds the images from corresponding Containerfile, for specified env.platforms and uses tags from the previous step. After the successful building, the images are loaded into docker, but not pushed yet as they need to be tested first. AlmaLinux 8 minimal images buildx looks like this:
/usr/bin/docker buildx build --file ./Containerfile.minimal ... \
--platform linux/amd64,linux/ppc64le,linux/s390x,linux/arm64 \
--provenance false ... \
--tag docker.io/***/8-minimal:latest --tag docker.io/***/8-minimal:8 --tag docker.io/***/8-minimal:8.9 --tag docker.io/***/8-minimal:8.9-20240319 --tag quay.io/***/8-minimal:latest --tag quay.io/***/8-minimal:8 --tag quay.io/***/8-minimal:8.9 --tag quay.io/***/8-minimal:8.9-20240319 \
--load \
--metadata-file /home/runner/work/_temp/docker-actions-toolkit-*/metadata-file \
https://github.com/***/container-images.git#270a6d3fd433cfa6c3e1fff5896a92d1ae2896be:Containerfiles/8provenance: false is to disable the Provenance attestations as Quay.io registry doesn't support such kind of images data.
Every image can be tested separately for each type and platform as each image is loaded into docker. Docker run images "by digest":
docker run --platform=${platform} ${{ steps.build-images.outputs.digest }}The docker/build-push-action@v5 is used. This step pushes built images into Client Library. The options are the same as for Build images step.
❗ Skip this step if the image type is not 'default' or 'minimal'.
The step is to extract RootFS from existing image's blobs:
- uses
docker saveto produce a tarred repository and save it to the "tar file". Unpack the "tar file" to get blobs. - Prepares the "temporary Dockerfile" to build image based on RootFS.
FROM scratch
ADD rootfs.tar.gz /
CMD ["/bin/bash"]- Loops blobs to find all zipped files that are RootFS for a particular architecture.
- with
docker build, builds an image from the "temporary Dockerfile". - with
docker run, runs the image and queryalmalinux-releasepackage's architecture. - Maps found architecture to the corresponding platform.
- Copes the "taken RootFS" into corresponded .tar.xz (like
almalinux-9-default-amd64.tar.xz)
❗ Skip this step if the image type is not 'default' or 'minimal'.
The step changes (# Tags with date stamp) in corresponded ${images_type}/${platform}/Docker file for AlmaLinux release 8 an release 9, which Docker will use to build images for the Official Library. An example is for AlmaLinux 9 minimal amd64 minimal/amd64/dockerfile file:
# Tags: 8-minimal, 8.9-minimal, 8.9-minimal-20240319
FROM scratch
ADD almalinux-9-minimal-amd64.tar.xz /
CMD ["/bin/bash"]
The change indicates that a new default and/or minimal container image was pushed to the Client Library and should be requested to be built by Docker. The change will later be committed to the 8 or 9 branch.
It will try to pull recent changes (before push) with
--rebase --autostash
❗ Skip this step if the image type is not 'default' or 'minimal'.
❗ The step is skipped if 'Push to production registries' is not checked (inputs.production set to false.)
Uses EndBug/add-and-commit@v9 to commit and push Dockerfile and RootFS, which were changed and extracted on the previous steps.
The commit message is:
AlmaLinux ${version_major}-${images_type} image build as of ${date_stamp} (with ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).It includes the AlmaLinux version major, image type, build date, and reference to this GitHub Action.
❗ Skip the job if the image type is not 'default' or 'minimal', or 'Push to production registries' is not checked (inputs.production set to false.)
The actions/checkout@v4 checkouts container-images into branch '${version_major}'. The repository directory is located at /home/runner/work/container-images/container-images and its subdirectory is named '${version_major}'. All commits for the branch are checkout with fetch-depth: 0.
This step is written in bash and is designed to:
- preserves 'default' and 'minimal' folders with Dockerfiles and RootFSs into
../tmp-${date_stamp}folder - checkouts into new local 'tmp' branch
- removes local ${version_major} branch
- checkouts into orphan ${version_major} branch
- restores 'default' and 'minimal' folders into the orphan branch placeholder
Uses EndBug/add-and-commit@v9 to commit and push Dockerfiles and RootFSs which were prepared on previous step. The following options are used to push:
--force- to rewrite history--set-upstream origin ${version_major}- to set upstream branch (as new one is orphan)
Tree illustration of the workflow Jobs and Steps for AlmaLinux 9 minimal image:
Publish images to the Docker Library
│
├── 8 default definition preparing
.
.
.
├── 8 minimal definition preparing
.
.
.
├── 9 default definition preparing
.
.
.
├── 9 minimal definition preparing
│ ├── Set up job
│ ├── Checkout container-images, branch '9'
│ ├── Checkout official-images, branch 'master'
│ ├── Get need data for the definition
│ ├── Render the definition
│ ├── Upload the definition for 9 minimal
│ ├── Post Checkout official-images, branch 'master'
│ ├── Post Checkout container-images, branch '9'
│ └── Complete job
│
└── Create Pull Request with the new definition file
├── Set up job
├── Checkout official-images, branch 'master'
├── Sync official-images with docker-library/official-images, branch 'master'
├── Download all definitions
├── Create head of official-images/library/almalinux
├── Merge definitions into official-images/library/almalinux
├── Prepare date stamp
├── Prepare time stamp
├── Commit and push official-images/library/almalinux
├── Create Pull Request for official-images/library/almalinux
├── Post Checkout official-images, branch 'master'
└── Complete job
The workflow inputs are:
-
pr- boolean 'Publish to the Docker Official Library' with the default valuetrue(checked). The input indicates whether to create a Pull Request to Docker with AlmaLinux Definition File. -
draft- boolean 'Draft Pull Request' with the default valuefalse(not checked). The input indicates whether the Pull Request is draft or it is ready to review.
Job iterates (using matrix) with AlmaLinux all version_major, and image_types (default and minimal). Multiple jobs run simultaneously for each of the versions and each of the image types.
The actions/checkout@v4 checkouts container-images into branch '${version_major}'. The repository directory is located at /home/runner/work/container-images/container-images. All commits for the branch are checkout with fetch-depth: 0.
The actions/checkout@v4 checkouts container-images into branch 'master'. The repository directory is located at /home/runner/work/container-images/official-images.
That's your fork of docker-library/official-images repository.
The step is written in bash. It reads the # Tags: string and the commit hash of Containerfiles/${{ matrix.version_major }}/Containerfile.image_types file changed by the Build, test and push workflow. env.tags and env.last_commit are exported. These data will be used to generate part of Definition File.
The chuhlomin/render-template@v1 generates from the docker-library-definition.tmpl using data (env.tags, env.last_commit, matrix.version_major and matrix.image_types) file official-images/library/almalinux.version_major.image_types. The file is a part of Docker Library Definition File.
The step uses actions/upload-artifact@v4 to store an artifact generated in the previous step official-images/library/almalinux.version_major.image_types. The artifact is named against version_major and image_type, following the pattern: definition-${version_major}.${image_types}.
Artifacts are used to transfer files between different jobs of the same workflow. The artifact is a zip archive of the file without file-path included.
It is also possible to download artifacts via GitHub Action's web interface.
The job is skipped if the 'Publish to Docker Official Library' isn't checked (
inputs.prset intofalse)
The actions/checkout@v4 checkouts container-images into branch 'master'. The repository directory is located at /home/runner/work/container-images/official-images.
That's your fork of docker-library/official-images repository.
The step is written in bash. It uses GitHub CLI to sync the docker-library-official-images with the official-images upstream repository.
Uses actions/download-artifact@v4 to download multiple (merge-multiple: true) artifacts with generated definitions. The files are saved into the official-images/library/ directory.
Creates heading for the Docker Definition File.
The step is written in bash. It appends the official-images/library/almalinux Definition File with downloaded on the previous step definitions official-images/library/almalinux.version_major.image_types.
Generates date_stamp in the YYYYMMDD format. It is used in the commit message and pull request title.
Generates time_stamp in the HH:MM:SS format. It is used in the commit message and pull request title.
Uses EndBug/add-and-commit@v9 to commit and push the generated Definition File.
The commit message is:
AlmaLinux auto-update - ${{ env.date_stamp }} ${{ env.time_stamp }}.It will try to pull recent changes (before push) with
--rebase --autostash
The step is written in bash. It uses Github CLI to create a Pull Request for the official-images/library/almalinux Definition File from your fork and to docker-library/official-images repository.
The Pull Request will be drafted if the draft input is checked. When ready, mark the request as ready for review.
