Building a Custom Bluefin Image#

Overview#

finpilot is the recommended template for building custom Bluefin images. Rather than forking Bluefin and patching it, finpilot lets you assemble your own Bluefin by consuming the same centralized OCI containers that official variants — Bluefin, Aurora, Bluefin LTS, and dakotaraptor — are built from 1. This means you inherit shared maintenance improvements automatically without rebasing against a fork.

The core constraint is simple: all modifications happen at build time. The OS is delivered as a complete, signed container image. There is no runtime package installation — everything you want in the image must be incorporated during the build via the Containerfile and build scripts 2 3.

Getting Started#

Fork the Template#

1. Go to github.com/projectbluefin/finpilot and click "Use this template" to create a new repository.
2. Rename the project by replacing every instance of finpilot with your repository name in these six files 4:
   • Containerfile
   • Justfile
   • README.md
   • artifacthub-repo.yml
   • custom/ujust/README.md
   • .github/workflows/clean.yml
3. Enable GitHub Actions in the Actions tab of your new repository.

Repository Layout#

Note: Flatpaks are not embedded in the image. They are declared in custom/flatpaks/ and downloaded on first boot after network setup. 10

Choosing a Base Image#

The Containerfile defaults to ghcr.io/ublue-os/silverblue-main:latest (GNOME desktop included). Alternative bases are commented in the file 2:

# Base Image - GNOME included (default)
FROM ghcr.io/ublue-os/silverblue-main:latest@sha256:...

# Fedora base without a desktop environment
# FROM ghcr.io/ublue-os/base-main:latest

# CentOS Stream 10 base
# FROM quay.io/centos-bootc/centos-bootc:stream10

Uncomment the alternative that suits your use case.

Building Locally#

All local build and test operations are driven by the Justfile 5.

Typical local dev loop:

just build # Build the container
just build-qcow2 # Convert to a VM disk image
just run-vm-qcow2 # Boot and test in a VM

rebuild-* variants (e.g., just rebuild-qcow2) chain just build and the conversion step together in one command.

CI/CD with GitHub Actions#

The included .github/workflows/build.yml handles the full automated pipeline 11:

• Triggers: pull requests, pushes to main, daily schedule (10:05 UTC), and manual dispatch.
• PR builds validate the image without pushing to the registry.
• Merges to main build and push a :stable tag to ghcr.io/YOUR_USERNAME/YOUR_REPO.
• Optional: image signing with Cosign and SBOM generation with Syft are already wired into the workflow — enable them by adding the required secrets to your repository.

Automatic Dependency Updates with Renovate#

The included .github/renovate.json5 keeps your image's upstream dependencies current automatically 12:

• Tracks container image digests in both Containerfile and Justfile.
• Auto-merges digest-only updates (safe, reproducibility-preserving changes).
• Tracks and updates pinned GitHub Actions versions.
• Requires manual review for rechunk-related updates.

No configuration changes are needed — Renovate runs automatically once your repository is connected to the Renovate app.

Customization Examples#

Build scripts in build/ execute in ascending numerical order during the image build 6. 10-build.sh runs first. Add your own scripts with higher numbers to extend the system without modifying the base script.

Two example scripts are included to illustrate common patterns:

Adding Third-Party RPM Repositories#

build/20-onepassword.sh.example demonstrates adding external RPM repositories (Google Chrome, 1Password) and cleaning up the repo file after installation so it doesn't persist in the image 13.

Replacing the Desktop Environment#

build/30-cosmic-desktop.sh.example shows how to remove GNOME and install the COSMIC desktop from System76's COPR instead 14. It uses the copr_install_isolated() helper from build/copr-helpers.sh 15, which enables a COPR, installs from it, then disables it — preventing the COPR repo from being baked into the final image.

Enabling an Example Script#

# Remove the .example extension and make it executable
mv build/20-onepassword.sh.example build/20-onepassword.sh
chmod +x build/20-onepassword.sh

The build system picks it up automatically on the next just build.

Script Template#

#!/usr/bin/env bash
set -eoux pipefail

# Your build-time modifications here
dnf5 install -y your-package

Use dnf5 (not dnf or yum) for package management. Scripts run as root with the build context available at /ctx.

Deploying to Your Machine#

Once your image is built and pushed to ghcr.io, switch to it from any running Bluefin (or compatible bootc) system 4:

sudo bootc switch ghcr.io/YOUR_USERNAME/YOUR_REPO:stable
sudo systemctl reboot

Your home directory, Flatpak applications, and configurations are preserved across the switch. The previous deployment is kept as a rollback target — if something goes wrong, run:

bootc rollback

Tip: Keep your repository public so your machine can pull the image without authentication. For private registries, configure credentials via podman login before switching.

References#