How to make a new rpm-ostree desktop variant in Fedora?

So you want to make a new rpm-ostree desktop variant in Fedora to join Silverblue, Kinoite, Sericea and soon Onyx? Here are the steps that you should follow.

Note: This checklist may not be fully exhaustive and I’ll likely update it as needed. Feel free to send me suggestions.

Making your first image from the base image

First, you should figure out what packages should be installed in your image. To do that, you can start from the base container image that already includes the packages common to all variants. You can then add packages from the comps group corresponding to your desktop in Fedora.

At this point, you should consider which apps are going to be shipped by default, included in the image, and which ones are going to be installed by default as Flatpaks.

Take a look at the Universal Blue project for examples on how to do container based variants.

Creating rpm-ostree manifests

Once you’ve got something working, reproduce that in the workstation-ostree-config repo using the comps group, the exclude list and the filter and sync script. Look at other variants for example.

Always start from Rawhide, or use the latest stable Fedora release to test but submit the PR to Rawhide. I’ll likely review it then.

Experimental CI in GitLab

Once the PR is merged, we’ll enable test builds in the unofficial CI hosted on GitLab.com in the fedora/ostree namespace.

This will get you container images in the fedora-ostree-desktops quay.io organization. With those, you can start building uBlue images and ISOs and test things more (including the installation).

When things are in good shape, you can move to the next step!

Making it official

Then, let’s make it official!

Change Request

Now you need to submit a change request to Fedora to request this new variant to be added to the official Fedora composes. Follow the steps to make a Fedora Change Request.

You can use the last three change requests as example:

• Fedora Kinoite
• Fedora Sericea
• Fedora Onyx

You will have to pick a name for your variant and request legal review for it. You can not reuse existing names or call your variant “Silverblue FooBar”.

Once your change as been accepted, you can move to the next steps.

Addition to fedora-release

You then have to create a new sub package as part of fedora-release to give your new edition a distinctive identity in /etc/os-release.

Composes

Once the new sub package is merged and built, you can add it to the rpm-ostree manifests.

To get official builds of your variant, you will have to add the confirmation to enable them in Rawhide. It’s mostly copy pasting and tweaking the existing configuration for other variants. See:

• Look for “ostree” in the fedora-pungi config repo:
  • https://pagure.io/pungi-fedora/blob/main/f/fedora.conf
  • This is also where you configure which Flatpaks are included in the installer ISO and thus installed by default.
• Add your variants to the following files:
  • https://pagure.io/fedora-infra/ansible/blob/main/f/roles/bodhi2/backend/templates/pungi.rpm.conf.j2
  • https://pagure.io/fedora-infra/ansible/blob/main/f/roles/bodhi2/backend/files/new-updates-sync

Flatpak Apps

You’ll want to make sure that the apps that you want to install by default as Flatpaks are available as Fedora Flatpaks. Reach out to the Flatpak SIG if you need help. You can not use Flatpaks from Flathub. See the Fedora Flatpak and SIG FAQ.

Documentation

Then you’ll have to make a docs repo. You can start from the Silverblue one and then make a PR to the docs website repo (start with stg then prod once released) to have it built and hosted on the Fedora docs site.

Website

Finally, you can add a page for your variant to the new Fedora website. Use the Silverblue, Kinoite and Sericea pages as example.

Conclusion

Happy composing and rebasing!