LegendaryOS Builder

Spis treści

• Co to jest?
• Wymagania
• Instalacja
  • Ze źródeł
  • Release binary
• Szybki start
• Struktura projektu
• config.toml — konfiguracja
  • Wersjonowanie
  • Sekcja [project]
    • special_type
  • Sekcja [system]
  • Sekcja [desktop]
  • Sekcja [boot]
  • Sekcja [bootloader] (opcjonalna)
    • Obsługiwane typy bootloadera
  • Sekcja [anaconda]
  • Sekcja [build]
  • Sekcja [nvidia]
  • Sekcja [container]
  • Branches — warianty DE
• Polecenia
  • Flagi globalne
• Pakiety, pliki i skrypty
  • packages/install.packages
  • packages/flatpak.packages i flatpak.remove.packages
  • files/before/ i files/after/
  • scripts/
  • build.rb — własny skrypt budowania
• Tryby budowania (special_type)
  • default — Fedora immutable (bootc)
  • classic — zwykła Fedora
• Konfiguracja bootloadera
  • Przykład: systemd-boot
  • Przykład: rEFInd
  • Przykład: Limine
• Pipeline CI/CD (GitHub Actions)
• user.toml
• Budowanie buildera
• Architektura
• Licencja

Zautomatyzowane narzędzie do budowania niestandardowych dystrybucji Linuksa opartych na Fedorze — jako obrazy bootc OCI i bootowalne pliki ISO. Obsługuje zarówno tryb immutable (bootc/ostree) jak i klasyczny tryb mutable Fedory.

Co to jest?

LegendaryOS Builder to narzędzie wiersza poleceń napisane w Go, które pozwala zbudować własną dystrybucję Linuksa opartą na Fedorze z jednego pliku konfiguracyjnego config.toml.

Pipeline budowania składa się z dwóch etapów:

config.toml
  │
  ├─► build cloud ──► Containerfile ──► podman build ──► obraz OCI (ghcr.io)
  │                   (immutable: fedora-bootc + ostree commit)
  │                   (classic:   plain fedora, bez ostree)
  │
  └─► build iso ───► bootc-image-builder ──► .iso

Obraz OCI w trybie domyślnym jest tworzony za pomocą bootc, co oznacza, że system operacyjny może być aktualizowany atomowo przez bootc upgrade. W trybie classic budowany jest standardowy obraz kontenera Fedory bez ostree.

Wymagania

Narzędzie	Uwagi
Fedora 44+ (host)	Wymagane dla build cloud i build iso
podman ≥ 4.x	Wymagane. sudo dnf install podman
bootc-image-builder	Wymagane dla build iso. sudo dnf install bootc-image-builder
Go 1.22+	Tylko do kompilacji buildera
Ruby	Wymagane do uruchomienia build.rb oraz build.rb install
cosign (opcjonalnie)	Do podpisywania obrazów: sudo dnf install cosign

Note	build iso wymaga uprawnień roota (sudo) — bootc-image-builder używa rootful podman.

Instalacja

Ze źródeł

git clone https://github.com/LegendaryOS-Linux-System/legendaryos-builder
cd legendaryos-builder

# Buduj i instaluj (Ruby)
ruby build.rb install

# lub przez go bezpośrednio
go build -o legendaryos-builder .
sudo install -m 0755 legendaryos-builder /usr/local/bin/legendaryos-builder

Release binary

curl -fsSL \
  https://github.com/LegendaryOS-Linux-System/legendaryos-builder/releases/latest/download/legendaryos-builder-linux-amd64.tar.gz \
  -o /tmp/legendaryos-builder.tar.gz

tar -xzf /tmp/legendaryos-builder.tar.gz -C /tmp
sudo install -m 0755 /tmp/legendaryos-builder /usr/local/bin/legendaryos-builder

legendaryos-builder version

Szybki start

# 1. Utwórz katalog projektu
mkdir my-os && cd my-os

# 2. Inicjalizacja projektu (interaktywny wizard)
legendaryos-builder init --fast

# 3. Edytuj konfigurację
$EDITOR config.toml

# 4. Zbuduj obraz OCI
legendaryos-builder build cloud

# 5. Zbuduj ISO (wymaga sudo)
sudo legendaryos-builder build iso

Struktura projektu

Po legendaryos-builder init katalog projektu wygląda następująco:

my-os/
├── config.toml                 ← główna konfiguracja
├── user.toml                   ← dane osobiste (gitignored)
├── build.rb                    ← opcjonalny własny skrypt budowania
├── packages/
│   ├── install.packages        ← pakiety DNF do instalacji
│   ├── remove.packages         ← pakiety DNF do usunięcia
│   ├── flatpak.packages        ← aplikacje Flatpak (stosowane przy instalacji OS)
│   ├── flatpak.remove.packages ← aplikacje Flatpak do usunięcia (przy instalacji OS)
│   └── *.rpm                   ← lokalne pliki .rpm (opcjonalnie)
├── files/
│   ├── before/                 ← overlay przed instalacją pakietów
│   └── after/                  ← overlay po instalacji pakietów
├── scripts/
│   ├── pre/                    ← skrypty na HOŚCIE przed buildem
│   ├── before/                 ← skrypty w kontenerze PRZED dnf install
│   └── after/                  ← skrypty w kontenerze PO dnf install
├── repos/                      ← niestandardowe pliki .repo
├── .github/workflows/
│   └── build-cloud.yml         ← GitHub Actions CI
└── build/
    ├── cache/
    └── output/                 ← końcowe .iso

config.toml — konfiguracja

Plik config.toml jest jedynym miejscem, gdzie konfigurujesz swój system operacyjny.

Wersjonowanie

Pola version, tag i product_version przyjmują:

• Numery semver: 0.1.0, 1.2.3, 44

• Symboliczne etykiety kanałów: stable, beta, alpha, nightly, latest, edge, dev

[project]
version = "stable"    # etykieta kanału → tag OCI: ghcr.io/org/myos:stable

# lub

version = "0.1.0"     # semver → tag OCI: ghcr.io/org/myos:0.1.0

Sekcja [project]

[project]
name         = "LegendaryOS"
version      = "stable"          # semver lub: stable | beta | alpha | nightly | latest | edge | dev
description  = "Fedora-based OS"
author       = "LegendaryOS-Linux-System"
license      = "GPL-3.0"
base_distro  = "fedora"
base_version = 44                # minimalna wersja: 44
arch         = "x86_64"

# special_type — tryb budowania:
#   "default" (lub brak) → Fedora immutable (bootc/ostree) — zachowanie jak dotychczas
#   "classic"            → zwykła, mutowalna Fedora (tradycyjny system RPM, bez bootc)
special_type = "default"

special_type

Wartość	Opis
default (lub brak pola)	Fedora immutable — obraz bazuje na fedora-bootc, kończy się ostree container commit. System aktualizowany atomowo przez bootc upgrade.
classic	Zwykła mutowalna Fedora — obraz bazuje na registry.fedoraproject.org/fedora, bez ostree. Standardowy system RPM taki jak tradycyjna instalacja Fedory.

Sekcja [system]

[system]
hostname         = "legendaryos"
locale           = "pl_PL.UTF-8"
language         = "pl_PL:pl:en_US:en"
timezone         = "Europe/Warsaw"
keyboard         = "pl"
selinux          = "enforcing"   # enforcing | permissive | disabled
firewall         = true
services_enable  = ["sshd", "NetworkManager", "bluetooth"]
services_disable = ["ModemManager"]

Sekcja [desktop]

[desktop]
environment     = "kde"          # gnome | kde | xfce | cinnamon | mate | lxqt | cosmic | none
display_server  = "wayland"      # wayland | x11 | both
auto_login      = false
auto_login_user = ""

Sekcja [boot]

Sekcja [boot] działa jak dotychczas gdy [bootloader] jest wyłączony lub nieobecny.

[boot]
bootloader  = "grub2"
kernel_args = "quiet splash mitigations=off"
splash      = true
timeout     = 5

Sekcja [bootloader] (opcjonalna)

Nowa, opcjonalna sekcja pozwalająca wybrać alternatywny bootloader. Gdy enabled = false (lub sekcja jest nieobecna) zachowanie jest identyczne jak dotychczas — rządzi boot.bootloader.

[bootloader]
enabled          = true
# type: grub2 | refind | limine | systemd-boot | syslinux
type             = "systemd-boot"
# Dodatkowe argumenty kernela dołączane gdy ten bootloader jest aktywny
extra_args       = ""
# Dodatkowe pakiety DNF instalowane dla tego bootloadera
install_packages = []
# Katalog partycji EFI (domyślnie /boot/efi)
efi_dir          = "/boot/efi"

Obsługiwane typy bootloadera

Wartość	Opis
grub2 (domyślny)	GRUB 2 — takie samo zachowanie jak boot.bootloader = "grub2"
refind	rEFInd — menedżer rozruchu EFI
limine	Limine — nowoczesny bootloader
systemd-boot	systemd-boot (sd-boot)
syslinux	SYSLINUX / ISOLINUX

Sekcja [anaconda]

[anaconda]
enabled            = true
product_name       = "LegendaryOS"
product_version    = "stable"    # mirrors project.version
webui              = true
default_lang       = "pl_PL.UTF-8"
default_keyboard   = "pl"
default_timezone   = "Europe/Warsaw"
root_password_lock = true
default_user       = "user"
default_user_groups = ["wheel", "audio", "video", "gamemode", "input", "render"]

Sekcja [build]

[build]
output_dir   = "build/output"
cache_dir    = "build/cache"
compression  = "zstd"            # zstd | xz | gzip
iso_label    = "LEGENDARYOS"
iso_filename = ""                # puste = auto-generowane
jobs         = 4
filesystem   = "ext4"            # ext4 | xfs | btrfs

Sekcja [nvidia]

[nvidia]
enabled                 = true
open_driver             = false
blacklist_nouveau        = true
enable_kms              = true
install_nvidia_settings = true
install_vaapi           = true
install_vulkan          = true
install_cuda            = false

Sekcja [container]

[container]
enabled    = true
registry   = "repo"
repo       = "LegendaryOS-Linux-System/legendaryos"
image      = "legendaryos"
tag        = "stable"
push       = false
sign_image = false
bootc_mode = true

Branches — warianty DE

[[branch]]
name         = "gnome"
display_name = "LegendaryOS GNOME Edition"
desktop      = "gnome"
tag          = "stable-gnome"
enabled      = true
extra_packages  = ["@gnome-desktop-environment"]
remove_packages = ["@kde-desktop-environment"]

Polecenia

legendaryos-builder <polecenie> [flagi]

Polecenie	Opis
build cloud	Buduje obraz bootc/classic OCI za pomocą podman
build cloud --push	Buduje i wysyła do ghcr.io
build cloud --push --sign	Buduje, wysyła i podpisuje przez cosign
build cloud --no-cache	Buduje bez cache’u warstw
build cloud --release	Tryb release: squash warstw, usunięcie symboli debugowania
build iso	Buduje bootowalne ISO z obrazu OCI
build iso --source <img>	ISO z konkretnego obrazu OCI
build iso --output <path>	Zapis ISO pod wskazaną ścieżkę
build --release	Pełny pipeline: cloud --push + iso
build	Uruchamia build.rb z katalogu projektu (bez żadnych flag)
build ;;	Wyświetla wszystkie dostępne zadania zdefiniowane w build.rb (--tasks)
build ''	Wyświetla dostępne subkomendy build.rb (--help)
build -_ <plik>	Uruchamia wskazany plik zamiast build.rb
settings	Interaktywny edytor TUI konfiguracji
init [dir]	Inicjalizuje scaffold projektu
init --fast	Interaktywny wizard (zadaje pytania)
validate	Sprawdza konfigurację bez budowania
info	Wyświetla informacje o projekcie i listę pakietów
clean	Usuwa build/output/
clean --all	Usuwa cały katalog build/
setup	Instaluje zależności na hoście (Fedora)
setup --release	Instaluje również cosign
version	Wyświetla wersję buildera

Flagi globalne

Flaga	Opis
--verbose, -v	Pełne wyjście poleceń
--release	Tryb release
--no-cache	Wyłącza cache warstw podman

Pakiety, pliki i skrypty

packages/install.packages

Jeden pakiet DNF na linię. Komentarze zaczynają się od #. Grupy pakietów mają prefiks @.

bash-completion
curl
git
@kde-desktop-environment
# to jest komentarz

packages/flatpak.packages i flatpak.remove.packages

Note	Pliki flatpak.packages i flatpak.remove.packages NIE są wykonywane podczas budowania obrazu OCI/kontenera. Są one wbudowywane do sekcji %post kickstarta Anacondy i wykonywane na zainstalowanym systemie podczas procesu instalacji OS.

# packages/flatpak.packages
com.visualstudio.code
com.spotify.Client
com.discordapp.Discord

files/before/ i files/after/

Drzewa plików nakładane na obraz kontenera — before/ przed instalacją pakietów, after/ po instalacji.

scripts/

Katalog	Kiedy uruchamiany
scripts/pre/	Na HOŚCIE przed jakimkolwiek krokiem budowania
scripts/before/	W kontenerze PRZED dnf install
scripts/after/	W kontenerze PO dnf install

Obsługiwane rozszerzenia: .sh, .py, .pl, .rb. Skrypty są sortowane i wykonywane alfabetycznie.

build.rb — własny skrypt budowania

Opcjonalny plik build.rb umieszczony obok config.toml jest uruchamiany przez polecenie legendaryos-builder build (bez żadnych argumentów).

# Uruchom build.rb
legendaryos-builder build

# Wyświetl wszystkie zadania zdefiniowane w build.rb
legendaryos-builder build ;;

# Wyświetl subkomendy build.rb (--help)
legendaryos-builder build ''

# Uruchom własny plik zamiast build.rb
legendaryos-builder build -_ myscript.rb
legendaryos-builder build -_ scripts/custom-build.rb

Tryby budowania (special_type)

default — Fedora immutable (bootc)

Domyślny tryb. Obraz bazuje na quay.io/fedora/fedora-bootc:<wersja>. Containerfile kończy się RUN ostree container commit. System może być aktualizowany atomowo przez bootc upgrade.

classic — zwykła Fedora

Tryb klasyczny. Obraz bazuje na registry.fedoraproject.org/fedora:<wersja>. Brak ostree — standardowy, mutowalny system RPM identyczny z tradycyjną instalacją Fedory. Containerfile nie zawiera ostree container commit.

[project]
special_type = "classic"   # zwykła Fedora
# lub
special_type = "default"   # immutable bootc (domyślnie)

Konfiguracja bootloadera

Sekcja [bootloader] jest opcjonalna. Gdy nieobecna lub enabled = false, builder zachowuje się identycznie jak przed jej dodaniem — rządzi boot.bootloader.

Przykład: systemd-boot

[bootloader]
enabled          = true
type             = "systemd-boot"
extra_args       = "mitigations=off"
install_packages = ["efi-filesystem"]
efi_dir          = "/boot/efi"

Przykład: rEFInd

[bootloader]
enabled = true
type    = "refind"
efi_dir = "/boot/efi"

Przykład: Limine

[bootloader]
enabled = true
type    = "limine"

Pipeline CI/CD (GitHub Actions)

legendaryos-builder init generuje .github/workflows/build-cloud.yml. Workflow:

1. Pobiera binarkę legendaryos-builder

2. Instaluje podman

3. Loguje się do ghcr.io

4. Oblicza tag obrazu (tag git lub latest)

5. Uruchamia legendaryos-builder validate

6. Uruchamia legendaryos-builder build cloud --push

7. Podpisuje obraz przez cosign (Sigstore)

user.toml

Plik user.toml przechowuje dane osobiste i jest automatycznie pomijany przez .gitignore.

[github]
type  = "org"
name  = "moja-organizacja"
token = ""                  # zostaw puste — builder zapyta interaktywnie
                            # lub użyj zmiennej środowiskowej GITHUB_TOKEN

Token można podać przez zmienną środowiskową:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
legendaryos-builder build cloud --push

Budowanie buildera

# Dev build
ruby build.rb

# Release binary + tarball + checksum
ruby build.rb release

# Instalacja do /usr/local/bin
ruby build.rb install

# Wszystkie testy
ruby build.rb test

# Formatowanie kodu
ruby build.rb fmt

# Sprawdzanie kodu
ruby build.rb vet

Architektura

legendaryos-builder/
├── main.go
├── go.mod
├── build.rb                    ← skrypt budowania (zastępuje Makefile)
├── config.toml                 ← przykładowa konfiguracja projektu
├── src/
│   ├── builder/
│   │   ├── cloud.go            ← CloudBuilder (podman build/push/sign)
│   │   │                          obsługuje tryb immutable i classic
│   │   ├── iso.go              ← ISOBuilder (bootc-image-builder)
│   │   └── kickstart.go        ← generator kickstarta Anaconda
│   │                              (Flatpak stosowany w %post)
│   ├── cli/
│   │   ├── cli.go              ← dispatcher poleceń + obsługa build.rb
│   │   ├── init.go             ← scaffold projektu + szablony
│   │   ├── settings.go         ← interaktywny edytor konfiguracji TUI
│   │   └── secret.go           ← czytanie hasła bez echa (POSIX termios)
│   ├── config/
│   │   ├── config.go           ← parser TOML + struktury + BootloaderConfig
│   │   │                          + SpecialType + VersionTag
│   │   └── user.go             ← parser user.toml
│   └── ui/
│       ├── ui.go               ← TUI: kolory, paski postępu, podsumowanie buildu
│       └── usage.go            ← pomoc / instrukcja użycia

Licencja

Projekt jest dostępny na licencji MIT. Szczegóły w pliku LICENSE.

---

LegendaryOS Builder — Fedora Edition · x86_64 · bootc OCI native · classic support