This is a constantly updating template repository for creating a native container image designed to be customized however you want. GitHub will build your image for you, and then host it for you on ghcr.io. You then just tell your computer to boot off of that image. GitHub keeps 90 days worth image backups for you, thanks Microsoft!

For more info, check out the uBlue homepage and the main uBlue repo

Getting started

See the Make Your Own-page in the documentation for quick setup instructions for setting up your own repository based on this template.

Don't worry, it only requires some basic knowledge about using the terminal and git.

After setup, it is recommended you update this README to describe your custom image.

Note

Everywhere in this repository, make sure to replace ublue-os/startingpoint with the details of your own repository. Unless you used create-ublue-image, in which case the previous repo identifier should already be your repo's details.

Warning

To start, you must create a branch called live which is exclusively for your customizations. That is the only branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your live branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits".

Customization

For information about customization, see the README in the config directory

Installation

Warning

This is an experimental feature and should not be used in production, try it in a VM for a while!

To rebase an existing Silverblue/Kinoite installation to the latest build:

First rebase to the unsigned image, to get the proper signing keys and policies installed:
```
sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/startingpoint:latest
```
Reboot to complete the rebase:
```
systemctl reboot
```

Then rebase to the signed image, like so:

sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/startingpoint:latest

Reboot again to complete the installation
```
systemctl reboot
```

This repository builds date tags as well, so if you want to rebase to a particular day's build:

sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/startingpoint:20230403

This repository by default also supports signing.

The latest tag will automatically point to the latest build. That build will still always use the Fedora version specified in recipe.yml, so you won't get accidentally updated to the next major version.

ISO

This template includes a simple Github Action to build and release an ISO of your image.

To run the action, simply edit the boot_menu.yml by changing all the references to ublue-os/startingpoint to your repository. This should trigger the action automatically.

The Action uses isogenerator and works in a similar manner to the official Universal Blue ISO. If you have any issues, you should first check the documentation page on installation. The ISO is a netinstaller and should always pull the latest version of your image.

Note that this release-iso action is not a replacement for a full-blown release automation like release-please.

Just

The just task runner is included in ublue-os/main-derived images, and we have provided several template commands which help you perform further customization after first boot.

You can merge our template justfiles into your own local configuration. When just supports include directives, you will instead be able to simply include these paths into your own justfile, without having to copy anything manually.

Run the following commands when you're logged into the operating system, to merge uBlue's provided configurations into your own user config. (The "touch" command is only necessary on certain shells which won't let you merge into non-existent files.)

touch ~/.justfile
cat /usr/share/ublue-os/just/main.just >> ~/.justfile
cat /usr/share/ublue-os/just/custom.just >> ~/.justfile

After doing that, you'll be able to run the following commands:

just - Show all tasks, more will be added in the future
just bios - Reboot into the system bios (Useful for dualbooting)
just changelogs - Show the changelogs of the pending update
Set up distroboxes for the following images:
- just distrobox-boxkit
- just distrobox-debian
- just distrobox-opensuse
- just distrobox-ubuntu
just setup-flatpaks - Install all of the flatpaks declared in recipe.yml
just setup-gaming - Install Steam, Heroic Game Launcher, OBS Studio, Discord, Boatswain, Bottles, and ProtonUp-Qt. MangoHud is installed and enabled by default, hit right Shift-F12 to toggle
just nix-me-up - Install Nix with dnkmmr69420's Nix Silverblue install script
just update - Update rpm-ostree, flatpaks, and distroboxes in one command

Check the just website for tips on modifying and adding your own recipes.