How to Create Your Own Custom uBlue-OS Variant from Scratch

---

TL;DR

• Define Your OS in Code: Use ublue-os/image-template on GitHub to define your custom operating system image via build.sh or Containerfile.
• Automated CI & Cryptographic Signing: Generate a Cosign keypair (cosign generate-keypair), add your private key to GitHub Actions secrets (SIGNING_SECRET), and automatically compile and sign container images on GHCR.
• Rebase & Update via bootc: Switch physical hardware to your custom container image with sudo bootc switch ghcr.io/USER/REPO:latest and apply ongoing updates with sudo bootc update.
• Safe Package Validation: Use toolbox create && toolbox enter to test DNF package names before adding them to your OS image repository.

---

Universal Blue (uBlue-OS) represents the future of desktop Linux administration: an immutable, container-native operating system built on top of Fedora Atomic Desktop and OCI containers.

Rather than manually installing packages, tweaking scripts, and managing system state across multiple machines, uBlue-OS allows you to define your entire operating system image in code. You build your OS image in GitHub Container Registry (GHCR) via GitHub Actions, sign it with cryptographic keys, and rebase your physical hardware directly onto your custom container image.

This step-by-step guide walks through creating, signing, rebasing, and updating your own custom uBlue-OS variant from scratch.

---

Prerequisite Checklist

Before starting, ensure your system meets the following requirements:

Verify your system is running bootc:

sudo bootc status

---

Step 1: Create Your Repository from ublue-os/image-template

1. Navigate to the official template on GitHub: github.com/ublue-os/image-template.
2. Click Use this template -> Create a new repository.
3. Set your repository name (e.g., my-custom-ublue).
4. Set visibility to Public (required for free GitHub Container Registry hosting).
5. Clone your newly generated repository to your local machine:

git clone git@github.com:YOUR_USERNAME/my-custom-ublue.git
cd my-custom-ublue

---

Step 2: Install Cosign & Generate Cryptographic Signing Keys

uBlue-OS images use Cosign to cryptographically sign container builds, ensuring your bootloader only installs verified images.

1. Install Cosign

# On systems with Homebrew / Linuxbrew:
brew install cosign

# Or download binary directly via Cosign GitHub releases

2. Generate Keypair

Inside your cloned repository folder, generate an unpassphrased keypair:

cosign generate-keypair

When prompted for a passphrase, press Enter twice (no password for automated CI signing).

This generates two files in your directory:

• cosign.key (Private signing key — DO NOT COMMIT TO GIT)


• cosign.pub (Public key — Will be committed to repository root)

The template's .gitignore file automatically excludes cosign.key to prevent accidentally committing your private key to public GitHub repositories.

---

Step 3: Configure GitHub Signing Secret & Commit Public Key

1. Add Private Key to GitHub Secrets

1. Open your repository on GitHub.
2. Go to Settings -> Secrets and variables -> Actions.
3. Click New repository secret.
4. Set Name: SIGNING_SECRET
5. Print your private key in terminal and copy the entire output:

cat cosign.key

6. Paste the contents into the secret Value field and click Add secret.

2. Commit Public Key to Repository

Commit the public key cosign.pub to the root of your git repository:

git status
git add cosign.pub
git commit -m "Add cosign public key"
git push origin main

---

Step 4: Monitor GitHub Actions Build

Pushing cosign.pub triggers the automated GitHub Actions build workflow:

1. Click the Actions tab in your GitHub repository.
2. Watch the container build process: it compiles your image, signs it using SIGNING_SECRET, and publishes the finished container to GitHub Container Registry (GHCR).
3. Once complete, your container image will be available at:

ghcr.io/YOUR_USERNAME/my-custom-ublue:latest

---

Step 5: Rebase & Switch Your OS with bootc

Now that your container image is built and signed on GHCR, switch your physical operating system to boot from your custom image!

1. Execute bootc switch

sudo bootc switch ghcr.io/YOUR_USERNAME/my-custom-ublue:latest

Provide your sudo password. bootc will pull the container layers and stage the new deployment.

2. Reboot System

sudo systemctl reboot

3. Verify Active Booted Image

After rebooting, open your terminal and verify your active OS image:

sudo bootc status

You are now officially running your custom containerized Linux OS build!

---

Step 6: Testing & Adding Software Packages

One of the greatest features of uBlue-OS is the ability to easily customize installed packages in code (build.sh or recipe.yml / Containerfile).

1. Test Package Installs Safely via toolbox

Before adding software packages to your OS build file, test them inside a disposable Toolbox container to verify DNF package names:

# Create and enter a disposable Fedora container
toolbox create
toolbox enter

# Test package installation inside toolbox
sudo dnf install tmux krita

# Exit toolbox when verified
exit

2. Add Packages to Build Configuration

Add your verified packages to build.sh or Containerfile inside your cloned repository:

# Example snippet in build.sh:
rpm-ostree install tmux krita zsh

3. Commit, Push & Apply System Updates

git add .
git commit -m "Add tmux, krita, and zsh to custom build"
git push origin main

Once GitHub Actions finishes building the new container layer (~2–3 minutes), apply the update live without reinstalling:

# Pull and apply updated container layers
sudo bootc update

# Reboot to enter updated system state
sudo systemctl reboot

---

Safety Net: Instant System Rollback

If an update ever introduces an unwanted change, uBlue-OS keeps your previous system deployment intact:

# Instantly roll back to your previous working OS deployment
sudo bootc rollback