Turquoise

Preface

There are many ways to create a Linux distro. Many people will end up deciding to use LinuxFromScratch, NixOS, or Cubic. This guide will go over creating a Fedora Silverblue derivative using blue-build. If at any point you get stuck, please use the blue-build docs. If you are still stuck, feel free to ask in #turquoise on the Hack Club Slack

For this guide, we are making an immutable distro. That means that the user's filesystem layers on our underlying image without actually replacing anything. This approach is the future of Linux and comes with many benefits such as how the whole system is updated in one go, and an update will not apply if anything goes wrong, meaning you will always have a working computer. This will be important to understand

This guide assumes you know some basic linux terminology. Please use the following list and research what each word you don't know means (if any):

• kernel
• package manager
• distro
• bash

Development Environment Setup

Automatic setup using the BlueBuild Workshop

The automatic setup will apply some default configuration and set up cosign for you.

The Workshop is a currently work-in-progress part of BlueBuild that allows managing custom image repositories using a web interface. Report issues in the GitHub repository: blue-build/workshop.

1. Open https://workshop.blue-build.org/.
2. Press "Log in with GitHub".

3. Press "New custom image repository".

4. Choose a name for your repository and press "Create repository".
   • This name should not contain spaces, slashes, or other special non-ascii characters. Using a dash (-) for delimitating words is recommended.

5. Wait for the repository to be set up

6. When prompted with setting up container signing, it is recommended to do it automatically.
   • If you have security concerns, skipping is an option too. Read more about this in the wizard.

7. After that step is completed, you're done! You can now clone your repository, open recipes/recipe.yml and start customizing! The reference section of the documentation is your friend here.

Below is the default recipe:

---
# yaml-language-server: $schema=https://schema.blue-build.org/recipe-v1.json
# image will be published to ghcr.io/<user>/<name>
name: KaylOS
# description will be included in the image's metadata
description: This is my personal OS image.

# the base image to build on top of (FROM) and the version tag to use
base-image: ghcr.io/ublue-os/silverblue-main
image-version: 41 # latest is also supported if you want new updates ASAP

# module configuration, executed in order
# you can include multiple instances of the same module
modules:
  - type: files
    files:
      - source: system
        destination: / # copies files/system/* (* means everything inside it) into your image's root folder /

  - type: rpm-ostree
    repos:
      - https://copr.fedorainfracloud.org/coprs/atim/starship/repo/fedora-%OS_VERSION%/atim-starship-fedora-%OS_VERSION%.repo
    install:
      - micro
      - starship
    remove:
      # example: removing firefox (in favor of the flatpak)
      # "firefox" is the main package, "firefox-langpacks" is a dependency
      - firefox
      - firefox-langpacks # also remove firefox dependency (not required for all packages, this is a special case)

  - type: default-flatpaks
    notify: true # Send notification after install/uninstall is finished (true/false)
    system:
      # If no repo information is specified, Flathub will be used by default
      install:
        - org.mozilla.firefox
        - org.gnome.Loupe
      remove:
        - org.gnome.eog
    user: {} # Also add Flathub user repo, but no user packages

  - type: signing # this sets up the proper policy & signing files for signed images to work fully

Preinstalled Applications

rpm-ostree (reference)

rpm-ostree is the system package manager of all Fedora immutable distros and derivatives. It is very comparable to the non-immutable variant dnf. It requires a reboot and, unlike most other package managers we will cover, has the potential to make your system unstable if used with the wrong packages. For this reason, we recomend you use it sparingly.

To use it, you have 6 things you can add to the rpm-ostree: configuration under modules in recipe.yml:

• install: for applications that you want to install
• remove: for applications on the default image you want to uninstall
• replace: for applications on the default image you would like to replace
• repos: for specifiying CoPr or third party repositories
• keys: for importing GPG keys for those repositories
• optfix: for a list of directories of applications that need to install in the /opt directory

Here I want to install vscode from the Microsoft repos. To do that I would add:

- https://packages.microsoft.com/yumrepos/vscode/config.repo

to repos:

- https://packages.microsoft.com/keys/microsoft.asc

to keys:

and

- code

to install:

This would give me a complete rpm-ostree section of

- type: rpm-ostree
    repos:
      - https://copr.fedorainfracloud.org/coprs/atim/starship/repo/fedora-%OS_VERSION%/atim-starship-fedora-%OS_VERSION%.repo
      - https://packages.microsoft.com/yumrepos/vscode/config.repo
    keys:
      - https://packages.microsoft.com/keys/microsoft.asc
    install:
      - micro
      - starship
      - code
    remove:
      # example: removing firefox (in favor of the flatpak)
      # "firefox" is the main package, "firefox-langpacks" is a dependency
      - firefox
      - firefox-langpacks

flatpak (reference)

flatpaks are containerized applications that run as containers and are completely unified between distros. This means that when you install a flatpak on Ubuntu, it will be exactly the same as when install it on Arch Linux. This standardization is why this is the recomended way to preinstall software.

If you are new to flatpaks, it is recomended that you install packages under system.

The only things you really need to know to use it are install and remove which both need the reverse URL notation, also known as the app id. To find this ID, all you need to do is search for the app you want on flathub and copy the end of the url.

Then simply add it to install or remove in a similar fasion to rpm-ostree.

- type: default-flatpaks
    notify: true # Send notification after install/uninstall is finished (true/false)
    system:
      # If no repo information is specified, Flathub will be used by default
      install:
        - org.mozilla.firefox
        - org.gnome.Loupe
        - com.brave.Browser
      remove:
        - org.gnome.eog
    user: {} # Also add Flathub user repo, but no user packages

bling

bling is a install helper for a select few features that you might find useful. It can install any of the following modules:

• rpmfusion
• negativo17
• ublue-update
• 1password
• dconf-update-service
• gnome-vrr

This guide won't go into what each of these are, but if you are interested, you can quite easily look it up.

To add any of these modules, simply add it to the install: property. An example is shown below using rpmfusion, an alternate package repository.

- type: bling
  install:
    - rpmfusion