How to make a new Fedora Atomic Desktop variant?
So you want to make a new Fedora Atomic Desktop variant in Fedora to join Silverblue, Kinoite, Sway Atomic (was Sericea) and Budgie Atomic (was 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.
Last updated on: November 18th, 2024
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-atomic 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 examples.
Until we have completed the migration to Bootable Containers, you will have to create two top-level manifests, one for the bootable container image and one for the ostree classic one.
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 Universal Blue 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:
New Fedora Atomic Desktop variants should be named Fedora <Desktop> Atomic. For example, in the case of XFCE it would be: Fedora XFCE Atomic.
Once your change as been accepted, you can move to the next step.
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 configuration to enable them in Rawhide and then in Bodhi for future updates once released. It’s mostly copy pasting and tweaking the existing configuration for other variants. See:
- Look for
ostree,ostree_installerandostree_containerin thefedora-pungiconfig repo for Rawhide and branched releases:- 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.
- Do the same for the config in Bodhi:
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
We would like to unify the documentation for the Fedora Atomic Desktops in a single place. Contributions to make that happen are welcomed.
Website
Finally, you can add a page for your variant to the new Fedora website. Use the other variants’ pages as example.
Conclusion
Happy composing and rebasing!
Comments
You can also contact me directly if you have feedback.