How I Built Kafy

Kafy is a Debian-based desktop Linux distro built to feel polished, work out of the box, and support gaming without forcing people into Linux setup rituals.

This article is the engineering story behind the first Kafy image: the build profile, the package decisions, the way I used Debian live-build, and the principles that kept the project moving.

The core engineering problem

Kafy is not a kernel rewrite or a new package manager. It is a product that starts from Debian and adds a set of defaults, apps, drivers, and desktop flow that work immediately.

That means the project has to solve two engineering problems at once:

make a reliable build system for a bootable ISO
choose defaults and hooks that make the image usable without extra setup

If the first ISO cannot boot as a real desktop, then the rest of the distro is just an idea.

Why I chose Debian live-build

I wanted the first Kafy deliverable to be concrete and repeatable. Debian live-build is the right tool for that because it already knows how to:

create a temporary chroot filesystem
install Debian packages into it
copy in custom files
run build hooks inside the image
assemble a bootable hybrid ISO

The key Kafy files are all in distro/kafy:

auto/config to configure lb and the image type
config/package-lists/*.list.chroot to install the runtime packages
config/includes.chroot/ to copy files into the target filesystem
config/hooks/normal/ to run setup scripts inside the image
config/archives/ to fix Debian archive behavior for Bookworm

The first image strategy

Instead of building a custom compositor first, I built a bootable OS with an existing desktop shell. That made the project deliverable and testable from day one.

The first real image uses:

Debian Bookworm as the base
KDE Plasma on Wayland as the desktop baseline
firmware and driver packages for modern hardware
gaming tooling and Flatpak support

Why KDE first? Because it gives a real desktop environment with session management, display settings, app launching, and portal support immediately. It is not the final Kafy shell, but it is a strong, stable baseline.

Package decisions that matter

The package lists in distro/kafy/config/package-lists reflect the core product direction:

00-base.list.chroot installs system services, networking, audio, firmware, and essential hardware support
10-desktop.list.chroot installs KDE Plasma, SDDM, media apps, and the installer UI
20-gaming.list.chroot adds Steam, Wine, Lutris, Vulkan tooling, controller support, and game performance utilities
30-apps.list.chroot includes Flatpak, Discover Flatpak backend, Timeshift, media tools, productivity apps, and developer utilities

This is not a generic Debian image. It is a curated default experience that should boot into a usable desktop with gaming and app distribution available.

Build configuration and robustness

The image configuration is intentionally version-aware. auto/config checks the installed lb config --help output before using optional options like --bootloaders and --image-name.

That makes the build profile more robust across different live-build versions.

Example from auto/config:

if has_lb_option "--bootloaders"; then
  set -- "$@" --bootloaders "grub-efi grub-pc"
elif has_lb_option "--bootloader"; then
  set -- "$@" --bootloader grub-efi
fi

The profile also disables deprecated Bookworm behavior and sets security archives explicitly, which is important for repeatable builds.

Automation with hooks

The build hooks are where Kafy makes the image feel like a product instead of a raw Debian snapshot.

For example:

010-enable-services.hook.chroot enables NetworkManager, Bluetooth, CUPS, SDDM, and power management services
020-flatpak-flathub.hook.chroot adds Flathub automatically
030-gaming-defaults.hook.chroot sets runtime and kernel tuning for audio/gaming workloads
040-kafy-branding.hook.chroot injects Kafy branding into /etc/issue and /etc/os-release

These hooks are small but important: they encode the defaults that make the image usable out of the box.

Design principles behind the build

There were a few product-engineering principles that guided every decision:

keep the first image honest and usable
avoid building custom infrastructure too early
choose stable defaults, not the latest bleeding-edge stack
make recovery and install flows work by default
keep the build repeatable and easy to run on a Debian host

That is why the first Kafy image is Debian + KDE + gaming defaults, not a brand-new compositor and shell.

What I learned

Building Kafy taught me that early-stage platform work is mostly about constraints and integration, not clever technology.

The biggest wins were:

making the build process deterministic with live-build
separating package selection from branding and runtime tuning
using small hooks to make the image feel polished
opting for a real desktop baseline instead of an idealized custom shell

What comes next

This first image is the engineering foundation for Kafy. Once the distro boots reliably, the next phase can focus on the custom shell and compositor work.

That future path is still grounded in the same product rule:

boot into a usable desktop
ship defaults that reduce setup friction
support gaming and hardware without extra configuration
let the base image evolve from actual usage and testing

If you want to understand Kafy as an engineer, the story is not "build something exotic." It is "build the right first image, then make the product better from a working foundation."