Installation Runbook#

In order to set yourself up for success, it's useful to plan out your Bluefin installation into phases so that you can avoid common pitfalls and poorly supported configurations. On Linux-friendly hardware, booting into the installation process and clicking through the recommended installer defaults is usually enough. But you can never be too sure—here's the nitty-gritty in case you need it.

This page is a short runbook for the Bluefin installation process. Read the entirety of this documentation to ensure survival (in case of a raptor attack).

Support Tiers#

Bluefin is purposely designed to follow the state of the art of Linux development, the project optimizes a "golden path" to provide users the best chance to succeed. However sometimes you just get lucky (or unlucky). This section is inspired by Homebrew's support tiers. Not all configurations are supported. Here is a quick guide:

Tier 1 - The best experience#

A Tier 1 configuration is considered fully supported. These configurations receive the highest level of coverage and are prioritized.

Requirements#

• Linux friendly hardware (no external kernel modules required)
  • Linux laptop vendors may or may not fall under this tier.
  • "Our hardware is fully supported in the upstream Linux kernel" ← good
  • "We only support Ubuntu 24.04" ← probably not good
• Software packaged for modern Linuxes (Flatpak for desktop apps, containers for development, etc)

Users can expect#

• The most reliable and intended Bluefin experience

Recommendation: Bluefin

Tier 2 - You're probably ok#

A Tier 2 configuration is not fully supported and may contain compromises due to hardware or software choices.
It can mostly work but may need post-install configuration. Some of these work fine but are put here because the software is delivered by the vendor and not something the team can control like Nvidia drivers.

Requirements#

• NVidia GPUs on desktops
• Some Linux laptop vendors may fall under this tier
  • Might have good kernel support but needs an external module for a fan controller or some other component
• Locally layered packages or other software configurations not covered in the documentation
• ARM/aarch64 hardware - the core team does not have access to this hardware but generates images for the community

Users can expect#

• Unreliable upgrades and manual system maintenance
  • The team typically does not take these configurations into account when testing.
• Generally works fine day to day

Recommendation: Try Bluefin and see how it runs. Some people make custom images, investigation may be needed.

Tier 3 - Who knows?#

Tier 3 is mostly unsupported - it may work perfectly or be a disaster.

Requirements#

• Known problematic hardware (Asus and Apple laptops)
• Dual GPU laptops with Nvidia hardware
• Old school "good luck with this!" packaging formats
  • .run files, tarballs, and Appimages
  • Anything where the software asks for DKMS
• Exotic hardware in general - in some cases a Tier 3 installation may be used as bragging rights.

Users can expect#

• Unreliable upgrades and manual system maintenance
  • The team typically does not take these configurations into account when testing.
• "Flaky support" - wireless may or may not work occasionally, suspend/resume issues, etc.

Recommendation: Ubuntu or a custom image.

System Requirements#

Review the Fedora Silverblue installation instructions. Some differences to consider:

• Use the Fedora Media Writer to create installation media. Other creation methods may not work properly
  • Use of Ventoy is unsupported
• Older BIOS-based systems are unsupported; only UEFI systems are supported
• Dual booting off of the same disk is unsupported; use a dedicated drive for another operating system and use your BIOS to choose another OS to boot off of
  • Bluefin supports an installation on an external drive if you want to try it on bare metal before committing
• We strongly recommend using automated partitioning during installation; there are known issues with manual partitioning on Atomic systems and it is unnecessary to set up unless you are on a multi-disk system
• A stock Bluefin installation is 11GB. Bluefin with developer mode enabled (bluefin-dx) is 19GB

Quick Reference#

Disk Usage#

This is how much disk space each image of Bluefin by default, this includes the flatpak applications (which can be removed):

Bluefin#

~12.4 GB / ~17.4 GB with developer mode enabled

Bluefin LTS#

~13.2 GB / ~14.5 GB with developer mode enabled

Bluefin GDX#

~18.1 GB (Developer mode included)

Why 16 GB RAM Minimum?#

Bluefin ships with an extensive cloud-native development stack. These workloads typically scale out to replicate entire clusters of computers and demand more resources than typical workloads.

These requirements ensure smooth operation of Bluefin's integrated development workflow and container-first architecture.

Day 0: Planning#

Most pain points can be addressed directly by planning ahead of time. Note that the term "Day" is an abstract—please do not install Bluefin over the course of three days. Typically, an installation should take about twenty minutes.

All Users#

• Is your hardware Linux-friendly?
  • Do you understand the limitations of having an Nvidia GPU (if applicable)?
    • Nvidia Optimus laptops tend to be particularly troublesome
  • Does the hardware require an out-of-tree kernel module? This may lead to long-term maintenance issues
  • Does the software you use require an out-of-tree kernel module?
    • VirtualBox and VMware are not supported
    • Nvidia, Xbox One Controller Support, wl drivers, and v4l2loopback are supported (these are "best effort"; in certain cases we cannot control third-party software that breaks with newer versions of the Linux kernel)
    • openzfs is included out of the box. It is used by maintainers regularly and has not yet fallen behind the kernels Bluefin ships. However, we still cannot guarantee this as it is an out-of-tree kernel module
  • Is your wireless card supported by Linux?
    • Poorly supported cards include Broadcom
    • Check USB-Wifi if you are not sure
  • Is your printer/scanner well supported in Linux?
    • Driverless printers are strongly recommended; we cannot guarantee every printer will work
    • Scanner support
• Is the BIOS/UEFI up to date on the device?
• We recommend having all hardware firmware updates completed and up to date before installation
• Are the applications you depend on well supported on Flathub?
• Does your VPN provider provide a wireguard configuration to import into Network Manager?
• Dedicated disk ready to go?
  • Bluefin does not support dual booting from the same disk
  • Bluefin does not support rebasing from a pre-existing installation of Fedora
• Remember that this is a custom Fedora based image, it does move at a brisk pace compared to something like Ubuntu LTS
• Read this documentation in its entirety, here's some associated upstream documentation:
  • Homebrew (Donate)
  • Flathub
  • bootc

Developers#

• Do you know how to use containers for development?
• Do you know how to manage systemd service units for both the system and user accounts?

Day 1: Deployment and Configuration#

Deployment#

• Install the operating system
  • Use the entire disk with automatic partitioning
  • (Optional): Set up Secure Boot
  • (Optional): ujust rebase-helper to move to :stable or :latest
• Set up, test, and verify backups - While the system image is reproducible data, your user data in your home folder still needs to be backed up. Bluefin ships with two backup utilities depending on your preference. They are installed as Flatpaks so you can remove the one you don't use. rclone (Donate) and restic (Donate) are also preinstalled if you prefer command line tools
  • Deja Dup (Donate)
  • Pika Backup (Donate)
  • Ensure your backups are functional before moving on to configuration

Configuration#

The rest of these steps are user specific configuration and something that we tend to leave up to you. Automating this step is a good place to use tools like chezmoi for dotfile configuration and syncing: brew install chezmoi

Since the user space is all in your home directory, any tool you use to automate this step should work as you expect. Ideally, configuration that you might have done at the system level in the past is configured at your user level now, leading to a clean separation between user configuration and the system image.

• Software Installation
  • Use the Bazaar store to install applications
  • (Optional): Install Command line applications via brew
• Post-installation Configuration
  • Select/Change default applications as you see fit
  • (Optional) Import your wireguard configuration via wg-quick or use the VPN configuration in the network manager GUI
• (Optional) Developer Configuration
  • ujust devmode and follow the directions
  • Start VSCode and configure your settings and extensions

Day 2: Operations and Maintenance#

Bluefin strives to make maintenance as straightforward as possible, however many of the automated tasks can be run manually.

• Run a System Upgrade via the menu option or ujust update to observe an update and reboot
  • ujust changelogs will show incoming changes and updates coming from Fedora
  • ujust bios will reboot the machine and enter the BIOS/UEFI menu. This is useful for booting into a Windows drive
• Subscribe to the blog
• Understand rebase and rollback procedures
• Use the Warehouse application to manage Flatpak lifecycle:
  • Pin to an old version or rollback
  • Easily remove applications at once
• ujust clean-system to clean up old containers and unused flatpak runtimes

And one more piece of advice: The more you invest into day 0, the smoother your day 1 will be, which results in an even smoother day 2. After that, it's all bragging rights. The fastfetch (Donate) command will be there to remind you of your milestone:

Secure Boot#

Secure Boot is supported by default providing an additional layer of security.

Universal Blue supports secure boot with our custom key.

After installation completes, during first boot you will be prompted to enroll the secure boot key using the mokutil UEFI menu UI (QWERTY keyboard input and navigation).

Select Enroll MOK, and input universalblue as the password.

If this step is not completed during the initial setup, you can manually enroll the key by running the following command in the terminal:

ujust enroll-secure-boot-key

If you'd like to enroll this key prior to installation or rebase, download the key and run the following:

sudo mokutil --timeout -1
sudo mokutil --import path/to/public_key.der

You can use mokutil --list-enrolled to confirm that the "ublue kernel" key is listed:

Lenovo ThinkPad users (P, T, X series): Before enabling Secure Boot, go to BIOS (F1) → Security → Secure Boot and enable "Allow Microsoft 3rd party UEFI CA". This setting is required for Fedora's signed shim bootloader to be recognized by the firmware. Without it, Secure Boot will fail with a violation error.