We will use Tuxguitar to render the audio of a Guitar Pro score [5]. Guitar Pro scores are files with a complete band score transcribed (guitars, bass, drums, synths and more).

Introduction

Tuxguitar is a quite powerful application written in a mixture of Java / C. It is able to render a score in real time either via Fluidsynth [6] or via pure MIDI. The development of Tuxguitar started in 2008 on Sourceforce and after a halt in 2022, the project restarted on Github and is still actively developed.

The goal of this article is to try to render a score via Tuxguitar, and various other applications connected to Tuxguitar, via Jack or Pipewire-Jack. The score used throughout this article will be The Pursuit Of Vikings by the band Amon Amarth [7]. It has 2 guitars, a bass and a drum track.

First step, configuration

For this audio rendering, we will use some tools from the Audinux Fedora COPR repository [11] [12]. The COPR repository can be enabled via :

$ dnf copr enable ycollet/audinux

You may activate the official real time kernel, via the GRUB menu by adding the following options to the kernel you want to boot (hit ‘e’ while on the kernel you want to boot on GRUB) :

preempt=full threadirqs nopti

Then hit F10 to start the kernel.

Using a real time kernel is not always a requirement for audio. It really depends on how you use audio. For standard audio rendering, a standard kernel is maybe enough. However, if you want real time processing of the audio of a guitar connected to a USB audio interface via Guitarix, for example, then a real time kernel will be required. This is especially true if you want to have a really low latency.

Last step: ensure that the /etc/security/limits.d/25-pw-rlimits.conf has the following settings:

@pipewire   – rtprio  80
@pipewire   – nice    -15
@pipewire   – memlock unlimited

Add your username to the pipewire group and disconnect / reconnect to your session.

This last setting is required to allow audio to use a high priority to avoid Xruns (cracks in the sound because of a buffer not filled fast enough).

On Pipewire, you can now adjust the global audio latency via the following command:

$ pw-metadata -n settings 0 clock.force-quantum 256

The global sample rate can be adjusted via the following command:

$ pw-metadata -n settings 0 clock.force-rate 44100

Using Tuxguitar

The first step is to activate the Fluidsynth plugin of Tuxguitar.

Fluidsynth [6] is a software MIDI synthesizer based on the SoundFont 2 specifications [28] and can read sound fonts (set of samples used to mimic some instruments) either in format SF2 (samples based on WAV files) or SF3 (samples based on OGG files – [29]). Fluidsynth comes as a library and executable tool, but is often integrated into applications like Tuxguitar or Qsynth (which is a GUI to control Fluidsynth).

To enable the Fluidsynth plugin in Tuxguitar : open Tools→ Plugins and check Fluidsynth output plugin. After that, select Fluidsynth output plugin on Configure. You will then have access to three tabs (Soundfonts, Audio, and Synthesizer) which allow you to select a better sound font and control the audio rendering of this sound font.

The Musical Artifacts website [1] hosts a lot of interesting artifacts for audio. You can find the Xioad Bank Sound font which has a lot of interesting sounds for Rock and Metal.

Once the sound font is set up in Tuxguitar, you need to select this sound font as audio driver via Tools → Settings → Sound.

First select a MIDI Sequencer (I use the Jack one) and the MIDI Port (TG Fluidsynth – The Xioad Bank).

After those selections, you can open the score [4], [7].

Connecting Tuxguitar to Audio Output

Under Jack or Pipewire-Jack, we will need to connect Tuxguitar to the audio output of the computer. This can be done via Ray-Session [10] or qpwgraph [30].

Ray Session is an audio session manager. It can load a user defined set of applications and remember the audio connections made between application and rewire these connections automatically. With such a tool, you can restart and rewire a complex session in a second.

qpwgraph is a Pipewire graph manager and can be used to perform connections between various applications.

In Ray Session you will need to draw wires between the fluidsynth block to the audio output (a block with blue connectors). When that is complete, select Play in Tuxguitar to render the score.

Fine tuning the drum sound

Some sound fonts provide various drum kits and, via Tuxguitar, it is relatively easy to select a new kit.

First, inspect the sound font using Polyphone [8], [9]. Polyphone is a sound font editor. You can easily create new sound fonts using this tool by assembling samples into instruments and presets.

In the Presets subsection, you can see all the available instruments in the sound font. Each instrument is identified by an index. For example, in 006:125 the first number is the bank (006) and the second number is the instrument (125). Thus, 006:125 → bank 6 and instrument 125. In the general MIDI specification [21], bank 128 is dedicated to drums. As you can see, the Xioad sound font gives you access to 15 drum kits. We will now switch the default drum kit used by Tuxguitar from 128:001 – Custom Standard to 128:016 – Custom Power.

Switch the drum kit by selecting View → Show Instruments and then, in the DrumKit 1 area, select the drop down menu and select ‘Program #16‘ to select the 128:016 – Custom Power drum kit. There is a correspondence between the ‘Program #’ number and the bank ‘128:’ number.

You can now hit Play in Tuxguitar and hear the difference in sound between the default drum kit and the one just selected.

Using Tuxguitar and Hydrogen / QSynth

We will now set up Tuxguitar as a MIDI sequencer using :

• Qsynth for the audio rendering anything but the drum [15], [16]
• Hydrogen for the drum audio rendering [13], [14]

To turn Tuxguitar into a MIDI sequencer perform the following:

• via the Tools → Plugins, ensure that Jack Audio Connection Kit output plugin is checked ;
• via the Tools → Settings → Sound, select Jack Midi Port in the MIDI Port field.

Tuxguitar will now no longer generate sound but will generate MIDI events.

Start Qsynth and load the Xioad sound font into Qsynth via the Setup button.

For Qsynth, we need to take the following steps:

• in the MIDI tab, select Jack as MIDI Driver and be sure to check ‘Enable MIDI Input’. Rename the ‘Engine Name’ with a informative name of your choice;
• in the Audio tab, select Jack as Audio Driver and rename the ‘JACK Client Name ID’;
• in the Soundfonts tab, load the sound font you want (Xioad sound fount in our example) and remove the default one.

Now, open View→ Show Instruments and in the Drum Kit area, and select the wrench tool. A dialog shows up from which you select Exclusive Jack Port. This will add a specific output for the drum and a new output will show up and will gather all the other instruments (the 2 guitars and the bass).

Via Ray Session, you will have to create some audio connections (blue ports / blue wires) and some MIDI connections (pink ports / pink wires).

We have now connected all the guitars and the bass to Qsynth and need to focus on the drum.

Now start Hydrogen

Hydrogen [13], [14] is a standalone application which is a drum sequencer with a lot of interesting drum kits. If you want to use Hydrogen as an audio plugin, some plugins exists and will be presented later in this article.

Under Ray Session, Hydrogen has 2 boxes : one for audio output and the other one for MIDI input / output.

You can now install a Hydrogen drum kit from the annex and select it via the View → Instrument rack and then click on Sound Library in the instrument view. You will see all the drum kits installed.

Right click on a drum kit and select Load.

After that you can render the score via Tuxguitar → Play.

If you want to use Hydrogen as a LV2 plugin, you can use the Drmr plugin [18] or select other plugins available in Audinux.

Using Tuxguitar and Hydrogen / DrumGizmo

DrumGizmo is a professional drum sequencer [16]. It comes as an executable or as a LV2 plugin. We will use the executable version. Once installed, you will need to install a drum kit from DrumGizmo [17].

These drum kits are professionally recorded. From DrumGizmo[17], the description of the recording setup of the DRS drum kit : all microphones are connected to its own channel when loading the kit in DrumGizmo. A total of 13 channels. Remember to pan the relevant channels to give you a better stereo effect.

• Channel 1: Ambiance left
• Channel 2: Ambiance right
• Channel 3: Kick drum back
• Channel 4: Kick drum front
• Channel 5: Hihat
• Channel 6: Overhead left
• Channel 7: Overhead right
• Channel 8: Ride cymbal
• Channel 9: Snare drum bottom
• Channel 10: Snare drum top
• Channel 11: Tom1
• Channel 12: Tom2 (Floor tom)
• Channel 13: Tom3 (Floor tom)

Using the DRS drum kit

For the demonstration, we will use the DRS drum kit.

The command line used to start the DrumGizmo sequencer (in the DRS kit directory) :

$ drumgizmo -i jackmidi -I midimap=Midimap_minimal.xml -o jackaudio DRSKit_minimal.xml

There are several MIDI map files available for DrumGizmo :

Midimap_basic.xml 

Midimap_full.xml 

Midimap_minimal.xml 

Midimap_no_whiskers.xml 

Midimap_whiskers_only.xml

Each file is activating some options in drum rendering. We will use the simple MIDI map available.

The minimal MIDI map has the following MIDI events :

Midi note: 44 -> Hihat_foot sample
Midi note: 37 -> Snare_rim sample
MIDI note: 49 -> Crash_left_shank sample
MIDI note: 57 -> Crash_right_shank sample
MIDI note: 42 -> Hihat_closed_shank sample
MIDI note: 46 -> Hihat_semi_open sample
MIDI note: 35 -> Kdrum_without_contact sample
MIDI note: 36 -> Kdrum_with_contact sample
MIDI note: 51 -> Ride_tip sample
MIDI note: 53 -> Ride_shank_bell sample
MIDI note: 38 -> Snare sample
MIDI note: 40 -> Snare_rest sample
MIDI note: 47 -> Tom1 sample
MIDI note: 43 -> Tom2 sample
MIDI note: 41 -> Tom3 sample

The first number corresponds to the MIDI event: 44 for the Hihat_foot sample.

The full MIDI map has the following MIDI events :

MIDI note 54 -> Crash_left_tip sample
MIDI note 60 -> Crash_left_whisker sample
MIDI note 55 -> Crash_right_tip sample
MIDI note 62 -> Crash_right_whisker sample
MIDI note 56 -> Hihat_closed sample
MIDI note 64 -> Hihat_closed_whisker sample
MIDI note 44 -> Hihat_foot sample
MIDI note 58 -> Hihat_open sample
MIDI note 61 -> Hihat_open_tip sample
MIDI note 65 -> Hihat_open_whisker sample
MIDI note 63 -> Ride_rest sample
MIDI note 66 -> Ride_shank sample
MIDI note 68 -> Ride_tip_bell sample
MIDI note 70 -> Ride_tip_bell_chain sample
MIDI note 73 -> Ride_tip_chain sample
MIDI note 67 -> Ride_whisker sample
MIDI note 69 -> Snare_circle_whisker sample
MIDI note 37 -> Snare_rim sample
MIDI note 71 -> Snare_whisker sample
MIDI note 72 -> Tom1_whisker sample
MIDI note 74 -> Tom2_whisker sample
MIDI note 76 -> Tom3_whisker sample
MIDI note 49 -> Crash_left_shank sample
MIDI note 57 -> Crash_right_shank sample
MIDI note 42 -> Hihat_closed_shank sample
MIDI note 46 -> Hihat_semi_open sample
MIDI note 35 -> Kdrum_without_contact sample
MIDI note 36 -> Kdrum_with_contact sample
MIDI note 51 -> Ride_tip sample
MIDI note 53 -> Ride_shank_bell sample
MIDI note 38 -> Snare sample
MIDI note 40 -> Snare_rest sample
MIDI note 47 -> Tom1 sample
MIDI note 43 -> Tom2 sample
MIDI note 41 -> Tom3 sample

Various options are available in DrumGizmo to enhance the audio rendering like:

• -t, –timing-humanizer:  Enable moving of notes in time. NOTE: Adds latency to the output so do not use this with a real-time drumkit;
• -T, –timing-humanizerparms <x>: Timing humanizer options;
• -x, –velocity-humanizer:  Enables adapting input velocities to make it sound more realistic;
• -X, –velocity-humanizerparms <x>: Velocity humanizer options.

And we also select Jack for audio output and Jack for MIDI input.

Connecting all the Inputs

Now, we have to connect all the audio and MIDI inputs. We have the following connections on Ray Session :

As you can see, the drum from DrumGizmo comes with many outputs.

There is now a huge difference in audio rendering when we consider the drum. We had a good result with the selection of a specific sound font, this result was improved a little bit via the use of Hydrogen but now, we have a nearly perfect drum rendering.

Some other solutions for the drum

We will now use some plugins as drum sequencers.

Audinux Plugins

The following plugins are available in Audinux:

• drumkv1 : an old-school drum-kit sampler
• drumlabooh : LV2/VSTi drum machine that can use Hydrogen, SFZ, and other drumkit formats
• drumrox : a hydrogen compatible drum LV2 plugin
• lv2-avldrums-x42-plugin : simple Drum Sample Player LV2 Plugin
• ChowKick : kick synthesizer based on old-school drum machine circuits
• boomer : a drum synth
• drmr : a drum LV2 plugin
• geonkick : drum Software Synthesizer
• kickmess : a kick drum synthesizer plugin
• lv2-fabla : an LV2 drum sequencer
• onetrick-cryptid : an FM drum synth with the cold clanging heart of a DX7 in the fearsome frame of an 808
• onetrick-simian2 : an open source drum synth inspired by hexagonal classics like the Simmons SDS-V
• onetrick-urchin : a hybrid drum synth that models the gritty lo-fi sound of beats from vintage records without sampling.
• sickbeatbetty : an open source MIDI drum machine / generator VST and standalone application
• stegosaurus : drum synthesizer

Using Drumrox

We will perform our test using the Drumrox LV2 plugin. To be able to use this sequencer, we will need to use the Carla rack.

Don’t forget to install either a hydrogen drum kit or a drumrox kit via

before using this plugin.

We can either install the Carla or Carla-mao RPM package. The second one provides some tools to allow loading a Windows VST plugin via Wine. We need also to install the Drumrox package.

Once

ack executable is started, we load the Drumrox plugin via the Add Plugin button (and you may have to click on the Refresh button to update the list of installed plugins).

Investigating Drumrox

Now display the Drumrox GUI via a click on the nut button near the ON/OFF button and select an installed drum kit in the Kit field. This plugin is able to load a Hydrogen drum kit, but it can also load a Drumrox drum kit.

Drumrox plugin comes into 2 flavors :

• Drumrox : a plugin with 2 output channels
• Drumrox-Multi : a plugin with 36 output channels

We have the following audio / MIDI connections under Ray Session :

Using a sound font by instrument

First we download some SF2 files from the Musical Artifacts website :

1. Overdriven Guitar [19] as a SF2 guitar
2. Rock Bass [20] as a SF2 bass

We will need to launch these applications :

• 4 x
  carla-rack
  . One will host the Drumrox plugin for drum and the 3 others will host one MIDI Event filter to filter out the bank change event sent by Tuxguitar and which resets the channels settings we made in Qsynth ;
• Qsynth with one Fluidsynth engine by instrument ;
• Tuxguitar.

We will need these plugins :

• Drumrox : the drum plugin compatible with Hydrogen drum kits ;
• lv2-x42-plugins [26], [27] : a set of various plugins dedicated to MIDI management and in this set, we will use MIDI Event Filter.

An Issue with Tuxguitar … and a workaround

The problem with Tuxguitar: each time we hit the play button, a MIDI event “bank change” is sent and this event erases all the set up made in Qsynth channelsassignment. So, to avoid this bank change event, we need to use the MIDI Event Filter plugin and filter out this event. The content of the MIDI Event Filter in Carla rack is :

For Qsynth, we need to take the following steps:

• in the MIDI folder :
  • rename the Engine Name (Guitar1 here) ;
  • select ‘jack’ as MIDI Driver
  • uncheck Auto Connect MIDI Inputs
• in the Audio folder :
  • select ‘jack’ as Audio Driver
  • rename the Jack Client Name ID as ‘Guitar1’
  • uncheck the Auto Connect Jack Outputs
• in the Soundfonts folder :
  • load the sound font we want
  • remove the default sound font

We need to repeat these steps for each instrument we want to add.

Last step : setting the channels assignment for each instrument.

Select instruments by channel

Depending on the sound font you have loaded, you will need to select some instrument, by channel.

When we selected the ‘Exclusive Jack Port’ in Tuxguitar, the MIDI program numbering switched from ‘General MIDI’ (from 0 to 127) to 2 channels only (one for the instrument and one for the instrument effects). In the Qsynth channel assignment GUI, we will need to make some correspondence between the 1/2 channels of Tuxguitar to the bank of the requested instrument (29 for the guitar sound font we used in the example).

Now, in Tuxguitar, to you need to select the Jack MIDI Port in Tools → Settings → Sound → Port MIDI. Open the Instrument view (View → Show Instruments) and click each wrench icon of the guitars and bass to check Exclusive Jack Port. You will have to connect every box in Ray Session like the above figure.

The audio rendering will depend on the SF2 / SF3 sound fonts you loaded but with such a settings, everything is possible.

Conclusion

One of the main strength of music under Linux is the ability to connect several application between them and having the sound rendered in real time with a low latency.

With a tool like Ray Session, the management of complex application connection is really easy. This tool can start a set of application and reconnect all these really quickly.

The ergonomics and efficiency of audio applications has greatly improved and will continue to improve in the coming years. We can also notice that several pro audio tools are now available on Linux like Ardour [22] / Mixbus [23], Bitwig [24], Renoise [25] and many others. This allows us to use audio under Linux as people use audio on Apple and Windows.

So, now, it’s time to make some music on Linux and be careful, Linux can be really addictive.

Links

[1] – https://musical-artifacts.com/artifacts/362

[2] – https://www.tuxguitar.app/

[3] – https://github.com/helge17/tuxguitar

[4] – https://www.ultimate-guitar.com/explore?type[]=Pro

[5] – https://www.guitar-pro.com

[6] – https://github.com/FluidSynth/fluidsynth

[7] – https://tabs.ultimate-guitar.com/tab/amon-amarth/the-pursuit-of-vikings-guitar-pro-213840

[8] – https://polyphone-soundfonts.com/

[9] – https://github.com/davy7125/polyphone

[10] – https://github.com/Houston4444/RaySession

[11] – https://audinux.github.io/

[12] – https://copr.fedorainfracloud.org/coprs/ycollet/audinux/

[13] – http://hydrogen-music.org/

[14] – https://github.com/hydrogen-music/hydrogen

[15] – https://qsynth.sourceforge.io/

[16] – https://github.com/rncbc/qsynth

[16] – https://www.drumgizmo.org/wiki/doku.php?id=start

[17] – https://www.drumgizmo.org/wiki/doku.php?id=kits

[18] – https://github.com/falkTX/drmr

[19] – https://musical-artifacts.com/artifacts/3038

[20] – https://musical-artifacts.com/artifacts/2077

[21] – https://en.wikipedia.org/wiki/General_MIDI

[22] – https://ardour.org/

[23] – https://store.harrisonaudio.com/all-products/mixbus-11-daw

[24] – https://www.bitwig.com/

[25] – https://www.renoise.com/

[26] – https://github.com/x42/x42-plugins

[27] – https://x42-plugins.com/x42/

[28] – https://www.synthfont.com/sfspec24.pdf

[29] – https://github.com/davy7125/soundfont-standard-v3

[30] – https://github.com/rncbc/qpwgraph

The Fedora Project is built on the dedication, mentorship, and relentless efforts of contributors who continuously go above and beyond. From reviewing pull requests to onboarding new community members, from writing documentation to organizing events — it’s these quiet champions who make Fedora thrive. As a part of the Fedora Mentor Summit , we would be declaring the results. This wiki underscores the sentiment and the thought that went into this recognition programme.

As we gear up to recognize outstanding mentors and contributors in our community, we invite you to nominate those individuals who’ve made a lasting impact — the ones who’ve guided, inspired, or stood out through their unwavering contributions. Whether it’s a long-time mentor who helped you take your first steps, or a contributor whose work has left a mark across Fedora’s landscape — now is the time to celebrate them! Read more about the nomination process and submit your nomination at the link below:

Submit your nominations here: https://forms.gle/xB8ng7GH9niT2Sza8

Deadline: 16 May 2025

Let’s spotlight the amazing humans who power Fedora. Your nomination could be the recognition someone has long deserved — and a moment of pride for our whole community.

Each Fedora release is only possible thanks to the dedication of many contributors. One of the most important ways you can get involved is by participating in Test Days! This article describes the steps in proposing and scheduling test days.

As Fedora 43 development moves ahead, it’s time to start planning and proposing Test Days. A Test Day is a focused event where contributors and users come together to test a specific feature, component, or area of the Fedora distribution. These events usually happen around a test-day Matrix channel for live interaction. The results are coordinated through a Fedora Wiki page and Test Days App. Test Days play a critical role in ensuring Fedora Linux continues to deliver a stable and high-quality experience.

Test Days can focus on many things — not just code! We regularly host Test Days for localization (l10n), internationalization (i18n), desktop environments like GNOME, and major system components like the Linux kernel. You can learn more about Fedora QA Test Days here!

How to propose a Test Day

Anyone can propose and host a Test Day! Whether you want to lead it yourself, collaborate with the Fedora QA team, or just need a little help getting started, you’re welcome to participate.

To propose a Test Day, simply file a ticket in the fedora-qa pagure and tag it with test days. You can see an example here.

If you’re new to organizing, we have a full guide to help you set up and run a successful event. The information at SOP: Test Day Management will go a long way to help you

The current schedule of Test Days and available slots are available here. When selecting a date, please keep in mind the Fedora 43 development milestones, such as the Beta Freeze and Final Freeze.

Scheduling notes

We traditionally schedule Test Days on Thursdays. However, if you are organizing a series of related Test Days (for example, the Kernel or GNOME Test Weeks), we often schedule them over Tuesday, Wednesday, and Thursday. If Thursday slots are full, or special timing is needed for your topic, don’t worry — we can open up additional days.

Just note your preferred dates when filing your ticket, and we’ll work with you!

Help with ongoing Test Days

If you don’t want to host your own Test Day but would still like to help, you can participate in ongoing events, including:

• GNOME Test Day
• i18n Test Day
• Kernel Test Week(s)
• Upgrade Test Day
• IoT Test Week
• Cloud Test Day
• Fedora CoreOS Test Week

These recurring Test Days help ensure that major areas of Fedora are working well across the release cycle.

Questions?

If you have any questions about Test Days — whether proposing, organizing, or participating — please don’t hesitate to contact the Fedora QA team via Matrix!
Or via email test@lists.fedoraproject.org, or IRC #fedora-qa on Libera Chat: Join here

We look forward to seeing you at Fedora 43 Test Days!

Bootc and associated tools provide the basis for building a personalised desktop. This article will describe the process to build your own custom installation.

Disclaimer

Building and using a custom installation is “at your own risk”. Your installation may be harder to find support for when compared with a mainstream solution.

Motivation

There has been an increasing interest in atomic distros, which offer significant benefits in terms of stability and security.

These distros apply updates as a single transaction, known as atomic upgrades, which means if an update doesn’t work as expected, the system can instantly roll back to its last stable state, saving users from potential issues. The immutable nature of the filesystem components reduces the risk of system corruption and unauthorised modifications as the core system files are read-only, making them impossible to modify.

If you are planning to spin off various instances from the same image (e.g. setting up computers for members of your family or work), atomic distros provide a reliable desktop experience where every instance of the desktop is consistent with each other, reducing discrepancies in software versions and behaviour.

Mainstream sources like Fedora and Universal Blue offer various atomic desktops with curated configurations and package selections for the average user. But what if you’re ready to take control of your desktop and customise it entirely, from packages and configurations to firewall, DNS, and update schedules?

Thanks to bootc and the associated tools, building a personalised desktop experience is no longer difficult.

What is bootc?

Using existing container building techniques, bootc allows you to build your own OS. Container images adhere to the OCI specification and utilise container tools for building and transporting your containers. Once installed on a node, the container functions as a regular OS.

The filesystem structure follows ostree specifications:

• The /usr directory is read-only, with all changes managed by the container image.
• The /etc directory is editable, but any changes applied in the container image will be transferred to the node unless the file was modified locally.
• Changes to /var (including /var/home) are made during the first boot. Afterwards, /var remains untouched.

You can find the full documentation for bootc here: https://bootc-dev.github.io/bootc/

Creating your own bootc desktop

The approach described in this article uses quay.io/fedora/fedora-bootc as a base image to create a customizable container for building your personalised Fedora KDE atomic desktop.

Although tailored to KDE Plasma, most of the concepts and methodologies described here also apply to other desktop environments.

The kde-bootc repository

I published kde-bootc as a repository available in GitHub, and I will use it as a reference. It will help this explanation providing additional details, and a source to clone and experiment. You may wish to clone kde-bootc to following along.

Folder structure:

• scripts/
• system/
• systemd/
• Containerfile

scripts: Scripts to be ran from the Containerfile during building
system: Files to be copied to /usr and /etc
systemd: Systemd unit files to be copied to /usr/lib/systemd

Each file follows a specific naming convention. For instance a file /usr/lib/credstore/home.create.admin is named as usr__lib__credstore__home.create.admin

Explaining the Containerfile

The following will describe and show, step by step, the contents of the example Containerfile created.

Image base

The fedora-bootc project is part of the Cloud Native Computing Foundation (CNCF) Sandbox projects and  generates reference “base images” of bootable containers designed for use with the bootc project.

In this example, I’m using quay.io/fedora/fedora-bootc as the base image. The containerfile starts off with:

FROM quay.io/fedora/fedora-bootc

Setup filesystem

If you plan to install software on day 2, i.e. after the kde-bootc installation is complete, you may need to link /opt to /var/opt. Otherwise, /opt will remain an immutable directory that you can only populate from the container build.

RUN rmdir /opt
RUN ln -s -T /var/opt /opt

In some cases, for successful package installation, the /var/roothome directory must exist. If this folder is missing, the container build may fail. It is advisable to create this directory before installing the packages.

RUN mkdir /var/roothome

Prepare packages

To simplify the installation, and to have a record of installed and removed packages for future reference, I found it useful to keep them as a resource under /usr/share.

• All additional packages to be installed on top of fedora-bootc and the KDE environment are documented in packages-added.

COPY --chmod=0644 ./system/usr__local__share__kde-bootc__packages-added /usr/local/share/kde-bootc/packages-added

• Packages to be removed from fedora-bootc and the KDE environment are documented in packages-removed.

COPY --chmod=0644 ./system/usr__local__share__kde-bootc__packages-removed /usr/local/share/kde-bootc/packages-removed

• For convenience, the packages included in the base fedora-bootc are documented in packages-fedora-bootc.

RUN jq -r .packages[] /usr/share/rpm-ostree/treefile.json > /usr/local/share/kde-bootc/packages-fedora-bootc

Install repositories

This section handles adding extra repositories needed before installing packages.

In this example, I’m adding Tailscale, but the same principle applies to any other source you may add to your repositories.

Adding repositories uses the config-manager verb, available as a DNF5 plugin. This plugin is not pre-installed by default in fedora-bootc, so it will need to be installed beforehand.

RUN dnf -y install dnf5-plugins
RUN dnf config-manager addrepo --from-repofile=https://pkgs.tailscale.com/stable/fedora/tailscale.repo

Install packages

For clarity and task separation, I divided the installation into two steps:

Installation of environment and groups.

RUN dnf -y install @kde-desktop-environment

And the installation of all other individual packages. The script will select all lines not starting with # passing them as arguments to dnf -y install. The --allowerasing option is necessary for cases like installing vim-default-editor, which would conflict with nano-default-editor, removing the latter first.

RUN grep -vE '^#' /usr/local/share/kde-bootc/packages-added | xargs dnf -y install –-allowerasing

PACKAGES-ADDED
# LibreOffice
libreoffice
libreoffice-help-en
# Utilities
vim-default-editor
git
....

Remove packages

Some of the standard packages included in @kde-desktop-environment don’t behave well and sometimes conflict with an immutable desktop, so we will remove them.

This is also an opportunity to remove software you may never use, saving resources and storage.

RUN grep -vE '^#' /usr/local/share/kde-bootc/packages-removed | xargs dnf -y remove
RUN dnf -y autoremove
RUN dnf clean all

The criteria used to remove some packages is listed below:

Conflict with bootc and its immutable nature.
plasma-discover-offline-updates
plasma-discover-packagekit
PackageKit-command-not-found

Bring unwanted dependencies.
tracker
tracker-miners
mariadb-server-utils
abrt
at
dnf-data

Deprecated services.
iptables-services
iptables-utils

Packages that are resource-heavy, or bring unnecessary services.
rsyslog
dracut-config-rescue

Configuration

This section will copy all necessary configuration files to /usr and /etc. As recommended by the bootc project, prioritise using /usr and use /etc as a fallback if needed.

Bash scripts that will be used by systemd services are stored in /usr/local/bin:

COPY --chmod=0755 ./system/usr__local__bin/* /usr/local/bin/

Custom configuration for new users’ home directories will be added to /etc/skel/. As an example you can customise bash.

COPY --chmod=0644 ./system/etc__skel__kde-bootc /etc/skel/.bashrc.d/kde-bootc

If you’re building your container image on GitHub and keeping it private, you’ll need to create a GITHUB_TOKEN to download the image. Further information is available at GitHub container registry.

COPY --chmod=0600 ./system/usr__lib__ostree__auth.json /usr/lib/ostree/auth.json

Users

I opted for systemd-homed users because they are better suited than regular users for immutable desktops, preventing potential drift in case of local modifications in /etc/passwd. Additionally, each user home benefits from LUKS encrypted volume.

The process begins when firstboot-setup runs, triggered by firstboot-setup.service during boot. It executes homectl firstboot, which checks if any regular home areas exist. If none are found, it searches for service credentials starting with home.create. to create users at boot.

The parameter below imports service credentials into the systemd service:

FIRSTBOOT-SETUP.SERVICE
...
ImportCredential=home.create.*

For more details, refer to the homectl and systemd.exec manual pages.

The homed identity file (usr__lib__credstore__home.create.admin) sets the user’s parameters, including username, real name, storage type, etc.

Common systemd-homed parameters:

• userName: A single word for your username and home directory. In this example, it is admin.
• realName: Full name for the user
• diskSize: The size of the LUKS storage volume, calculated in bytes. For instance, 1 GB equals 1024x1024x1024 bytes, which is 1073741824 bytes.
• rebalanceWeight: Relevant only when multiple user accounts share the available storage. If diskSize is defined, this parameter can be set to false.
• uid/gid: User and Group ID. The default range for regular users is 1000-6000, and for systemd-homed users, it is 60001-60513. However, you can assign uid/gid for systemd-homed users from both ranges.
• memberOf: The groups the user belongs to. As a power user, it should be part of the wheel group.
• hashedPassword: This is the hashed version of the password stored under secret. Setting up an initial password allows homectl firstboot to create the user without prompting. This password should be changed afterwards (homectl passwd admin). The hash password can be created using the mkpasswd utility.

We are storing the identity file in one of the directories where systemd-homed expects to find credentials.

COPY --chmod=0644 ./system/usr__lib__credstore__home.create.admin /usr/lib/credstore/home.create.admin

For more information on user records, visit: https://systemd.io/USER_RECORD/

This section also creates a temporary password for the root user. As I will explain later, having a root user as an alternative login is important.

echo "Temp#SsaP" | passwd root -s

Subuid and Subgid:

Another key parameter to set up is the range for /etc/subuid and /etc/subgid for the admin user. This range is necessary for running rootless containers since each uid inside the container will be mapped to a uid outside the container within this range. Systemd-homed predefines ranges for uid/gid.

The available range is 524288…1879048191. Choosing 1000001 makes it easy to identify the service running in the container. For instance, if the container is running Apache with uid=48, the volume or folder bound to it will have uid=1000048.

echo "admin:1000001:65536">/etc/subuid
echo "admin:1000001:65536">/etc/subgid

For more information on available ranges, visit: https://systemd.io/UIDS-GIDS/

The next step will set up authselect to enable authenticating the admin user on the login page. To achieve this, we need to enable the features with-systemd-homed and with-fingerprint (if your computer has a fingerprint reader) for the local profile.

authselect enable-feature with-systemd-homed
authselect enable-feature with-fingerprint

Systemd services

I decided to install at least two services; One to complete the configuration during machine boot, to run commands that require systemd (firstboot-setup.service), and the other one to automate updates (bootc-fetch.service).

We are enabling, by default, the first systemd service firstboot-setup:

COPY --chmod=0644 ./systemd/usr__lib__systemd__system__firstboot-setup.service /usr/lib/systemd/system/firstboot-setup.service
RUN systemctl enable firstboot-setup.service

USR__LIB__SYSTEMD__SYSTEM__FIRTBOOT-SETUP.SERVICE
[Unit]
Description=Setup USERS and /VAR at boot
After=multi-user.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/firstboot-setup
ImportCredential=home.create.*
[Install]
WantedBy=multi-user.target

And it runs the script below:

FIRSTBOOT-SETUP
# Setup hostname
HOST_NAME=kde-bootc
hostnamectl hostname $HOST_NAME
# Create user(s)
homectl firstboot
# Setup firewall to allow kdeconnect to functions
firewall-cmd --set-default-zone=public
firewall-cmd --add-service=kdeconnect --permanent

We are triggering bootc-fetch daily by a timer as a second systemd service:

COPY --chmod=0644 ./systemd/usr__lib__systemd__system__ bootc-fetch.service /usr/lib/systemd/system/bootc-fetch.service
COPY --chmod=0644 ./systemd/usr__lib__systemd__system__bootc-fetch.timer /usr/lib/systemd/system/bootc-fetch.timer

USR__LIB__SYSTEMD__SYSTEM__BOOTC-FETCH.TIMER
[Unit]
Description=Fetch bootc image daily
[Timer]
OnCalendar=*-*-* 12:30:00
Persistent=true
[Install]
WantedBy=timers.target

USR__LIB__SYSTEMD__SYSTEM__BOOTC-FETCH.SERVICE
[Unit]
Description=Fetch bootc image
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/bin/bootc update --quiet

This service replaces bootc-fetch-apply-updates, which would download and apply updates as soon as they are available. This approach is problematic because it causes your computer to shut down without warning, so it is better to disable by masking the timer:

RUN systemctl mask bootc-fetch-apply-updates.timer

How to create an ISO?

The instructions that follow will build the container locally. You need to do it as root so bootc-image-builder can use the image to make the ISO.

cd /path-to-your-repo
sudo podman build -t kde-bootc .

Then, outside the repository on a different directory, create a folder named output for the ISO image. And also you need to create the configuration file config.toml to feed the installer.

CONFIG.TOML
[customizations.installer.kickstart]
contents = "graphical"

[customizations.installer.modules]
disable = [
"org.fedoraproject.Anaconda.Modules.Users"
]

It instructs the installer to use the graphical interface and disable the module for user creation. We do not need to set up a user during installation, as this is already being taken care of.

Within the directory where ./output/ and ./config.toml exists, run bootc-image-builder utility which is available as a container. It must be run as root.

sudo podman run --rm -it --privileged --pull=newer \
--security-opt label=type:unconfined_t \
-v ./output:/output \
-v /var/lib/containers/storage:/var/lib/containers/storage \
-v ./config.toml:/config.toml:ro \
quay.io/centos-bootc/bootc-image-builder:latest \
--type iso \
--chown 1000:1000 \
localhost/kde-bootc

If everything goes well, the ISO image will be available in the ./output directory. You can use Fedora Media Writer to create a USB and put your images on a portable drive such as flash disk.

At the time of writing, the installer uses Anaconda and functions like any other Fedora flavor installation.

For more information on bootc-image-builder, visit: https://github.com/osbuild/bootc-image-builder

Post installation

The first step is to restore the SELinux context for the systemd-homed home directory. Without this, you may not be able to log in as admin. To complete this task, log in as root, activate admin home area, and then run restorecon to restore the SELinux context.

homectl activate admin
<< enter password for admin
restorecon -R /home/admin
homectl deactivate admin

At this point, you can change the passwords for root and admin:

passwd root
homectl passwd admin

After completing these steps, you can log out from root and log in to admin.

If your computer has a fingerprint reader, setting it up is not possible from Plasma’s user settings, as systemd-homed is not yet recognised by the desktop. However, you can manually enroll your fingerprint by running fprintd-enroll and placing your finger on the reader as you normally would.

sudo fprintd-enroll admin

Same as above, you cannot set up the avatar from Plasma’s user settings, but you can copy an available avatar (PNG file) from Plasma’s avatar directory to the account service’s directory. The file name needs to be the same as the username:

/usr/share/plasma/avatars/<avatar.png> -> /var/lib/AccountsService/icons/admin

Finally, enable the service to keep your system updated and any other desired services:

systemctl enable --now bootc-fetch.timer
systemctl enable --now tailscaled

Troubleshooting

Drifts on /etc

Please note that a configuration file in /etc drifts when it is modified locally. Consequently, bootc will no longer manage this file, and new releases won’t be transferred to your installation. While this might be desired in some cases, it can also lead to issues.

For instance, if /etc/passwd is locally modified, uid or gid allocations for services may not get updated, resulting in service failures.

Use ostree admin config-diff to list the files in your local /etc that are no longer managed by bootc, because they are modified or added.

If a particular configuration file needs to be managed by bootc, you can revert it by copying the version created by the container build from /usr/etc to /etc.

Adding packages after first installation

The /var directory is populated in the container image and transferred to your OS during initial installation. Subsequent updates to the container image will not affect /var. This is the expected behavior of bootc and generally works fine. However, some RPM packages execute scriptlets after installation, resulting in changes to /var that will not be transferred to your OS.

Instead of trying to identify and update the missing bits in /var, I found it easier to overlay /usr (bootc usr-overlay) and reinstall the packages (dnf reinstall ..) after updating and rebooting bootc.

References

GitHub – kde-bootc: https://github.com/sigulete/kde-bootc
GitHub – bootc: https://github.com/bootc-dev/bootc
GitLab – fedora-bootc: https://gitlab.com/fedora/bootc