alvinlollo/AlvinArch
1
0
Fork 0
Code Issues Pull Requests Actions Releases 2 Activity

Add dotfiles file structure

Browse Source
This commit is contained in:
alvinlollo
2026-09-15 15:37:31 +10:00
parent 7b7658732b
commit 2e51ff9226
1 changed files with 110 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+110 -3
View File
@@ -1,8 +1,32 @@
# Complete Guide to Creating a Custom Arch Linux ISO
DistroTube: https://www.youtube.com/watch?v=tSGGBbJBgvk&t=1228s
DistroTube: <https://www.youtube.com/watch?v=tSGGBbJBgvk&t=1228s>
Dotfiles install file structure:
```bash
AlvinArch/
├── airootfs/
│ ├── etc/skel/
│ │ ├── .config/bat/ # bat + catppuccin theme
│ │ ├── .config/fish/ # 20 files, quickshell guard
│ │ ├── .config/nvim/ # LazyVim (14 files)
│ │ ├── .config/hypr/custom/ # 8 files (kdeconnectd + cursor only)
│ │ ├── .config/starship.toml
│ │ ├── .zshrc # adapted (no hardcoded paths)
│ │ └── .fzf.zsh
│ └── root/customize_airootfs.sh # pre-installs oh-my-zsh, lazy.nvim, plugins
├── localrepo/
│ ├── build-end4-deps.sh # non-interactive AUR build (all deps)
│ ├── end4-pkgbuilds/ # microtex-git, quickshell-git, bibata
│ ├── illogical-impulse-quickshell-git-*.pkg.tar.zst
│ ├── illogical-impulse-bibata-modern-classic-bin-*.pkg.tar.zst
│ └── update.sh # existing, regenerates repo db
└── packages.x86_64 # 420 packages (65+ end-4 deps added)
```
## Table of Contents
1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Directory Structure](#directory-structure)
@@ -26,6 +50,7 @@ DistroTube: https://www.youtube.com/watch?v=tSGGBbJBgvk&t=1228s
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.
### What You'll Learn
- Complete archiso project structure for KyOS
- Advanced package management (official repos + AUR + custom packages)
- Custom configuration deployment and user management
@@ -41,6 +66,7 @@ This guide provides comprehensive documentation for creating KyOS - a custom Arc
## Prerequisites
### Required Tools
```bash
# Install archiso and dependencies
sudo pacman -S archiso git base-devel
@@ -50,6 +76,7 @@ sudo pacman -S arch-install-scripts squashfs-tools
```
### Knowledge Requirements
- Basic Linux system administration
- Understanding of Arch Linux package management
- Shell scripting basics
@@ -60,6 +87,7 @@ sudo pacman -S arch-install-scripts squashfs-tools
## Directory Structure
### Complete Project Layout
```
your-custom-iso/
├── profiledef.sh # Main ISO configuration file - defines ISO metadata, build options, and file permissions
@@ -212,24 +240,28 @@ your-custom-iso/
### Core Configuration Files
#### **profiledef.sh**
- **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**
- **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.x86_64**
- **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**
- **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
@@ -238,48 +270,56 @@ your-custom-iso/
### 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
@@ -288,18 +328,21 @@ your-custom-iso/
### 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
@@ -308,18 +351,21 @@ your-custom-iso/
### 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
@@ -328,12 +374,14 @@ your-custom-iso/
### 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
@@ -342,18 +390,21 @@ your-custom-iso/
### 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
@@ -362,24 +413,28 @@ your-custom-iso/
### 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
@@ -388,24 +443,28 @@ your-custom-iso/
### 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
@@ -414,24 +473,28 @@ your-custom-iso/
### 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
@@ -460,6 +523,7 @@ fi
#### 1. Qtile Autostart Script (`~/.config/qtile/scripts/autostart.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)
@@ -497,6 +561,7 @@ fi
#### 2. VirtualBox-Safe Picom Configuration (`~/.config/picom.conf`)
**Features:**
- Uses stable xrender backend
- Disables transparency and effects
- Prevents visual artifacts and black bars
@@ -541,6 +606,7 @@ wintypes:
#### 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
@@ -578,6 +644,7 @@ def create_bar(extra_bar=False):
#### 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
@@ -628,19 +695,25 @@ 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:**
**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:**
**Solution:**
1. Ensure VirtualBox Guest Additions are installed
2. Allocate sufficient video memory (128MB recommended)
3. Enable 3D acceleration in VirtualBox settings
@@ -666,6 +739,7 @@ chmod +x ~/.config/qtile/scripts/vbox-fix.sh
### Testing VirtualBox Compatibility
**Recommended VirtualBox Settings:**
- RAM: 4GB minimum, 8GB recommended
- Video Memory: 128MB
- 3D Acceleration: Enabled
@@ -673,6 +747,7 @@ chmod +x ~/.config/qtile/scripts/vbox-fix.sh
- Storage: 40GB minimum
**Test Checklist:**
- [ ] Desktop loads without black bars
- [ ] Terminal text is visible
- [ ] Window decorations render properly
@@ -682,6 +757,7 @@ chmod +x ~/.config/qtile/scripts/vbox-fix.sh
- [ ] File manager operates correctly
---
## KyOS Rebranding Process
This section documents the complete rebranding process from DTOS to KyOS, including all file changes, script updates, and configuration modifications.
@@ -689,6 +765,7 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
### 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
@@ -697,12 +774,14 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
- 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
@@ -710,6 +789,7 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
### 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
@@ -717,6 +797,7 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
- [ ] Installation scripts renamed (dtosinstall → kyosinstall)
#### User Interface Elements
- [x] Welcome application branding
- [x] Installer prompts and messages
- [x] Desktop environment themes
@@ -724,12 +805,14 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
- [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
@@ -737,6 +820,7 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
- [x] Maintained essential system packages
#### Scripts and Executables
- [x] Renamed installation scripts
- [x] Updated script internal references
- [x] Changed default usernames and passwords
@@ -745,6 +829,7 @@ This section documents the complete rebranding process from DTOS to KyOS, includ
### File Mapping
#### Renamed Files
```
Old Location New Location
/usr/local/bin/dtosinstall → /usr/local/bin/kyosinstall
@@ -754,6 +839,7 @@ Old Location New Location
```
#### Updated Content Files
```
File Change
/etc/os-release OS name and branding
@@ -768,7 +854,9 @@ 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'
@@ -778,12 +866,14 @@ airootfs/root/pkgs-* Package lists
- 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
@@ -791,7 +881,9 @@ airootfs/root/pkgs-* Package lists
### Package Management Changes
#### Removed Packages
All DTOS-specific packages were removed:
```
dtos-* # All DTOS branded packages
dtos-core-repo # DTOS repository configuration
@@ -799,19 +891,24 @@ 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
@@ -819,6 +916,7 @@ User-specified packages from packages.txt were added:
### VirtualBox Integration
#### Automatic Detection
```bash
# Detect VirtualBox environment
if [ "$(systemd-detect-virt)" = "oracle" ]; then
@@ -827,6 +925,7 @@ 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
@@ -835,6 +934,7 @@ fi
### Testing and Validation
#### Installation Testing
- [x] Automated installation works correctly
- [x] TUI installation accepts user input
- [x] User credentials are set properly
@@ -842,6 +942,7 @@ fi
- [x] Package installation completes successfully
#### VirtualBox Testing
- [x] Desktop loads without visual artifacts
- [x] Terminal text is visible
- [x] Applications launch successfully
@@ -849,6 +950,7 @@ fi
- [x] Audio works properly
#### Compatibility Testing
- [x] Works on real hardware
- [x] Functions in VirtualBox
- [x] Compatible with different VM configurations
@@ -857,12 +959,14 @@ fi
### 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
@@ -870,6 +974,7 @@ fi
### Distribution Preparation
#### ISO Building
```bash
# Build KyOS ISO
cd /path/to/kyos-iso/releng
@@ -877,6 +982,7 @@ sudo mkarchiso -v -w /tmp/kyos-work -o /tmp/kyos-out .
```
#### Testing Checklist
- [ ] ISO boots successfully
- [ ] Live environment functions properly
- [ ] Installation completes without errors
@@ -885,6 +991,7 @@ sudo mkarchiso -v -w /tmp/kyos-work -o /tmp/kyos-out .
- [ ] All KyOS branding appears correctly
---
## Conclusion
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.