Problem
Mainstream distributions ship heavy defaults tuned for nobody in particular. The CodeVerse Hub community wanted a distro shaped by their own workflow Wayland-first, developer-oriented, and minimal and, just as importantly, a shared project that would teach members distro engineering from the inside.
Distro projects are usually opaque: they expect deep Arch knowledge just to build an ISO. The team set out to make the build path a documented learning journey, so a first-timer could go from 'what is an ISO?' to flashing their own build.
Goals
Build
Reproducible ArchISO profile with a single build script that outputs a bootable .iso artifact.
Install
Interactive cvh-install installer that walks users through disk selection and setup with clear prompts.
Configure
Curated Wayland-first configs niri, waybar, rofi, GRUB theme committed to the repo as the distro's default experience.
Learn
Beginner-friendly documentation that starts at 'what is an ISO?' so community members can build and flash their own.
Architecture
┌──────────────────────────────────────────────────────────────────────────┐ │ CODEVERSE LINUX (CVH LINUX) │ ├──────────────────────────────────────────────────────────────────────────┤ │ Source → Build → Output │ │ ┌────────────────────┐→ ┌───────────────────┐→ ┌──────────────────────┐ │ │ │iso/ (ArchISO │→ │build-iso.sh │→ │out/ .iso │ │ │ │profile) │→ │build-pkg.sh │→ │artifact │ │ │ │configs/ niri │→ │cvh-install │→ │live environment │ │ │ │waybar · rofi │→ │(interactive) │→ │+ installer │ │ │ └────────────────────┘→ └───────────────────┘→ └──────────────────────┘ │ │ custom packages: src/ · pkgbuild/ · repo/ (local pacman repo) │ └──────────────────────────────────────────────────────────────────────────┘
The repository is structured around a classic distro pipeline: source, build, output. An ArchISO profile in iso/ declares the package set, filesystem layout, and bootloader. Build tooling in scripts/ assembles the ISO and installs custom packages built from src/ via PKGBUILDs into a local pacman repo. The output is a bootable ISO that boots into a Wayland-first desktop with curated configs, and a cvh-install installer that partitions and sets up the target disk interactively.
ArchISO Profile
iso/ holds the packages list, airootfs overlay, and bootloader config the declarative heart of the distribution.
Build Tooling
scripts/build-iso.sh assembles the ISO; scripts/build-pkg.sh builds custom packages from PKGBUILDs into the local repo.
Curated Configs
configs/ ships the Wayland-first default experience: niri compositor, waybar status bar, rofi launcher, and a custom GRUB theme.
Installer
cvh-install runs inside the live environment, interactively selecting the target disk, partitioning, and completing setup with on-screen prompts.
Key Features
Wayland-First Desktop
A curated niri + waybar + rofi stack tuned for a developer workflow, replacing the GNOME/KDE defaults of most distros.
Interactive Installer
cvh-install guides users through disk selection and setup no command-line partitioning knowledge required.
Custom Packages
src/ + pkgbuild/ + repo/ maintain the distro's own software in a local pacman repository, versioned like any Arch package.
Beginner-First Docs
The README walks from 'what is an ISO?' through building, flashing to USB, and booting in VirtualBox or QEMU.
Tech Stack
ArchISO
The official Arch tooling for building reproducible ISO profiles.
bash / shell
Build scripts and the interactive installer logic.
niri · waybar · rofi
The Wayland-first default desktop stack shipped in configs/.
GRUB
Bootloader with a custom theme, configured in the ISO profile.
pacman
Package management, extended by a local repo of custom packages.
Results
CodeVerse Linux became the org's flagship systems project and one of its most-forked repositories. The beginner-first documentation has converted members with zero Linux packaging experience into contributors who can build, flash, and install their own distribution exactly the 'learn by building' outcome the community exists for.
Challenges & Trade-offs
Challenge
ArchISO builds only run on Arch-based hosts, which excludes most contributors' daily machines.
Solution
Builds are officially supported inside VMs, and the docs dedicate a section to building within VirtualBox/QEMU Arch guests.
Challenge
The installer wipes the selected disk one wrong choice and a user's data is gone.
Solution
The installer is interactive and warns explicitly at each destructive step; docs recommend VM testing until users are comfortable.
Challenge
Curated configs drift as upstream tools (niri, waybar) release breaking changes.
Solution
Configs are committed and versioned in the repo with the ISO, so a build always pairs a known-good config set with a known-good package set.
Implementation Highlights
Local Pacman Repo
Custom packages ship through the distro's own repository, teaching contributors real package-maintenance skills.
One-Command Build
./scripts/build-iso.sh turns the profile into a bootable .iso in out/ the entire pipeline is two commands from clone to flash.
Learning by Doing
The README doubles as a curriculum: contributors learn ISO internals, partitioning, and boot flows by building.
Lessons Learned
A distribution is a documentation problem as much as an engineering one beginner docs doubled the contributor pool.
Declaring everything (profile, packages, configs) in the repo makes builds reproducible and reviewable.
VM-first testing turns a scary system-level project into something a first-timer can safely break and rebuild.