Matcha Linux

Today, when one Hack Clubber pointed out that they wish to try Matcha Linux on Hyper-V, I thought it would work. Turns out I was completely wrong!

Linux, built with the LTS kernel instead of VM-specific (Virt), breaks on Hyper-V due to inability to pass the framebuffer through Hyper-V’s exceptional drivers (or so I think). The minimal terminal works, but flickers due to GDM trying to restart every few ms.

Implementing a dual-ISO build pipeline I fixed this issue and also made Matcha Linux and its packages work on top of a new Alpine (v3.24) release. Thought it would be harder, but both Alpine itself, and Gnome 50 play along very well!

Also added Hyper-V specific instructions to the README.

It builds, it runs, it WORKS!

I was really surprised with how this OS turned out. After what seemed like a rollercoaster of issues that had me stumped for a while, and countless hours of debugging, I STILL managed to deliver a working product this soon. It relieved me, and I can consider myself both lucky and proud.

After fixing all said issues in the previous devlogs, I present Matcha Linux 2026.06.09 - the initial release.

Matcha Linux was made to combat e-waste, hardware pricing increase and provide a beautiful yet customizable experience to absolutely anyone! By being able to run it on any x86_64 UEFI-compatible piece of hardware, using very few resources, Matcha Linux aims to be the primary choice for people trying to escape bloat.

What was fixed since the last devlog:

• Swap not working due to a service not being run on boot
• Locales not being correctly set up due to a missing installer module

Additional tweaks:

• Reworked the permission system to be more reliable and controllable (when building the live ISO image)
• Implemented a proper post-install reboot mechanism by tweaking installer’s configuration
• Refactored build source files to be more compact, added comments where necessary
• Removed keyboard configuration from the installer due to it not being well integrated with GNOME
• Cleaned up repositories, added better documentation, published first working release files

I consider this experience a lesson not only about Linux, but also the need of doing things sequentally, planning and always going forward, no matter what challenge waits up front.

Do I have something else planned for the future?

YES! But these things may be quite difficult:

• A custom installer module to provide the setup for Distrobox (to run almost any Linux app (by default they won’t run unless installed through APK and are within Alpine Linux repositories. Running layered Debian, Arch or Fedora boxes creates disposable and highly capable environments))
• A custom updater program (probably won’t be integrated this summer)
• Further debugging and engaging with the community

I hope this project inspires many people to build projects and solve problems for the whole world.
Open source, as it should be.

Several bugs fixed! (And one drawback taken)

First off, with the fixes:

• Installer UI no longer crashes when selecting a swap option or entering encryption details (the issue was only persistent on legacy BIOS boot and without a certain configuration file (bootloader.conf, that got added))
• Encryption finally works! Can’t show in the devlog image, but a disk can be encrypted and decrypted with LUKS properly
• A non-encrypted approach of installation is also viable and works as it should

Drawback (the sad part):

• Since I couldn’t get legacy BIOS to not crash the installer in a mentioned case, after strong considerations I have decided that Matcha Linux will only officially support EFI, and enforced this behaviour in the build pipeline
• This gets along the philosophy of using modern lightweight standards that Matcha tries to utilize, so it’s not much of a loss

What remains broken:

• Swap memory does not seem to be working in the installed system, even when the necessary files ARE created by the installer
• Timezones don’t still work properly

After fixing said issues the project will be ready to ship. Hopefully it shouldn’t take more than a week

I have successfully resolved the issues found in the earlier build, and everything works (almost) flawlessly now!

New things:

• Cleaned up build scripts to make them more portable and more easily readable
• Implemented package exclusion when installing the OS
• Customized the default dock apps list
• Improved branding by implementing FastFetch configuration

However, I have noticed some bugs that are worth taking a look into:

• When setting up the disk with swap space, the installer crashes. Maybe just a package missing that handles this
• LUKS encryption does not work
• Timezone setup is useless as it doesn’t set up the timezone (manual setup is working post-install, but the installer SHOULD set that up)

After fixing those, Matcha Linux can finally ship!

Since the last devlog, I put in a LOT of work to make the whole OS build properly

This includes:

• Setting up a well-working approach for installing Matcha Calamares installer to the live system
• Adding a README to (almost) all repositories related to this project
• Customizing the installer
• Tweaking a few things for smoother performance

Next steps are:

• Removing hardcoded references to just make the images “build and run”
• Reflecting ways of optimization
• Excluding unnecessary stuff from the installed system
• Testing everything for the final time
• Shipping!
  Wish me luck, now I’m heading out, polishing this project

FINALLY did I fix the system running incorrectly
Turns out, the problem was a faulty overlay that kept overwriting user account files, thus revoking the ability for some system services to run!
Now the system installs beautifully, runs even prettier, only thing left is to test whether there is no junk in a fresh system and the user is set up correctly and if the startup times could be improved (unless it’s VirtualBox-specific)
Other goals haven’t changed since the last devlog, but I am starting to question if I really need to write software for this distribution myself (for issuing updates, etc…) because the process should be fairly straightforward

First devlog, and with good news already!
After successfully porting Calamares installer over to Alpine Linux, today I also made it install the system correctly
The issue was bad grub configuration that either did not mount the system or did not load ext4 kernel module
With that resolved (and a bit of a rework on live iso build profile) Matcha Linux is one step closer to being at least usabe post-install

Remaining issues are:

• Incorrect group and user creation process due to which dbus service can’t launch (critical)

Remaining steps are:

• Testing if other core services that depend on dbus launch after fixing the issue
• Testing the system and whether everything copies correctly

Future plans:

• Customizing the installer
• Adding a DistroBox Debian shell by default for app compatibility
• Making an updater app