image-template

Purpose

This repository is meant to be a template for building your own custom Universal Blue image. This template is the recommended way to make customizations to any image published by the Universal Blue Project:

• Aurora
• Bazzite
• Bluefin
• uCore
• main
• hwe

or any other base image if you want to start from scratch:

• Fedora: quay.io/fedora/fedora-bootc:41
• CentOS Stream 9: quay.io/centos-bootc/centos-bootc:stream9
• CentOS Stream 10 (in development): quay.io/centos-bootc/centos-bootc:stream10

This template includes a Containerfile and a Github workflow for building the container image, signing, and proper metadata to be listed on artifacthub. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry.

Prerequisites

Working knowledge in the following topics:

• Containers
  • https://www.youtube.com/watch?v=SnSH8Ht3MIc
  • https://www.mankier.com/5/Containerfile
• bootc
  • https://bootc-dev.github.io/bootc/
• Fedora Silverblue (and other Fedora Atomic variants)
  • https://docs.fedoraproject.org/en-US/fedora-silverblue/
• Github Workflows
  • https://docs.github.com/en/actions/using-workflows

How to Use

Template

Select Use this Template and create a new repository from it. To enable the workflows, you may need to go the Actions tab of the new repository and click to enable workflows.

Containerfile

This file defines the operations used to customize the selected image. It contains examples of possible modifications, including how to:

• change the upstream from which the custom image is derived
• add additional RPM packages
• add binaries as a layer from other images

Building an ISO

This template provides an out of the box workflow for getting an ISO image for your custom OCI image which can be used to directly install onto your machines.

This template provides a way to upload the ISO that is generated from the workflow to a S3 bucket or it will be available as an artifact from the job. To upload to S3 we use a tool called rclone which is able to use many S3 providers. For more details on how to configure this see the details below.

Justfile Documentation

This Justfile contains various commands and configurations for building and managing container images and virtual machine images using Podman and other utilities.

Environment Variables

• repo_organization: The GitHub repository owner (default: "yourname").
• image_name: The name of the image (default: "yourimage").
• centos_version: The CentOS version (default: "stream10").
• fedora_version: The Fedora version (default: "41").
• default_tag: The default tag for the image (default: "latest").
• bib_image: The Bootc Image Builder (BIB) image (default: "quay.io/centos-bootc/bootc-image-builder:latest").

Aliases

• build-vm: Alias for build-qcow2.
• rebuild-vm: Alias for rebuild-qcow2.
• run-vm: Alias for run-vm-qcow2.

Commands

check

Checks the syntax of all .just files and the Justfile.

fix

Fixes the syntax of all .just files and the Justfile.

clean

Cleans the repository by removing build artifacts.

Build Commands

build

Builds a container image using Podman.

just build $target_image $tag $dx $hwe $gdx

Arguments:

• $target_image: The tag you want to apply to the image (default: aurora).
• $tag: The tag for the image (default: lts).
• $dx: Enable DX (default: "0").
• $hwe: Enable HWE (default: "0").
• $gdx: Enable GDX (default: "0").

Building Virtual Machines and ISOs

build-qcow2

Builds a QCOW2 virtual machine image.

just build-qcow2 $target_image $tag

build-raw

Builds a RAW virtual machine image.

just build-raw $target_image $tag

build-iso

Builds an ISO virtual machine image.

just build-iso $target_image $tag

rebuild-qcow2

Rebuilds a QCOW2 virtual machine image.

just rebuild-qcow2 $target_image $tag

rebuild-raw

Rebuilds a RAW virtual machine image.

just rebuild-raw $target_image $tag

rebuild-iso

Rebuilds an ISO virtual machine image.

just rebuild-iso $target_image $tag

Run Virtual Machines

run-vm-qcow2

Runs a virtual machine from a QCOW2 image.

just run-vm-qcow2 $target_image $tag

run-vm-raw

Runs a virtual machine from a RAW image.

just run-vm-raw $target_image $tag

run-vm-iso

Runs a virtual machine from an ISO.

just run-vm-iso $target_image $tag

spawn-vm

Runs a virtual machine using systemd-vmspawn.

just spawn-vm rebuild="0" type="qcow2" ram="6G"

Lint and Format

lint

Runs shell check on all Bash scripts.

format

Runs shfmt on all Bash scripts.

Workflows

build.yml

This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). By default, the image name will match the Github repository name.

build-iso.yml

This workflow creates an ISO from your OCI image by utilizing the bootc-image-builder to generate an ISO. In order to use this workflow you must complete the following steps:

• Modify iso.toml to point to your custom image before generating an ISO.
• If you changed your image name from the default in build.yml then in the build-iso.yml file edit the IMAGE_REGISTRY and DEFAULT_TAG environment variables with the correct values. If you did not make changes, skip this step.
• Finally, if you want to upload your ISOs to S3 then you will need to add your S3 configuration to the repository's Action secrets. This can be found by going to your repository settings, under Secrets and Variables -> Actions. You will need to add the following
  • S3_PROVIDER - Must match one of the values from the supported list
  • S3_BUCKET_NAME - Your unique bucket name
  • S3_ACCESS_KEY_ID - It is recommended that you make a separate key just for this workflow
  • S3_SECRET_ACCESS_KEY - See above.
  • S3_REGION - The region your bucket lives in. If you do not know then set this value to auto.
  • S3_ENDPOINT - This value will be specific to the bucket as well.

Once the workflow is done, you'll find it either in your S3 bucket or as part of the summary under Artifacts after the workflow is completed.

Container Signing

Container signing is important for end-user security and is enabled on all Universal Blue images. It is recommended you set this up, and by default the image builds will fail if you don't.

This provides users a method of verifying the image.

1. Install the cosign CLI tool

2. Run inside your repo folder:

   cosign generate-key-pair

   • Do NOT put in a password when it asks you to, just press enter. The signing key will be used in GitHub Actions and will not work if it is encrypted.

Warning

Be careful to never accidentally commit cosign.key into your git repo.

3. Add the private key to GitHub

   • This can also be done manually. Go to your repository settings, under Secrets and Variables -> Actions Add a new secret and name it SIGNING_SECRET, then paste the contents of cosign.key into the secret and save it. Make sure it's the .key file and not the .pub file. Once done, it should look like this:

   • (CLI instructions) If you have the github-cli installed, run:

   gh secret set SIGNING_SECRET < cosign.key

4. Commit the cosign.pub file to the root of your git repository.

Community

• bootc discussion forums - Nothing in this template is ublue specific, the upstream bootc project has a discussions forum where custom image builders can hang out and ask questions.

Artifacthub

This template comes with the necessary tooling to index your image on artifacthub.io, use the artifacthub-repo.yml file at the root to verify yourself as the publisher. This is important to you for a few reasons:

• The value of artifacthub is it's one place for people to index their custom images, and since we depend on each other to learn, it helps grow the community.
• You get to see your pet project listed with the other cool projects in Cloud Native.
• Since the site puts your README front and center, it's a good way to learn how to write a good README, learn some marketing, finding your audience, etc.

Discussion thread

Community Examples

• m2os
• bos
• homer