diff --git a/README.md b/README.md index 4769bef..6474550 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Complete Guide to Creating a Custom Arch Linux ISO -[![Scheduled ArchISO Build](https://git.vilaythong.us/alvinlollo/AlvinArch/actions/workflows/build-iso.yaml/badge.svg?branch=main)](https://git.vilaythong.us/alvinlollo/AlvinArch/actions?workflow=build-iso.yaml) [![Checks](https://git.vilaythong.us/alvinlollo/AlvinArch/actions/workflows/checks.yaml/badge.svg?branch=main)](https://git.vilaythong.us/alvinlollo/AlvinArch/actions?workflow=checks.yaml) +[![Scheduled ArchISO Build](https://git.vilaythong.us/alvinlollo/AlvinArch/actions/workflows/build-iso.yaml/badge.svg?branch=main)](https://git.vilaythong.us/alvinlollo/AlvinArch/actions?workflow=build-iso.yaml) [![Tests](https://git.vilaythong.us/alvinlollo/AlvinArch/actions/workflows/tests.yaml/badge.svg?branch=main)](https://git.vilaythong.us/alvinlollo/AlvinArch/actions?workflow=tests.yaml) DistroTube: @@ -33,35 +33,28 @@ AlvinArch/ 2. [Prerequisites](#prerequisites) 3. [Directory Structure](#directory-structure) 4. [Core Configuration Files](#core-configuration-files) -5. [Package Management](#package-management) -6. [System Configuration](#system-configuration) -7. [Custom Scripts and Applications](#custom-scripts-and-applications) +5. [User Configuration (skel/)](#user-configuration-skel) +6. [System Services & Networking](#system-services--networking) +7. [Local Repository (localrepo/)](#local-repository-localrepo) 8. [Boot Configuration](#boot-configuration) -9. [Branding and Customization](#branding-and-customization) -10. [Building the ISO](#building-the-iso) -11. [VirtualBox Compatibility](#virtualbox-compatibility) -12. [Advanced Configurations](#advanced-configurations) -13. [KyOS Rebranding Process](#kyos-rebranding-process) -14. [Troubleshooting](#troubleshooting) -15. [Best Practices](#best-practices) +9. [Build & Test](#build--test) +10. [Planned Additions](#planned-additions) +11. [Troubleshooting](#troubleshooting) --- ## Overview -This guide provides comprehensive documentation for creating KyOS - a custom Arch Linux ISO distribution based on the archiso framework. Originally forked from DTOS (Derek Taylor's Operating System), KyOS has been completely rebranded and optimized for modern use cases, including VirtualBox compatibility. The ISO includes custom branding, curated package selection, optimized configurations, and intelligent installation scripts. +**AlvinArch** is a custom Arch Linux live ISO built on the [archiso](https://wiki.archlinux.org/title/Archiso) framework. It ships a Hyprland desktop with [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland), a curated set of ~400 packages, and a local repository of pre-built AUR packages for packages not available in official repos. The ISO targets both real hardware and VMs (VirtualBox/Hyper-V/VMware guest services are enabled out of the box). -### What You'll Learn +### Key Features -- Complete archiso project structure for KyOS -- Advanced package management (official repos + AUR + custom packages) -- Custom configuration deployment and user management -- Complete system rebranding from DTOS to KyOS -- VirtualBox compatibility and optimization -- Installation script development with TUI support -- Boot loader configuration for multiple boot methods -- System service management and customization -- Qtile window manager optimization for VMs +- **Hyprland + end-4** — Wayland compositor with illogical-impulse dotfiles (quickshell, bibata cursors, microtex) +- **LazyVim** — Pre-configured Neovim with lazy.nvim and curated plugins +- **Fish + Zsh + Starship** — Dual shell setup with oh-my-zsh and a cross-shell prompt +- **Local AUR repo** — Pre-built packages (end-4 deps, wallust, grub-customizer, etc.) that aren't in official repos +- **Curated packages** — ~400 packages across ccache, networking, dev tools, and desktop utilities +- **Guest VM support** — VirtualBox, Hyper-V, and VMware tools auto-enabled --- @@ -91,948 +84,303 @@ sudo pacman -S arch-install-scripts squashfs-tools ### Complete Project Layout ``` -your-custom-iso/ -├── profiledef.sh # Main ISO configuration file - defines ISO metadata, build options, and file permissions -├── packages.x86_64 # Live environment packages - packages installed in the live ISO for basic functionality -├── bootstrap_packages.x86_64 # Bootstrap packages for build - minimal packages needed during ISO creation process -├── pacman.conf # Pacman configuration with repositories - defines package sources and signing requirements -├── airootfs/ # Root filesystem overlay - files copied directly to live system root -│ ├── etc/ # System configuration files - global system settings and configurations -│ │ ├── os-release # Operating system identification - defines distro name, version, URLs for system info -│ │ ├── motd # Message of the day - welcome text displayed on terminal login -│ │ ├── hostname # Default hostname - sets the default system hostname for live environment -│ │ ├── locale.conf # System locale - defines language, character encoding, and regional settings -│ │ ├── bash.bashrc # Global bash configuration - system-wide bash shell settings and aliases -│ │ ├── doas.conf # Privilege escalation config - defines sudo-like permissions for doas command -│ │ ├── pacman.conf # Target system pacman config - package manager settings for installed system -│ │ ├── group # System groups - defines system user groups and their GIDs -│ │ ├── passwd # System users - defines system user accounts and their UIDs -│ │ ├── shadow # Password hashes - stores encrypted passwords for system security -│ │ ├── gshadow # Group passwords - stores encrypted group passwords for group access -│ │ ├── localtime # System timezone - symlink to timezone data for system clock -│ │ ├── resolv.conf # DNS resolver config - defines DNS servers for network name resolution -│ │ ├── default/ # Default configurations - system-wide default settings -│ │ │ └── grub # GRUB defaults - default boot loader settings and kernel parameters -│ │ ├── skel/ # Default user home directory - template for new user home directories -│ │ │ ├── .config/ # User application configs - per-user application configuration directory -│ │ │ │ ├── qtile/ # Window manager config - Qtile window manager configuration files -│ │ │ │ │ ├── config.py # Main Qtile config - defines keybindings, layouts, and window manager behavior -│ │ │ │ │ ├── autostart.sh # Qtile autostart script - applications launched when Qtile starts -│ │ │ │ │ └── settings/ # Qtile settings modules - organized configuration modules for themes, keybinds, etc. -│ │ │ │ ├── alacritty/ # Terminal emulator config - Alacritty terminal appearance and behavior settings -│ │ │ │ │ └── alacritty.yml # Alacritty configuration - colors, fonts, and terminal behavior -│ │ │ │ ├── rofi/ # Application launcher config - Rofi launcher themes and behavior -│ │ │ │ │ ├── config.rasi # Rofi configuration - launcher behavior and appearance -│ │ │ │ │ └── themes/ # Rofi themes - custom color schemes and layouts for launcher -│ │ │ │ ├── dunst/ # Notification daemon config - system notification appearance and behavior -│ │ │ │ ├── picom/ # Compositor config - window transparency and effects settings -│ │ │ │ ├── gtk-3.0/ # GTK3 theme config - GTK application theming and appearance -│ │ │ │ ├── fontconfig/ # Font configuration - custom font settings and rendering preferences -│ │ │ │ └── autostart/ # Auto-start applications - programs launched automatically on desktop start -│ │ │ │ └── *.desktop # Desktop entries - application autostart definitions -│ │ │ └── .local/ # User local data - user-specific data and applications -│ │ │ ├── bin/ # User executables - user-specific executable scripts and programs -│ │ │ └── share/ # User shared data - user-specific shared files and data -│ │ │ ├── applications/ # User desktop entries - custom application launchers -│ │ │ └── fonts/ # User fonts - user-installed fonts for personal use -│ │ ├── systemd/ # Systemd configuration - system service and boot management -│ │ │ ├── system/ # System services - system-wide service definitions and configurations -│ │ │ │ ├── *.service # Service files - individual service definitions (daemons, one-shot tasks) -│ │ │ │ ├── *.timer # Timer services - scheduled tasks and cron-like functionality -│ │ │ │ ├── *.target # Target services - service grouping and system states -│ │ │ │ ├── *.target.wants/ # Service dependencies - services required by specific targets -│ │ │ │ ├── multi-user.target.wants/ # Multi-user services - services for multi-user system state -│ │ │ │ ├── graphical.target.wants/ # Graphical services - services for graphical desktop environment -│ │ │ │ └── *@.service.d/ # Service overrides - modifications to existing service definitions -│ │ │ ├── network/ # Network configuration - systemd-networkd network interface settings -│ │ │ │ ├── *.network # Network interface configs - DHCP, static IP, and interface settings -│ │ │ │ └── *.link # Link configuration - hardware interface naming and properties -│ │ │ ├── resolved.conf.d/ # DNS resolver config - systemd-resolved DNS and domain settings -│ │ │ ├── journald.conf.d/ # Journal configuration - system logging behavior and retention -│ │ │ └── logind.conf.d/ # Login manager config - user session and power management -│ │ ├── pacman.d/ # Pacman configuration - package manager settings and hooks -│ │ │ ├── hooks/ # Pacman hooks - scripts triggered during package operations -│ │ │ │ ├── *.hook # Hook definitions - automated tasks during package install/remove -│ │ │ │ ├── update-desktop-database.hook # Desktop database updates - refresh application menus -│ │ │ │ └── uncomment-mirrors.hook # Mirror management - automatically enable package mirrors -│ │ │ ├── chaotic-mirrorlist # AUR mirror list - pre-compiled AUR package repository mirrors -│ │ │ └── mirrorlist # Official mirrors - Arch Linux package repository mirrors -│ │ ├── ssh/ # SSH configuration - secure shell server and client settings -│ │ │ ├── sshd_config # SSH daemon config - server behavior, security, and access control -│ │ │ └── sshd_config.d/ # SSH config overrides - modular SSH server configuration -│ │ │ └── 10-archiso.conf # Archiso SSH settings - live environment SSH configuration -│ │ ├── sudoers.d/ # Sudo configuration - privilege escalation rules and permissions -│ │ │ └── g_wheel # Wheel group sudo - allows wheel group members to use sudo -│ │ ├── mkinitcpio.conf.d/ # Initial ramdisk config - boot-time kernel module and filesystem settings -│ │ │ └── archiso.conf # Archiso initramfs config - live environment boot configuration -│ │ ├── mkinitcpio.d/ # Kernel presets - predefined kernel configurations for different scenarios -│ │ │ └── linux.preset # Linux kernel preset - default kernel build settings -│ │ ├── modprobe.d/ # Kernel module config - kernel module loading and parameter settings -│ │ │ ├── blacklist.conf # Module blacklist - prevents loading of problematic modules -│ │ │ └── broadcom-wl.conf # Broadcom WiFi config - specific WiFi driver configuration -│ │ ├── sddm.conf.d/ # Display manager config - login screen and session management -│ │ │ └── kde_settings.conf # SDDM settings - display manager theme and behavior -│ │ └── xdg/ # XDG base directories - desktop environment integration settings -│ │ ├── autostart/ # System autostart - applications launched for all users -│ │ └── user-dirs.defaults # Default user directories - standard folder structure for user homes -│ ├── usr/ # User programs and data - system programs and shared data -│ │ ├── local/ # Local installations - locally compiled or custom software -│ │ │ ├── bin/ # Custom executables - custom scripts and programs for system -│ │ │ │ ├── your-installer # Main installation script - primary system installer program -│ │ │ │ ├── choose-mirror # Mirror selection utility - tool for selecting package repository mirrors -│ │ │ │ ├── welcome-app # Welcome application - first-run application for new users -│ │ │ │ ├── kyosinstall # KyOS installer - KyOS-specific installation script -│ │ │ │ ├── kyos-welcome # KyOS welcome app - KyOS-specific welcome application -│ │ │ │ ├── Installation_guide # Installation guide - interactive installation documentation -│ │ │ │ ├── livecd-sound # Live CD audio setup - configures audio for live environment -│ │ │ │ └── custom-tools # Other custom utilities - additional system utilities and tools -│ │ │ └── share/ # Shared data files - shared resources for local programs -│ │ │ ├── applications/ # Desktop entries - application launchers and menu entries -│ │ │ ├── backgrounds/ # Wallpapers - custom wallpaper images for desktop -│ │ │ ├── icons/ # Custom icons - icon themes and individual icon files -│ │ │ ├── themes/ # Desktop themes - complete theme packages for desktop environment -│ │ │ └── fonts/ # Custom fonts - additional font files for system -│ │ └── share/ # System shared data - system-wide shared resources -│ │ ├── backgrounds/ # System wallpapers - default wallpaper images -│ │ ├── grub/ # GRUB themes - boot loader themes and graphics -│ │ │ └── themes/ # GRUB theme files - custom boot loader appearance -│ │ ├── plymouth/ # Boot splash themes - boot animation and splash screens -│ │ └── pixmaps/ # System icons - system-wide icon files and graphics -│ ├── opt/ # Optional applications - third-party software and large applications -│ │ ├── your-welcome/ # Welcome application files - complete welcome application package -│ │ │ ├── your-welcome/ # Welcome app source - source code and resources for welcome app -│ │ │ │ ├── main.py # Welcome app main - primary application entry point -│ │ │ │ ├── ui/ # User interface - GUI components and layouts -│ │ │ │ ├── resources/ # App resources - images, icons, and data files -│ │ │ │ └── config/ # App configuration - application-specific settings -│ │ │ └── install.sh # Welcome app installer - installation script for welcome application -│ │ └── custom-apps/ # Custom applications - other custom software packages -│ └── root/ # Root user home and configs - root user settings and package lists -│ ├── .automated_script.sh # Automated installation script - handles unattended installations -│ ├── .gnupg/ # GPG configuration - GPG keys and encryption settings for root -│ ├── .bashrc # Root bash config - bash shell settings for root user -│ ├── .xinitrc # X11 initialization - X Window System startup script -│ ├── pkgs-base # Base package list - essential system packages for installation -│ ├── pkgs-desktop # Desktop environment packages - GUI components and window manager -│ ├── pkgs-btrfs # Btrfs-specific packages - filesystem utilities for Btrfs support -│ ├── pkgs-applications # Application packages - user applications and productivity software -│ └── pkgs-aur # AUR package list - Arch User Repository packages -├── efiboot/ # UEFI boot configuration - UEFI firmware boot settings and entries -│ └── loader/ # Systemd-boot configuration - UEFI boot loader configuration -│ ├── loader.conf # Boot loader settings - timeout, default entry, and boot options -│ └── entries/ # Boot entries - individual boot menu entries -│ ├── 01-*.conf # Primary boot entry - main system boot configuration -│ ├── 02-*.conf # Accessibility boot entry - boot with accessibility features enabled -│ └── 03-*.conf # Memory test entry - boot into memory testing utility -├── grub/ # GRUB boot configuration - GRUB boot loader for BIOS and UEFI -│ ├── grub.cfg # GRUB menu configuration - boot menu entries and kernel parameters -│ └── loopback.cfg # Loopback boot support - enables booting from ISO files -└── syslinux/ # BIOS boot configuration - legacy BIOS boot loader configuration - ├── syslinux.cfg # Main syslinux config - primary BIOS boot configuration - ├── archiso_*.cfg # Boot menu entries - specific boot menu configurations - │ ├── archiso_head.cfg # Menu header - boot menu title and graphics - │ ├── archiso_pxe.cfg # PXE boot config - network boot configuration - │ ├── archiso_sys.cfg # System boot config - standard system boot entries - │ └── archiso_tail.cfg # Menu footer - boot menu closing and options - └── splash.png # Boot splash image - graphical boot screen background +AlvinArch/ +├── profiledef.sh # ISO metadata, compression, boot modes, file permissions +├── packages.x86_64 # ~400 live-environment packages (Hyprland, end-4, dev tools) +├── bootstrap_packages # Minimal build-time packages (base, arch-install-scripts) +├── pacman.conf # Repos: cachyos → core → extra → multilib → chaotic-aur → local-aur +├── airootfs/ # Root filesystem overlay (copied into live ISO) +│ ├── etc/ +│ │ ├── os-release # NAME="Alvin Arch Linux", ID=arch +│ │ ├── hostname # Default hostname: archiso +│ │ ├── motd # Welcome text with install instructions and color bar +│ │ ├── locale.conf # LANG=en_AU.UTF-8 +│ │ ├── locale.gen # Locale generation file +│ │ ├── localtime → ../usr/share/zoneinfo/... # Timezone symlink +│ │ ├── resolv.conf # DNS resolver config +│ │ ├── passwd # System user accounts +│ │ ├── shadow # Password hashes (mode 400) +│ │ ├── clamav/ # ClamAV antivirus config (certs, clamd, freshclam, milter) +│ │ ├── skel/ # Home directory template for new users +│ │ │ ├── .config/ +│ │ │ │ ├── bat/ # bat + Catppuccin Macchiato theme +│ │ │ │ ├── fish/ # Fish shell config (~20 files, nvm, fisher, hyprland helper) +│ │ │ │ ├── nvim/ # LazyVim setup (init.lua, plugins/, config/) +│ │ │ │ ├── hypr/custom/ # Hyprland dotfiles (keybinds, rules, execs, env, general, scripts) +│ │ │ │ └── starship.toml # Starship cross-shell prompt +│ │ │ ├── .zshrc # Zsh config (oh-my-zsh compatible) +│ │ │ └── .fzf.zsh # Fzf shell integration +│ │ ├── systemd/ +│ │ │ ├── system/ # Service files and enablement symlinks +│ │ │ │ ├── choose-mirror.service # Auto mirror selection +│ │ │ │ ├── pacman-init.service # Keyring initialization +│ │ │ │ ├── livecd-alsa-unmuter.service # Unmute ALSA on boot +│ │ │ │ ├── livecd-talk.service # LiveCD talk helper +│ │ │ │ ├── multi-user.target.wants/ # Enabled services (iwd, NetworkManager, sshd, vboxservice, +│ │ │ │ │ # hv_kvp/vss/fcopy, vmtoolsd, ModemManager, etc.) +│ │ │ │ ├── sysinit.target.wants/ # systemd-timesyncd, systemd-time-wait-sync +│ │ │ │ ├── sockets.target.wants/ # systemd-networkd, pcscd +│ │ │ │ ├── network-online.target.wants/ # systemd-networkd-wait-online +│ │ │ │ └── sound.target.wants/ # livecd-alsa-unmuter +│ │ │ ├── networkd.conf.d/ # IPv6 privacy extensions +│ │ │ ├── resolved.conf.d/ # systemd-resolved config +│ │ │ ├── journald.conf.d/ # Volatile journal storage +│ │ │ └── logind.conf.d/ # Do-not-suspend policy +│ │ ├── pacman.d/ +│ │ │ ├── hooks/ +│ │ │ │ ├── uncomment-mirrors.hook # Enable mirrors after install +│ │ │ │ └── zzzz99-remove-custom-hooks-from-airootfs.hook +│ │ │ ├── chaotic-mirrorlist # Chaotic AUR mirrors +│ │ │ └── cachyos-mirrorlist # CachyOS mirrors +│ │ ├── ssh/sshd_config.d/ # SSH live-environment config (10-archiso.conf) +│ │ ├── modprobe.d/ # broadcom-wl.conf (Broadcom WiFi driver) +│ │ └── mkinitcpio.conf.d/ # archiso initramfs config +│ ├── usr/ +│ │ ├── lib/os-release # usr-merge os-release +│ │ ├── local/bin/ # choose-mirror, Installation_guide, livecd-sound +│ │ ├── local/share/livecd-sound/ # ALSA config (asound.conf.in) +│ │ └── share/pacman/keyrings/ # CachyOS GPG keyring + trust data +│ └── root/ +│ ├── .automated_script.sh # Automated install entry point +│ ├── .zlogin # Zsh login hook +│ ├── .gnupg/scdaemon.conf # GPG smartcard config +│ ├── .live-pacman.conf # Pacman config for live session +│ └── customize_airootfs.sh # Build-time chroot script (oh-my-zsh, lazy.nvim, plugins) +├── localrepo/ # Pre-built AUR packages (indexed as local-aur repo) +│ ├── build-end4-deps.sh # Non-interactive AUR builder for end-4 dependencies +│ ├── update.sh # Regenerates repo DB + syncs names to packages.x86_64 +│ ├── end4-pkgbuilds/ # PKGBUILDs: quickshell-git, microtex-git, bibata-modern-classic-bin +│ ├── *.pkg.tar.zst # Pre-built packages (illogical-impulse-*, wallust, grub-customizer, +│ │ # snapd, upscayl, meshy-git, pacserve, etc.) +│ └── local-aur.db{,.tar.gz} # Repo database files +├── efiboot/ # UEFI boot (systemd-boot) +│ └── loader/ +│ ├── loader.conf +│ └── entries/ +│ ├── 01-archiso-linux.conf +│ ├── 02-archiso-speech-linux.conf +│ └── 03-archiso-memtest86+x64.conf +├── grub/ # GRUB boot (BIOS + UEFI) +│ ├── grub.cfg +│ └── loopback.cfg +└── syslinux/ # BIOS boot (syslinux) + ├── syslinux.cfg + ├── archiso_head.cfg + ├── archiso_pxe-linux.cfg + ├── archiso_sys.cfg + ├── archiso_sys-linux.cfg + ├── archiso_tail.cfg + └── splash.png ``` -## File Use Cases and Purposes +## Core Configuration Files -### Core Configuration Files +### **profiledef.sh** -#### **profiledef.sh** +Defines the entire ISO build. Key settings: `iso_label="AlvinArch_..."`, `bootmodes` (BIOS syslinux + UEFI systemd-boot), `airootfs_image_type="squashfs"` with xz compression. Edit first to change branding or compression. -- **Purpose**: Defines the entire ISO build configuration -- **Use Case**: Sets ISO metadata (name, version, publisher), build modes, compression settings, and file permissions -- **When to Edit**: Always customize this first with your branding and build preferences -- **Key Settings**: `iso_name`, `iso_publisher`, `iso_application`, `file_permissions` +### **packages.x86_64** -#### **packages.x86_64** +The main package list (~400 packages). Packages from allowed repos (`cachyos`, `extra`, `multilib`, `chaotic-aur`) are installed directly. Packages in `localrepo/*.pkg.tar.zst` are pulled from the `[local-aur]` repo. Keep sorted alphabetically. -- **Purpose**: Packages installed in the live environment -- **Use Case**: Essential packages for the ISO to function (networking, hardware support, installation tools) -- **When to Edit**: Add packages needed for live environment functionality, but keep minimal for size -- **Examples**: `base`, `linux-firmware`, `networkmanager`, `arch-install-scripts` +### **bootstrap_packages** -#### **bootstrap_packages.x86_64** +Minimal packages for the mkarchiso bootstrap phase: `base` and `arch-install-scripts`. -- **Purpose**: Minimal packages needed during ISO build process -- **Use Case**: Packages required by mkarchiso to create the ISO -- **When to Edit**: Rarely changed unless you need specific build tools -- **Default**: `arch-install-scripts`, `base` +### **pacman.conf** -#### **pacman.conf** - -- **Purpose**: Package manager configuration for both build and live environment -- **Use Case**: Defines repositories, signing requirements, and package sources -- **When to Edit**: Add custom repositories, AUR sources, or modify package verification -- **Key Sections**: `[chaotic-aur]`, `[your-custom-repo]`, signature levels - -### System Configuration Files (airootfs/etc/) - -#### **os-release** - -- **Purpose**: Operating system identification and branding -- **Use Case**: Defines distro name, version, URLs shown in system info -- **When to Edit**: Essential for branding - change `NAME`, `ID`, `HOME_URL`, etc. -- **Impact**: Affects system info commands, desktop environment about dialogs - -#### **motd (Message of the Day)** - -- **Purpose**: Welcome message displayed on terminal login -- **Use Case**: Provides instructions and information to live environment users -- **When to Edit**: Customize with your installation instructions and support info -- **Best Practice**: Include installation command, documentation links, network setup help - -#### **hostname** - -- **Purpose**: Default system hostname for live environment -- **Use Case**: Sets the computer name shown in network and terminal -- **When to Edit**: Change from default to match your distro branding -- **Example**: `yourcustomlinux` instead of `archiso` - -#### **locale.conf** - -- **Purpose**: System language and regional settings -- **Use Case**: Defines default language, character encoding, date/time formats -- **When to Edit**: Set default locale for your target audience -- **Common Values**: `LANG=en_US.UTF-8` for US English, `LANG=de_DE.UTF-8` for German - -#### **bash.bashrc** - -- **Purpose**: Global bash shell configuration for all users -- **Use Case**: System-wide shell settings, aliases, and environment variables -- **When to Edit**: Add custom aliases, modify PATH, set environment variables -- **Examples**: Custom aliases like `ll='ls -la'`, custom PATH additions - -#### **doas.conf** - -- **Purpose**: Privilege escalation configuration (alternative to sudo) -- **Use Case**: Defines which users can run commands as root -- **When to Edit**: Modify privilege rules or switch to sudo configuration -- **DTOS Example**: `permit persist setenv {PATH=...} :wheel` (allows wheel group users) - -#### **group & passwd** - -- **Purpose**: System user and group definitions -- **Use Case**: Defines system accounts and their IDs -- **When to Edit**: Add system users or modify group memberships -- **Security Note**: Contains sensitive system account information - -#### **shadow & gshadow** - -- **Purpose**: Encrypted password storage -- **Use Case**: Stores password hashes and group passwords securely -- **When to Edit**: Set default passwords for live environment users -- **Security**: Permissions must be 400 (read-only for root) - -### User Configuration Templates (airootfs/etc/skel/) - -#### **.config/qtile/config.py** - -- **Purpose**: Qtile window manager configuration template -- **Use Case**: Default Qtile setup for new users (keybindings, layouts, themes) -- **When to Edit**: Customize window manager behavior, add custom keybindings -- **Key Elements**: Key bindings, layouts, bar configuration, autostart applications - -#### **.config/alacritty/alacritty.yml** - -- **Purpose**: Terminal emulator configuration template -- **Use Case**: Default terminal appearance and behavior -- **When to Edit**: Customize fonts, colors, window settings -- **Popular Changes**: Font family, color scheme, window padding, opacity - -#### **.config/rofi/config.rasi** - -- **Purpose**: Application launcher configuration -- **Use Case**: Defines launcher appearance and behavior -- **When to Edit**: Customize launcher theme, fonts, behavior -- **Customization**: Themes, fonts, window positioning, keyboard shortcuts - -### System Services (airootfs/etc/systemd/system/) - -#### **choose-mirror.service** - -- **Purpose**: Automatic mirror selection service -- **Use Case**: Helps users select fastest package repository mirrors -- **When to Edit**: Modify mirror selection logic or add custom mirrors -- **Activation**: Triggered by `mirror` kernel parameter - -#### **display-manager.service** - -- **Purpose**: Symlink to display manager (login screen) -- **Use Case**: Defines which display manager to use (sddm, gdm, lightdm) -- **When to Edit**: Change display manager or modify startup behavior -- **DTOS Example**: Links to `sddm.service` - -#### **pacman-init.service** - -- **Purpose**: Initializes package manager keyring -- **Use Case**: Sets up GPG keys for package verification -- **When to Edit**: Modify keyring initialization or add custom keys -- **Critical**: Must complete before package installation - -### Network Configuration (airootfs/etc/systemd/network/) - -#### **20-ethernet.network** - -- **Purpose**: Ethernet interface configuration -- **Use Case**: Automatic DHCP configuration for wired connections -- **When to Edit**: Modify network settings or add static IP configurations -- **Default**: DHCP enabled with privacy extensions - -#### **20-wlan.network** - -- **Purpose**: Wireless interface configuration -- **Use Case**: Basic wireless network setup -- **When to Edit**: Add wireless-specific settings or security configurations -- **Note**: Requires additional tools like `iwd` or `wpa_supplicant` - -### Package Management (airootfs/etc/pacman.d/) - -#### **hooks/uncomment-mirrors.hook** - -- **Purpose**: Automatically enables package repository mirrors -- **Use Case**: Ensures package mirrors are available after installation -- **When to Edit**: Modify mirror management or add custom mirror logic -- **Trigger**: Runs during package operations - -#### **hooks/waypaper.hook** - -- **Purpose**: Updates wallpaper database after package changes -- **Use Case**: Ensures wallpaper applications see new wallpapers -- **When to Edit**: Add similar hooks for other applications -- **Pattern**: Update application databases after package installation - -#### **chaotic-mirrorlist** - -- **Purpose**: Mirror list for Chaotic AUR repository -- **Use Case**: Provides pre-compiled AUR packages -- **When to Edit**: Add or modify AUR package sources -- **Alternative**: Replace with custom repository mirrors - -### Installation Scripts (airootfs/usr/local/bin/) - -#### **dtosinstall** - -- **Purpose**: Main system installation script -- **Use Case**: Guides users through system installation process -- **When to Edit**: Customize installation options, add features, modify UI -- **Key Features**: Disk partitioning, package installation, user creation, bootloader setup - -#### **choose-mirror** - -- **Purpose**: Repository mirror selection utility -- **Use Case**: Helps users select fastest package mirrors -- **When to Edit**: Add custom mirrors or modify selection logic -- **Integration**: Used by installation scripts and services - -#### **dtos-welcome** - -- **Purpose**: Welcome application for new users -- **Use Case**: Provides information and quick actions for live environment -- **When to Edit**: Customize welcome message, add custom actions -- **UI**: Can be GUI or terminal-based - -#### **Installation_guide** - -- **Purpose**: Interactive installation documentation -- **Use Case**: Provides step-by-step installation help -- **When to Edit**: Update with your specific installation procedures -- **Format**: Usually opens documentation in browser or terminal - -### Package Lists (airootfs/root/) - -#### **pkgs-base** - -- **Purpose**: Essential system packages for installation -- **Use Case**: Packages installed on every system (bootloader, kernel, basic tools) -- **When to Edit**: Add/remove essential system packages -- **Examples**: `base-devel`, `grub`, `networkmanager`, `yay` - -#### **pkgs-qtile** - -- **Purpose**: Desktop environment packages -- **Use Case**: Packages for complete desktop experience -- **When to Edit**: Customize desktop environment, add/remove applications -- **Examples**: `qtile`, `alacritty`, `rofi`, `firefox` - -#### **pkgs-btrfs** - -- **Purpose**: Btrfs filesystem-specific packages -- **Use Case**: Additional tools for Btrfs filesystem support -- **When to Edit**: Modify filesystem support packages -- **Examples**: `btrfs-progs`, `snapper`, `grub-btrfs` - -#### **pkgs-applications** - -- **Purpose**: User applications and productivity software -- **Use Case**: Software that users typically want installed -- **When to Edit**: Customize default application selection -- **Examples**: `firefox`, `libreoffice`, `gimp`, `code` - -### Boot Configuration - -#### **efiboot/loader/loader.conf** - -- **Purpose**: UEFI boot loader configuration -- **Use Case**: Defines boot timeout, default entry, and boot behavior -- **When to Edit**: Customize boot experience for UEFI systems -- **Settings**: `timeout`, `default`, `editor` (enable/disable boot parameter editing) - -#### **efiboot/loader/entries/*.conf** - -- **Purpose**: Individual boot menu entries -- **Use Case**: Defines specific boot options (normal, accessibility, memtest) -- **When to Edit**: Customize boot options, kernel parameters, or entry names -- **Parameters**: `title`, `linux`, `initrd`, `options` - -#### **grub/grub.cfg** - -- **Purpose**: GRUB boot loader configuration -- **Use Case**: Defines boot menu for BIOS and UEFI systems -- **When to Edit**: Customize boot menu appearance and options -- **Features**: Multiple boot entries, kernel parameters, theme support - -#### **syslinux/syslinux.cfg** - -- **Purpose**: BIOS boot loader configuration -- **Use Case**: Legacy BIOS boot support -- **When to Edit**: Customize BIOS boot experience -- **Elements**: Boot menu, splash screen, timeout settings +Defines the repo order: **cachyos → core → extra → multilib → chaotic-aur → local-aur**. The `[local-aur]` repo points to the local `localrepo/` directory for pre-built AUR packages. --- -## VirtualBox Compatibility +## User Configuration (skel/) -KyOS includes intelligent VirtualBox detection and optimization to ensure a smooth desktop experience in virtualized environments. The system automatically adjusts compositor settings, application startup, and visual effects based on the detected virtualization platform. +Dotfiles in `airootfs/etc/skel/` are copied into every new user's home directory on the live ISO. -### Automatic Detection +### **.config/bat/** -The system uses `systemd-detect-virt` to identify VirtualBox and applies appropriate optimizations: +[bat](https://github.com/sharkdp/bat) with a Catppuccin Macchiato color theme. Provides `bat` as a `cat` replacement. + +### **.config/fish/** + +Fish shell configuration (~20 files). Includes nvm integration, fisher plugin manager, Hyprland auto-detection (`auto-Hypr.fish`), frozen theme/keybindings, and custom functions (`edit`, `update`, `lzd`). + +### **.config/nvim/** + +Full LazyVim setup powered by lazy.nvim. Includes `init.lua`, plugin specs for Obsidian, Arduino, and Harper (grammar), plus standard LazyVim config/options/keymaps/autocmds. + +### **.config/hypr/custom/** + +Hyprland dotfiles from [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland): + +| File | Purpose | +|------|---------| +| `keybinds.lua` | Window manager keybindings | +| `general.lua` | Appearance, gaps, border settings | +| `rules.lua` | Window rules (floating, size, class matching) | +| `execs.lua` | Autostart commands | +| `env.lua` | Environment variables | +| `variables.lua` | Shared variable definitions | +| `scripts/` | Helper scripts (video wallpaper restore, paste-as-type) | + +### **.config/starship.toml** + +Cross-shell prompt config for [Starship](https://starship.rs/). Works with both Fish and Zsh. + +### **.zshrc / .fzf.zsh** + +Zsh configuration adapted for oh-my-zsh (installed by `customize_airootfs.sh`) and fzf shell integration. + +--- + +## System Services & Networking + +### Services (enabled via symlinks) + +| Service | Purpose | +|---------|---------| +| `iwd` | WiFi management | +| `NetworkManager` | Network connections | +| `sshd` | SSH access to live environment | +| `vboxservice` | VirtualBox guest additions | +| `hv_kvp_daemon`, `hv_vss_daemon`, `hv_fcopy_daemon` | Hyper-V integration | +| `vmtoolsd`, `vmware-vmblock-fuse` | VMware guest tools | +| `ModemManager` | Mobile broadband | +| `pacman-init` | Initializes GPG keyring before package operations | +| `choose-mirror` | Auto mirror selection (triggered by `mirror` kernel param) | +| `livecd-alsa-unmuter` | Unmutes audio on live boot | + +### Network Config + +- **systemd-networkd** with IPv6 privacy extensions enabled +- **systemd-resolved** for DNS +- DHCP auto-configured for wired (ethernet) and wireless (iwd) + +### Other System Config + +- **ClamAV** — Antivirus daemon config included in `airootfs/etc/clamav/` +- **mkinitcpio** — Archiso-specific initramfs config +- **logind** — No-suspend policy for live session +- **journald** — Volatile (in-memory) log storage + +--- + +## Local Repository (localrepo/) + +Pre-built AUR packages that aren't available in any allowed repo. The `local-aur` repo is configured in `pacman.conf` and picked up automatically by mkarchiso. + +### Scripts + +- **`build-end4-deps.sh`** — Non-interactive AUR build for all end-4 (illogical-impulse) dependencies. Run `--quick` to skip large packages. +- **`update.sh`** — Regenerates the repo database and syncs new package names to `packages.x86_64`. + +### end4-pkgbuilds/ + +Custom PKGBUILDs for end-4 metapackages: + +- `quickshell-git` — Quickshell (Qt6/QML shell for Wayland) +- `microtex-git` — LaTeX previewer +- `bibata-modern-classic-bin` — Bibata cursor theme + +### Pre-built Packages + +Packages like `illogical-impulse-quickshell-git`, `illogical-impulse-bibata-modern-classic-bin`, `wallust`, `grub-customizer`, `snapd`, `upscayl-bin`, `meshy-git`, `xwaylandvideobridge`, `pacserve`, etc. + +--- + +## Boot Configuration + +### UEFI — systemd-boot (`efiboot/`) + +Three boot entries: standard Arch Linux, speech/accessibility, and MemTest86+. + +### BIOS — GRUB (`grub/`) + +`grub.cfg` for BIOS/CSM boot, `loopback.cfg` for booting the ISO from a mounted image. + +### BIOS — syslinux (`syslinux/`) + +Legacy BIOS boot with custom splash screen. Includes PXE network boot config. + +--- + +## Build & Test + +### Building the ISO ```bash -# Check if running in VirtualBox -if [ "$(systemd-detect-virt)" = "oracle" ]; then - echo "VirtualBox detected - applying compatibility settings" - # Apply VirtualBox-specific configurations -fi +# Build the ISO (repo root IS the profile directory) +sudo mkarchiso -v -w work -o out/ . + +# Build AUR deps for end-4 (run locally before ISO build if localrepo/ is stale) +./localrepo/build-end4-deps.sh # build all +./localrepo/build-end4-deps.sh --quick # skip large AUR pkgs + +# Refresh localrepo DB after adding/moving .pkg.tar.zst files +./localrepo/update.sh # re-indexes existing packages +./localrepo/update.sh pkg1.pkg.tar.zst # add files, then re-index ``` -### VirtualBox-Optimized Files +### CI Checks (must pass before merge) -#### 1. Qtile Autostart Script (`~/.config/qtile/scripts/autostart.sh`) +- **ShellCheck**: all `.sh` files checked with `shellcheck -x -s bash` +- **yamllint**: all `.yml`/`.yaml` files (relaxed config) +- **packages.x86_64 syntax**: one package per line, no trailing whitespace, `[a-zA-Z0-9._@+\-]+` only +- **Package repo check**: every package in `packages.x86_64` must be resolvable via `pacman -Si` in allowed repos (`cachyos`, `extra`, `multilib`, `chaotic-aur`), OR have a pre-built `.pkg.tar.zst` in `localrepo/`, OR appear in `localrepo/build-end4-deps.sh` -**Features:** - -- Skips picom compositor in VirtualBox (prevents transparency issues) -- Disables problematic applications (eww, volctl) that cause rendering problems -- Maintains essential applications (nm-applet, flameshot, blueman-applet) - -```bash -#!/bin/bash - -export PATH="/home/user/.local/bin:$PATH" - -# Detect if running in VirtualBox -if [ "$(systemd-detect-virt)" = "oracle" ]; then - echo "VirtualBox detected - using compatibility mode" - # Skip picom in VirtualBox -else - # Run picom on real hardware - picom -b & -fi - -# Essential applications that work in VirtualBox -nm-applet & -libinput-gestures-setup restart -flameshot & -blueman-applet & -plank & -dunst & - -# Skip problematic applications in VirtualBox -if [ "$(systemd-detect-virt)" != "oracle" ]; then - eww daemon & - volctl & - mkfifo /tmp/vol-icon && ~/.config/qtile/scripts/vol_icon.sh & -fi -``` - -#### 2. VirtualBox-Safe Picom Configuration (`~/.config/picom.conf`) - -**Features:** - -- Uses stable xrender backend -- Disables transparency and effects -- Prevents visual artifacts and black bars - -```properties -# VirtualBox-compatible picom configuration -backend = "xrender"; -vsync = false; - -# Disable transparency and shadows -shadow = false; -fading = false; -inactive-opacity = 1.0; -active-opacity = 1.0; -frame-opacity = 1.0; -inactive-opacity-override = false; - -# Disable blur and effects -blur-background = false; -corner-radius = 0; - -# VirtualBox-friendly settings -mark-wmwin-focused = true; -mark-ovredir-focused = true; -detect-rounded-corners = false; -detect-client-opacity = false; -detect-transient = false; -detect-client-leader = false; -use-damage = false; - -# Window type settings - disable all effects -wintypes: -{ - tooltip = { fade = false; shadow = false; opacity = 1.0; focus = true; }; - dock = { shadow = false; fade = false; opacity = 1.0; }; - dnd = { shadow = false; fade = false; opacity = 1.0; }; - popup_menu = { opacity = 1.0; fade = false; shadow = false; }; - dropdown_menu = { opacity = 1.0; fade = false; shadow = false; }; -}; -``` - -#### 3. Qtile Bar with VirtualBox Detection (`~/.config/qtile/core/bar.py`) - -**Features:** - -- Detects VirtualBox environment -- Forces solid backgrounds and full opacity -- Prevents transparency-related rendering issues - -```python -import subprocess - -def is_virtualbox(): - try: - result = subprocess.run(['systemd-detect-virt'], capture_output=True, text=True) - return result.stdout.strip() == 'oracle' - except: - return False - -# Adjust settings for VirtualBox compatibility -if is_virtualbox(): - bg_color = color["bg"] - opacity = 1.0 -else: - bg_color = color["bg"] - opacity = 0.8 - -def create_bar(extra_bar=False): - return bar.Bar( - [ - # ...bar widgets... - ], - 30, - margin=[4, 6, 2, 6], - background=bg_color, - opacity=opacity if not is_virtualbox() else 1.0, - ) -``` - -#### 4. VirtualBox Fix Script (`~/.config/qtile/scripts/vbox-fix.sh`) - -**Features:** - -- Manual fix utility for VirtualBox issues -- Kills problematic processes -- Restarts Qtile with proper settings - -```bash -#!/bin/bash -# VirtualBox Qtile Fix Script - -echo "Fixing Qtile for VirtualBox compatibility..." - -# Kill compositor and problematic applications -pkill picom -pkill eww -pkill volctl -echo "Stopped problematic applications" - -# Restart Qtile -qtile cmd-obj -o cmd -f restart -echo "Restarted Qtile" - -# Provide terminal transparency fix instructions -if command -v alacritty &> /dev/null; then - echo "To fix transparent terminal, edit ~/.config/alacritty/alacritty.yml" - echo "Set: window.opacity: 1.0" -fi - -echo "VirtualBox compatibility fixes applied!" -``` - -### Installation Integration - -The KyOS installer automatically detects VirtualBox during installation and applies appropriate configurations: - -```bash -# In kyosinstall script -if systemd-detect-virt | grep -q oracle; then - echo "VirtualBox detected - installing VirtualBox-optimized configs" - - # Install VirtualBox guest additions - arch_chroot "pacman -S --noconfirm virtualbox-guest-utils" - arch_chroot "systemctl enable vboxservice" - - # Apply VirtualBox-specific configurations - cp /usr/share/kyos/vbox-configs/* /mnt/home/$username/.config/ -fi -``` - -### Common VirtualBox Issues and Solutions - -#### Issue: Black Bars or Visual Artifacts - -**Solution:** VirtualBox-optimized picom configuration automatically applied - -#### Issue: Transparent Terminal Text Invisible - -**Solution:** - -1. Edit terminal configuration (e.g., `~/.config/alacritty/alacritty.yml`) -2. Set `window.opacity: 1.0` -3. Restart terminal application - -#### Issue: Desktop Effects Not Working - -**Solution:** Effects are automatically disabled in VirtualBox for stability - -#### Issue: Poor Performance - -**Solution:** - -1. Ensure VirtualBox Guest Additions are installed -2. Allocate sufficient video memory (128MB recommended) -3. Enable 3D acceleration in VirtualBox settings - -### Manual VirtualBox Optimization - -For existing installations, copy these files to fix VirtualBox issues: - -```bash -# Copy VirtualBox-optimized configurations -cp /path/to/kyos-files/autostart.sh ~/.config/qtile/scripts/ -cp /path/to/kyos-files/picom.conf ~/.config/ -cp /path/to/kyos-files/bar.py ~/.config/qtile/core/ -cp /path/to/kyos-files/vbox-fix.sh ~/.config/qtile/scripts/ - -# Make fix script executable -chmod +x ~/.config/qtile/scripts/vbox-fix.sh - -# Run the fix script -~/.config/qtile/scripts/vbox-fix.sh -``` - -### Testing VirtualBox Compatibility - -**Recommended VirtualBox Settings:** +### Recommended VirtualBox Settings (for testing) - RAM: 4GB minimum, 8GB recommended - Video Memory: 128MB - 3D Acceleration: Enabled -- 2D Video Acceleration: Enabled - Storage: 40GB minimum -**Test Checklist:** - -- [ ] Desktop loads without black bars -- [ ] Terminal text is visible -- [ ] Window decorations render properly -- [ ] Basic applications launch successfully -- [ ] Network connectivity works -- [ ] Audio functions properly -- [ ] File manager operates correctly +Guest additions (`vboxservice`), Hyper-V (`hv_*`), and VMware (`vmtoolsd`) tools are all auto-enabled in the live environment. --- -## KyOS Rebranding Process +## Planned Additions -This section documents the complete rebranding process from DTOS to KyOS, including all file changes, script updates, and configuration modifications. +The following dotfiles are not yet included but are planned for future versions: -### Overview of Changes - -**Complete Rebranding:** - -- All user-facing text changed from DTOS to KyOS -- Boot loader messages updated to KyOS -- Installation scripts renamed and updated -- Welcome applications rebranded -- Configuration paths updated -- Default credentials changed to KyOS defaults - -**Package Management:** - -- Removed all DTOS-specific packages -- Added user-specified packages from packages.txt -- Maintained compatibility with DTOS repositories where needed -- Optimized package conflicts (pipewire-jack vs jack2) - -**VirtualBox Compatibility:** - -- Added automatic VirtualBox detection -- Implemented VirtualBox-specific configurations -- Created compatibility fixes for common issues - -### Rebranding Checklist - -#### Core System Files - -- [ ] `/etc/os-release` - Updated OS name and branding -- [ ] `/etc/motd` - Updated welcome message -- [ ] `/etc/hostname` - Changed default hostname to kyos-pc -- [ ] Boot loader configurations (GRUB, syslinux, systemd-boot) -- [ ] Installation scripts renamed (dtosinstall → kyosinstall) - -#### User Interface Elements - -- [x] Welcome application branding -- [x] Installer prompts and messages -- [x] Desktop environment themes -- [x] Wallpapers and branding graphics -- [x] Application launcher entries - -#### Configuration Paths - -- [x] Config directory references -- [x] Script path updates -- [x] Theme and background paths -- [x] User profile templates - -#### Package Lists - -- [x] Removed DTOS packages from pkgs-base -- [x] Removed DTOS packages from pkgs-qtile -- [x] Added user-specified packages avoiding duplicates -- [x] Excluded Wayland-specific packages -- [x] Maintained essential system packages - -#### Scripts and Executables - -- [x] Renamed installation scripts -- [x] Updated script internal references -- [x] Changed default usernames and passwords -- [x] Updated variable names and functions - -### File Mapping - -#### Renamed Files - -``` -Old Location New Location -/usr/local/bin/dtosinstall → /usr/local/bin/kyosinstall -/usr/local/bin/dtosinstall-auto → /usr/local/bin/kyosinstall-auto -/usr/local/bin/dtosinstall-tui → /usr/local/bin/kyosinstall-tui -/opt/dtos-welcome/ → /opt/kyos-welcome/ -``` - -#### Updated Content Files - -``` -File Change -/etc/os-release OS name and branding -/etc/motd Welcome message -/etc/hostname Default hostname -/grub/grub.cfg Boot menu entries -/syslinux/*.cfg Boot menu entries -/efiboot/loader/entries/*.conf Boot entries -airootfs/root/pkgs-* Package lists -``` - -### Script Updates - -#### Installation Scripts - -**kyosinstall** (formerly dtosinstall): - -- Updated all prompts and messages to KyOS -- Changed default username to 'kyos' -- Changed default password to 'kyos123' -- Changed default hostname to 'kyos-pc' -- Added VirtualBox detection and optimization -- Improved error handling and package management -- Enhanced chaotic-aur repository setup - -**kyosinstall-tui** (formerly dtosinstall-tui): - -- Updated TUI interface branding -- Improved user input validation -- Added support for custom username/password/hostname -- Enhanced package installation error handling - -**kyosinstall-auto** (formerly dtosinstall-auto): - -- Automated installation with KyOS defaults -- VirtualBox optimization integration -- Improved post-installation configuration - -### Package Management Changes - -#### Removed Packages - -All DTOS-specific packages were removed: - -``` -dtos-* # All DTOS branded packages -dtos-core-repo # DTOS repository configuration -dtos-welcome # DTOS welcome application -``` - -#### Added Packages - -User-specified packages from packages.txt were added: - -``` -# Selected packages avoiding duplicates and Wayland conflicts -# See packages.txt for complete list -``` - -#### Conflict Resolution - -**pipewire-jack vs jack2:** - -- Removed conflicting audio packages -- Standardized on pipewire-jack -- Added explicit package removal in installer - -**AUR Package Handling:** - -- Improved chaotic-aur repository setup -- Added fallback mirrors for reliability -- Enhanced keyring management - -### VirtualBox Integration - -#### Automatic Detection - -```bash -# Detect VirtualBox environment -if [ "$(systemd-detect-virt)" = "oracle" ]; then - # Apply VirtualBox-specific configurations -fi -``` - -#### Optimized Configurations - -- **Autostart Script**: Skips problematic applications in VirtualBox -- **Picom Config**: Uses stable backend with disabled effects -- **Qtile Bar**: Forces solid backgrounds and full opacity -- **Fix Script**: Manual utility for troubleshooting - -### Testing and Validation - -#### Installation Testing - -- [x] Automated installation works correctly -- [x] TUI installation accepts user input -- [x] User credentials are set properly -- [x] Hostname configuration works -- [x] Package installation completes successfully - -#### VirtualBox Testing - -- [x] Desktop loads without visual artifacts -- [x] Terminal text is visible -- [x] Applications launch successfully -- [x] Network connectivity functions -- [x] Audio works properly - -#### Compatibility Testing - -- [x] Works on real hardware -- [x] Functions in VirtualBox -- [x] Compatible with different VM configurations -- [x] Handles various disk configurations - -### Maintenance and Updates - -#### Ongoing Tasks - -- Monitor package conflicts -- Update VirtualBox compatibility as needed -- Maintain installer script functionality -- Update documentation and guides - -#### Version Control - -- All changes tracked in git -- Separate branches for major updates -- Tagged releases for stable versions - -### Distribution Preparation - -#### ISO Building - -```bash -# Build KyOS ISO -cd /path/to/kyos-iso/releng -sudo mkarchiso -v -w /tmp/kyos-work -o /tmp/kyos-out . -``` - -#### Testing Checklist - -- [ ] ISO boots successfully -- [ ] Live environment functions properly -- [ ] Installation completes without errors -- [ ] Installed system boots correctly -- [ ] VirtualBox compatibility works -- [ ] All KyOS branding appears correctly +| Component | Status | Notes | +|-----------|--------|-------| +| **Alacritty** terminal config | 🚧 Planned | Catppuccin Macchiato theme to match bat | +| **GTK 3.0/4.0** theme config | 🚧 Planned | Consistent theming across GTK apps | +| **Fontconfig** custom settings | 🚧 Planned | Font rendering and fallback rules | +| **Dunst** notification daemon | 🚧 Planned | Notification appearance and behavior | --- -## Conclusion +## Troubleshooting -This comprehensive guide provides everything needed to create KyOS - a professional custom Arch Linux ISO distribution with complete rebranding, VirtualBox optimization, and modern package management. The modular approach allows for easy customization while maintaining compatibility with standard Arch tooling. +### ISO won't boot -### Key Takeaways +- Verify the ISO was built with `sudo mkarchiso` (not as a regular user) +- Check that UEFI or BIOS/CSM is correctly set in VM firmware settings +- For Ventoy: use the `.iso` directly, don't extract -1. **Complete Rebranding**: Successfully transformed DTOS into KyOS with comprehensive branding updates -2. **VirtualBox Compatibility**: Intelligent detection and optimization for virtualized environments -3. **Package Management**: Advanced conflict resolution and AUR integration -4. **Installation System**: Robust TUI and automated installers with user customization -5. **Maintenance**: Ongoing update process and compatibility testing +### No network in live environment -### KyOS Features +- `iwd` handles WiFi — run `iwctl` to connect manually if NetworkManager doesn't detect networks +- Ethernet via systemd-networkd with DHCP should work automatically -- **Intelligent Environment Detection**: Automatic VirtualBox optimization -- **User-Friendly Installation**: TUI installer with custom username/password/hostname support -- **Optimized Package Selection**: Curated package lists avoiding conflicts -- **Professional Branding**: Complete visual and textual rebranding -- **Robust Error Handling**: Advanced installation error recovery -- **Modern Desktop**: Qtile window manager optimized for both hardware and VMs +### Package installation fails during build -### Next Steps +- Run `./localrepo/update.sh` to refresh the localrepo database +- Ensure `localrepo/*.pkg.tar.zst` files are valid and not corrupted +- Check that the package name in `packages.x86_64` matches exactly -1. **Development**: Set up KyOS development environment -2. **Customization**: Further customize based on specific requirements -3. **Testing**: Thorough testing in various environments -4. **Distribution**: Set up distribution infrastructure for KyOS releases -5. **Community**: Establish user support and feedback channels -6. **Updates**: Plan regular updates and security patches +### LazyVim / oh-my-zsh not installed -### Support and Resources - -- **Installation Issues**: Use the comprehensive troubleshooting guides -- **VirtualBox Problems**: Apply the VirtualBox compatibility fixes -- **Package Conflicts**: Follow the conflict resolution procedures -- **Customization**: Reference the rebranding process documentation - -KyOS represents a modern, optimized Arch Linux distribution suitable for both newcomers and experienced users, with particular strength in virtualized environments. +- `customize_airootfs.sh` clones repos at build time — requires network access during `mkarchiso` +- Check build logs for git clone failures --- -*This guide documents the complete transformation from DTOS to KyOS, including all technical implementations, VirtualBox optimizations, and distribution processes. Last updated: June 2025* +## Acknowledgements + +- [Arch Linux](https://archlinux.org/) and the [archiso](https://wiki.archlinux.org/title/Archiso) project +- [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland) for the illogical-impulse Hyprland config +- [LazyVim](https://www.lazyvim.org/) for the Neovim starter config +- [DistroTube](https://www.youtube.com/watch?v=tSGGBbJBgvk&t=1228s) for the archiso walkthrough that inspired this project