User:Sangy/archlinux-docker

Archlinux Official Image Process Documentation

What is this?

This document contains information about how the official archlinux image is built and published. It also contains a list of goals for the project moving forward.

Build process

In order to build the official images, the Docker library team requires us to generate a all the artifacts that they will use in their docker builds. In the context of a distribution image (e.g., Debian or Arch Linux) this basically means generating the rootfs and any ancillary files that may be needed. For the Arch Linux build, we only create the rootfs in our infrastructure, and the rest of the operations are done inside of the Docker build.

Once all the required artifacts are created, they need be handed off to the library team, who will fetch them from a GitHub repository and schedule a build in their infrastructure. To do this, we are required to submit a pull-request to their official-images repository with all the meta-information required by the build. This information is used by their build tool, bashbrew, and contains things such as the build architecture, the git remote from which to fetch the artifacts and the like.

In other words, in order to produce a new image, we the following steps need to happen:

1. A build is kicked off in the Arch Linux infrastructure. This is scheduled to happen on the 5th of each month (see the docker-image role in our infrastructure repository for more information)
2. Once a new rootfs and all the required artifacts are generated, a new tag in the archlinux/archlinux-docker repository must be made. The tagname follows the DDMMYYYY format. The tag is then pushed to the canonical repository. There are two requirements to keep in mind when tagging a build:
   1. That there are no other copies in the artifacts in the history (i.e., the contents of the older tag are in any of the parent commits)
   2. There are no objects larger than 100MB. This is because the bashbrew toolchain does not have support for git-lfs.
3. With all the artifacts hosted on GitHub, a pull-request for the official-images repository. In it, the latest Docker tag needs to be updated to match the new id of the newly-created git tag ID. Optionally, the older tag can be kept by using the DDMMYYYY Docker tag format. Please see a previous PR to see how this is done.
4. Once the PR is merged, the docker build is kicked off on the docker-library side and, if successful, it is eventually released in docker hub under the _/archlinux namespace

Creating the artifacts

The most critical part of a release is creating the build artifacts. To ensure transparency, reproducibility, audit-ability, and to increase the bus factor release artifacts are automatically built on the Arch Linux infrastructure. The build process is namespaced to its own user (again, see the infrastructure.git repository) and kicked off by a systemd timer on the 5th of each month. When the timer is hit, and the “make rootfs” job is triggered.