image-template

Purpose

This repository is meant to be a template for building your own custom Universal Blue image.

Prerequisites

Working knowledge in the following topics:

• Containers
  • https://www.youtube.com/watch?v=SnSH8Ht3MIc
  • https://www.mankier.com/5/Containerfile
• bootc
  • https://containers.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

The top line is the base image you want to start FROM. Any valid image can be a starting point, examples include:

FROM ghcr.io/ublue-os/bazzite:latest FROM ghcr.io/ublue-os/bluefin:stable FROM ghcr.io/ublue-os/aurora-dx:stable

"Emtpy base images"

These contain a base system WITHOUT a prexisting desktop. This is recommended for

FROM ghcr.io/ublue-os/base-main:latest

Use base-nvidia:latest if you need the Nvidia drivers. You can also lock to a specific version like base-nvidia:41, etc.

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.

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 into your git repository

Examples

• m2os
• bos
• homer