omnixy/BUILD_ISO.md

Building OmniXY ISO Image

This guide explains how to build a live ISO image of OmniXY NixOS that can be used for installation or testing.

Prerequisites

1. NixOS or Nix with Flakes: You need a system with Nix installed and flakes enabled
2. Sufficient disk space: Building an ISO requires several GB of space
3. Good internet connection: Initial build will download many packages

Quick Start

Method 1: Using the Built-in App (Recommended)

# Clone the repository
git clone https://github.com/TheArctesian/omnixy.git
cd omnixy

# Build the ISO using the built-in app
nix run .#build-iso

The built app will:

• Build the ISO image
• Show progress and final location
• Provide instructions for using the ISO

Method 2: Direct Nix Build

# Build the ISO directly
nix build .#iso

# The ISO will be available as a symlink
ls -la ./result/iso/

Method 3: Build Specific Configuration

# Build the ISO configuration specifically
nix build .#nixosConfigurations.omnixy-iso.config.system.build.isoImage

# Find the ISO file
find ./result -name "*.iso"

ISO Features

The OmniXY ISO includes:

Pre-installed Software

• Desktop Environment: Hyprland with full OmniXY theming
• Development Tools: Complete development stack (editors, compilers, etc.)
• Multimedia: Video players, image viewers, audio tools
• Productivity: Browsers, office suite, communication tools
• System Tools: Disk utilities, system monitors, network tools

Live Session Features

• Auto-login: Boots directly to the desktop as nixos user
• No password required: Passwordless sudo for system administration
• Network ready: NetworkManager enabled for easy connection
• Installation tools: Graphical installer (Calamares) included
• Theme showcase: All OmniXY themes available for testing

Installation Capabilities

• Guided installation: Run omnixy-installer for graphical setup
• Manual installation: Full NixOS installation tools available
• Hardware support: Wide hardware compatibility with latest kernel

ISO Configuration Details

Size and Performance

• Expected size: 3-5 GB (depending on included packages)
• RAM requirements: Minimum 4GB RAM for live session
• Boot methods: UEFI and BIOS supported

Included Themes

All OmniXY themes are included and can be tested:

• tokyo-night (default)
• catppuccin
• gruvbox
• nord
• everforest
• rose-pine
• kanagawa
• catppuccin-latte
• matte-black
• osaka-jade
• ristretto

Customization Options

Building with Different Default Theme

Edit iso.nix and change the theme import:

# Change this line:
./modules/themes/tokyo-night.nix

# To your preferred theme:
./modules/themes/gruvbox.nix

Excluding Packages

Modify the omnixy.packages.exclude section in iso.nix:

omnixy = {
  # ... other config
  packages = {
    exclude = [ "discord" "spotify" "steam" ]; # Add packages to exclude
  };
};

Adding Custom Packages

Add packages to the environment.systemPackages in iso.nix:

environment.systemPackages = with pkgs; [
  # ... existing packages
  your-custom-package
];

Using the ISO

Creating Bootable Media

USB Drive (Linux)

# Replace /dev/sdX with your USB device
sudo dd if=./result/iso/omnixy-*.iso of=/dev/sdX bs=4M status=progress oflag=sync

USB Drive (Windows)

Use tools like:

• Rufus
• Balena Etcher
• Windows USB/DVD Download Tool

DVD

Use any DVD burning software with the ISO file.

Testing in Virtual Machine

QEMU

# Basic VM test (4GB RAM)
qemu-system-x86_64 -cdrom ./result/iso/omnixy-*.iso -m 4G -enable-kvm

# VM with more features
qemu-system-x86_64 \
  -cdrom ./result/iso/omnixy-*.iso \
  -m 8G \
  -enable-kvm \
  -vga virtio \
  -display gtk,gl=on \
  -machine q35 \
  -cpu host

VirtualBox

1. Create new VM with Linux/Other Linux (64-bit)
2. Allocate at least 4GB RAM
3. Mount the ISO as CD/DVD
4. Enable hardware acceleration if available

VMware

1. Create new VM with Linux/Other Linux 5.x kernel 64-bit
2. Allocate at least 4GB RAM
3. Use ISO as CD/DVD source
4. Enable hardware acceleration

Installation from ISO

Using the Graphical Installer

1. Boot from the ISO
2. Wait for auto-login to complete
3. Run the installer:

   omnixy-installer
   

4. Follow the graphical installation wizard
5. Reboot when complete

Manual Installation

1. Boot from the ISO
2. Partition your disk with gparted or command-line tools
3. Mount your root partition:

   sudo mount /dev/sdaX /mnt
   

4. Generate hardware configuration:

   sudo nixos-generate-config --root /mnt
   

5. Download OmniXY:

   cd /mnt/etc/nixos
   sudo git clone https://github.com/TheArctesian/omnixy.git .
   

6. Edit configuration:

   sudo nano configuration.nix
   # Set your username and preferred theme
   

7. Install:

   sudo nixos-install --flake /mnt/etc/nixos#omnixy
   

8. Set root password when prompted
9. Reboot

Troubleshooting

Build Issues

"Path does not exist" errors

Ensure all files are present and paths in configuration are correct:

# Check if all required files exist
ls -la modules/ packages/ assets/

Out of disk space

Building requires significant space:

# Clean up nix store
nix-collect-garbage -d

# Check available space
df -h

Network issues during build

Ensure internet connection and try with cached builds:

# Use substituters
nix build .#iso --substituters https://cache.nixos.org

Boot Issues

ISO doesn't boot

• Verify BIOS/UEFI settings
• Try different USB creation method
• Check USB drive integrity

Black screen on boot

• Try different graphics settings in GRUB
• Add nomodeset kernel parameter
• Use safe graphics mode

Out of memory during live session

• Use system with more RAM (minimum 4GB)
• Close unnecessary applications
• Consider lighter package selection

Installation Issues

Hardware not detected

• Ensure latest kernel is being used
• Check for firmware packages
• Update hardware-configuration.nix manually

Network issues during installation

• Test network in live session first
• Configure NetworkManager connections
• Check firewall settings

Advanced Usage

Building for Different Architectures

Currently, OmniXY ISO supports x86_64-linux. For other architectures:

# Check available systems
nix flake show

# Build for specific system (if supported)
nix build .#packages.aarch64-linux.iso

Customizing Boot Parameters

Edit the ISO configuration to add custom kernel parameters:

# In iso.nix
boot.kernelParams = [
  # Add your custom parameters
  "custom.parameter=value"
];

Creating Minimal ISO

For a smaller ISO, disable features in iso.nix:

omnixy = {
  preset = "minimal"; # Instead of "everything"
  packages.exclude = [ /* large packages */ ];
};

CI/CD Integration

GitHub Actions

Add to .github/workflows/build-iso.yml:

name: Build ISO
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: cachix/install-nix-action@v20
      with:
        enable_flakes: true
    - name: Build ISO
      run: nix build .#iso
    - name: Upload ISO
      uses: actions/upload-artifact@v3
      with:
        name: omnixy-iso
        path: result/iso/*.iso

GitLab CI

Add to .gitlab-ci.yml:

build-iso:
  image: nixos/nix:latest
  script:
    - nix build .#iso
    - cp result/iso/*.iso ./
  artifacts:
    paths:
      - "*.iso"
    expire_in: 1 week
  only:
    - tags

Contributing

When modifying the ISO configuration:

1. Test builds locally before committing
2. Verify ISO boots in at least one VM
3. Test both UEFI and BIOS boot modes
4. Check that installation process works
5. Update documentation if adding new features

Support

• Issues: Report problems on GitHub Issues
• Discussions: Join GitHub Discussions for questions
• Documentation: Check the main README.md for general info
• Matrix/Discord: Community chat (links in main README)

---

For more information about OmniXY, see the main README.md file.