YoRHa - Immutable Arch Linux distribution built with OSTree
This repository provides a toolkit for building and deploying OSTree-based Linux distributions. While Arch Linux is the preferred base, it is possible to use alternative distributions like Debian, Fedora, Alpine and friends simply by adding them as another image under config. However, please note that effort currently focuses exclusively on Arch Linux.
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 container images, 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 pulling the newest container image built either locally or provided by the GitHub container registry. If you hit a problem, you can easily roll back to the previously working OSTree 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.
A live environment such as the Arch Linux ISO is recommended for bootstrapping YoRHa to a target disk. The following instructions assume such an environment.
- Install the necessary dependencies and enable podman service needed to bootstrap your system:
# pacman --noconfirm -Sy git ostree podman fuse-overlayfs && systemctl start podman- Download and run the installer from the GitHub releases page:
# curl -OL https://github.com/lcook/yorha/releases/latest/download/yorha-inst && chmod +x yorha-inst
# ./yorha-instAfter downloading and running the installer binary, you will be guided through an interactive command-line installer that simplifies the process of setting up a live system. The installation occurs in three stages: first, disk partitioning and formatting; second, OSTree repository setup and imaging; and finally, OSTree deployment and bootloader installation.
In stage two, you will be asked to enter a container image for deployment. You can find available images here, and you also have the option to provide your own. After all stages have completed you can reboot your system. You should be greeted with ly as the login manager.
Note
The default root account password is set to ostree - please change this after logging in!
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. With that in mind, you can either use the provided images or build your own (see below) to create new OSTree deployments.
Pre-built GitHub Container Registry images (recommended for consumers)
Updating to the latest image can be done by running:
# yorha updateIt should automatically detect the booted OSTree environment and the corresponding
container image removing the need to use the -i flag. However, if you wish to
switch the image, you can do so by passing the -i flag followed by the container
image URL (for example, ghcr.io/lcook/yorha/custom-image). This will initiate a
new deployment.
This method of updating the system is the more hands-off approach, while the method below allows for the flexibility to use custom images as you wish.
Locally built images (recommended for development and custom images)
You can also build and customize your own container images according to your preferences. This approach is useful when you need to make local modifications to the deployed image that are not available in the provided image in the GitHub Container Registry.
To get started clone the repository, add your custom config into the config directory, and build the toolkit:
# git clone --recursive https://github.com/lcook/yorha && cd yorha
# make build # Builds binaries with all features enabled and not just a thin client
# ./yorha build -c config/image-custom.yamlThis will initiate a build by calling the Podman API after preparing the Containerfile
template as specified in the YAML file. Assuming the container name is archlinux-custom
and no issue occured during the build process, you can deploy the image:
# ./yorha update -i localhost/archlinux-customAny subequent invokations to yorha update do not need -i as the image name will
automatically be detected.
Note
Stale container images are automatically cleared up on update to help save on disk space.
List available OSTree deployments and their corresponding container image:
# yorha list
IMAGE CHECKSUM VERSION CREATED STATUS
0 ghcr.io/lcook/yorha/archlinux-nvidia 4982b32d08f 20260606.1541 6 days ago booted
1 ghcr.io/lcook/yorha/archlinux-nvidia 37817ccfade 20260605.2059 6 days ago rollback
2 ghcr.io/lcook/yorha/archlinux-nvidia d987ec7898f 20260530.2338 12 days ago
3 ghcr.io/lcook/yorha/archlinux-nvidia c4a44acf5db 20260528.0629 15 days agoNote
To remove a previous OSTree deployment, first identify its deployment index (in the output above,
between 0 and 3, '2' will be used in this example). Then run ostree admin undeploy 2
to delete that deployment and free up some space. You can repeat this process for as
many valid deployments as you want to remove.
Switch the active OSTree deployment:
# yorha switch
IMAGE CHECKSUM VERSION CREATED STATUS
0 ghcr.io/lcook/yorha/archlinux-nvidia 4982b32d08f 20260606.1541 6 days ago booted
1 ghcr.io/lcook/yorha/archlinux-nvidia 37817ccfade 20260605.2059 6 days ago rollback
2 ghcr.io/lcook/yorha/archlinux-nvidia d987ec7898f 20260530.2338 12 days ago
3 ghcr.io/lcook/yorha/archlinux-nvidia c4a44acf5db 20260528.0629 15 days ago
* Select deployment index [0-3]:| Image | Description |
|---|---|
| ghcr.io/lcook/yorha/archlinux-base | Base YoRHa container image built from Arch Linux |
| ghcr.io/lcook/yorha/archlinux-mainline | Mainline YoRHa container image providing the core desktop and environment |
| ghcr.io/lcook/yorha/archlinux-nvidia | YoRHa container image with NVIDIA GPU support |
| ghcr.io/lcook/yorha/archlinux-intel | YoRHa container image with Intel GPU support |
Updates, removals and additions to the latest container images can be found here.
Special thanks to GrabbenD (ostree-utility) for inspiration.