YoRHa (寄葉) "passing leaf" — Immutable Arch Linux distribution with OSTree

• Overview
• Design philosophy
• Installation
• Development
  • Flavors
• Tentative goals
• Credits
• License

Complementary blog post can be found here.

Overview

This repository provides a toolkit for building and deploying OSTree-based Linux distributions. While Arch Linux is the default base, it is possible to use alternative distributions like Debian, Fedora, Alpine and friends simply by adding them under base (see archlinux for reference). However, please note that effort currently focuses exclusively on Arch Linux.

Design philosophy

YoRHa is built around the concept of an atomic desktop: where the core system is kept minimal, immutable, and read-only. This approach enables reproducible deployments and versioned rollbacks, making upgrades and recoveries simple and dependable through OSTree. The root filesystem is created via containers, ensuring a clean and consistent environment each time, and each deployment performs a factory reset of the system configuration (unless overridden).

Graphical applications are installed via Flatpak whenever possible providing isolation and easy updates. Developers and power users can utilise toolbox containers for command-line tools and development environments, keeping the base system uncluttered. This separation means your system, graphical, and command-line workloads each operate in their own dedicated space.

At a higher level, the end system is comprised of:

• OSTree: Atomic updates and rollback mechanism with a read-only, immutable root filesystem
• Toolbox: Disposable development containers
• Flatpak: Sandboxed application deployment for GUI software
• Podman: Containerised system image creation for OSTree deployments
• Arch Linux (by the way).

Upgrades are performed by building a new container image with podman or by using the provided GitHub container repository. If you hit a problem, you can easily roll back to the previously working deployment.

Note

Configuration files from my dotfiles repository are copied to /etc/skel during image creation, so every new user account is automatically set up with a complete and consistent environment. You can of course swap these files with your own configurations if preferred.

Installation

It is recommended to use a live environment such as the Arch Linux ISO to bootstrap YoRHa to a drive. The following instructions are based on this setup; if you use a different system, the process or results may differ.

1. Install the necessary dependencies needed to bootstrap a system:

# pacman --noconfirm -Sy git ostree podman

2. Clone this repository on a live system:

# git clone --recursive https://github.com/lcook/yorha /tmp/yorha

3. Prepare the disk for bootstrapping by running the below command. You will be prompted choose the target disk, which will then be automatically partitioned and formatted with XFS as the default filesystem. The setup creates three labeled partitions:
   • SYS_ROOT: root filesystem (/)
   • SYS_VAR: persistent data (/var)
   • SYS_BOOT: EFI boot partition (/boot/efi)

Note

Make sure to source the script to setup the environment variables correctly otherwise the bootstrap process will fail.

# . ./yorha live prep-disk # You MUST source the script!
# ./yorha live init

4. Deploy OCI containter image with OSTree with one of two methods below:

Pre-built GitHub Container Registry images (recommended for consumers)

Container images are built automatically by GitHub Actions and can be found here following each commit that passes the build pipeline, in addition to weekly scheduled builds to prevent stale images accruing. You may replace <-flavor> with the images detailed in Flavors.

# ./yorha live install ghcr.io/lcook/yorha/archlinux<-flavor>
# systemctl reboot

After rebooting, you can upgrade your system whenever new container images are available in the container registry. To check, run the following:

$ sudo yorha upgrade remote

Viola - you are now up and running! This is the more "hands-off" approach towards configuring the system, meanwhile the below grants the flexibility to do as you please with custom images.

Locally built images (recommended for development and custom images)

Alternatively, custom local images can be built and adapted to your liking. This can be helpful for situations when you want to make local modifications to the deployed image not available in the provided image in the GitHub Container Registry.

# ./yorha compose container-base
# ./yorha compose container
# ./yorha compose flavor <flavor> # Optional
# ./yorha live install
# systemctl reboot

This will build both the base image and then atop any custom settings or tweaks found here. To make additions after the initial bootstrapping phase, please read Development.

Note

The default root account password is set to ostree - please change this after logging in!

Development

For local development, it is suggested to clone this repository to your machine. By maintaining a local copy at ~/dev/yorha the version will override the system-installed libexec and yorha scripts (located in /usr/libexec/yorha-* and /usr/bin/yorha).

The fish shell configuration initially copied from /etc/skel into your home directory includes a check for the corresponding project directory (see this script). If the directory exists, it sets YORHA_BASE_PATH and YORHA_LIBEXEC_PATH; if it is absent, the yorha script falls back to the defaults defined in yorha-config.

To get started, clone both the main repository and the accompanying dotfiles, then execute the helper scripts to apply the chosen theme and establish the proper symlinks:

$ git clone --recursive https://github.com/lcook/yorha ~/dev
$ git clone https://github.com/lcook/dots ~/dev && cdots
$ ./0-themer [theme]
$ ./1-symlinks

When modifying container images, update the files under base/archlinux and rebuild the images by running:

$ sudo yorha compose container-base  # Build the base Arch Linux container image
$ sudo yorha compose container       # Build the OSTree image with your customisations
$ sudo yorha compose flavor <flavor> # Optionally build flavor
$ sudo yorha upgrade local           # Deploy the updated container built image via OSTree
$ systemctl reboot

Flavors

Flavors are purpose-specific overlays for the base image that add hardware specific packages, configurations and tweaks during image creation. Flavors live under base/archlinux/flavor.

Some provided images built:

• ghcr.io/lcook/yorha/archlinux-nvidia: Adds packages/configurations commonly required for systems using NVIDIA GPUs
• ghcr.io/lcook/yorha/archlinux-intel: Adds packages/configurations commonly required for systems using Intel integrated graphics.

These optionally can be built locally and deployed with the following:

$ sudo yorha compose flavor archlinux-nvidia # Syntax for `compose flavor` is [base]-[flavor]
$ sudo yorha upgrade local # Deploy after build

Tentative goals

• Refactor the yorha buildkit to leverage the OSTree C API replacing a handful of shell scripts, inspired by projects like rpm-ostree
• Expand support to include additional Linux distributions beyond Arch Linux
• Migrate to bootc once bootupd is better supported on non-Fedora systems.

Credits

Special thanks to GrabbenD (ostree-utility) for inspiration.

License

BSD 2-Clause