AeThex-OS/docs/LINUX_QUICKSTART.md

AeThex Linux - Quick Start Guide

Build and Test AeThex Linux (Proof of Concept)

This guide will help you build a bootable ISO and test it in a VM within 30 minutes.

Prerequisites

System Requirements:

• Ubuntu 22.04+ or Debian-based Linux
• 20GB free disk space
• 8GB RAM (4GB for build, 4GB for VM)
• Root access (sudo)

Required Tools:

# Install all dependencies
sudo apt update
sudo apt install -y \
  build-essential \
  curl \
  git \
  nodejs \
  npm \
  debootstrap \
  squashfs-tools \
  xorriso \
  grub-pc-bin \
  grub-efi-amd64-bin \
  virtualbox

Rust (for Tauri build):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Step 1: Build the ISO

# Navigate to project directory
cd /workspaces/AeThex-OS

# Make scripts executable
chmod +x script/*.sh

# Build ISO (takes 10-15 minutes)
sudo bash script/build-linux-iso.sh

What this does:

1. Bootstraps Ubuntu 24.04 base system
2. Installs required packages (X server, desktop manager)
3. Builds your Tauri desktop app
4. Configures auto-login and system services
5. Creates bootable ISO image

Output:

• ISO: ~/aethex-linux-build/AeThex-Linux-1.0.0-alpha-amd64.iso
• Size: ~2-4GB
• Checksum: ~/aethex-linux-build/AeThex-Linux-1.0.0-alpha-amd64.iso.sha256

Step 1.5: Verify the ISO

./script/verify-iso.sh -i ~/aethex-linux-build/AeThex-Linux-1.0.0-alpha-amd64.iso

For strict verification and mount checks, see docs/ISO_VERIFICATION.md.

Step 2: Test in Virtual Machine

# Launch VirtualBox VM with the ISO
sudo bash script/test-in-vm.sh

What this does:

1. Creates new VirtualBox VM (4GB RAM, 20GB disk)
2. Attaches the AeThex Linux ISO
3. Boots the VM
4. Auto-logs in to AeThex Desktop

VM Login:

• Username: aethex
• Password: aethex

Test Checklist:

• System boots to desktop (no errors)
• Window manager works (drag windows)
• Terminal opens (Ctrl+Alt+T)
• File manager shows directories
• Applications menu appears
• Network connects automatically

Step 3: Create Bootable USB (Optional)

# Check available USB drives
lsblk

# Write ISO to USB (replace /dev/sdX with your device)
sudo bash script/create-usb.sh /dev/sdX

⚠️ WARNING: This erases all data on the USB drive!

Step 4: Boot on Real Hardware

1. Insert USB drive
2. Restart computer
3. Press F12, F2, or Del (depending on manufacturer) to access boot menu
4. Select USB drive
5. AeThex Linux will boot directly to desktop

Configuration Files

All configuration files are in configs/:

configs/
├── grub/                      # Bootloader configuration
│   ├── grub.cfg              # Boot menu
│   └── themes/aethex/        # Visual theme
├── lightdm/                  # Display manager
│   └── lightdm.conf          # Auto-login config
├── systemd/                  # System services
│   ├── aethex-desktop.service    # Main desktop
│   └── aethex-kernel.service     # OS Kernel API
└── xsession/                 # Desktop session
    └── aethex.desktop        # Session definition

Troubleshooting

Build fails at Tauri step

# Install Rust dependencies for your distro
# Ubuntu/Debian:
sudo apt install libwebkit2gtk-4.1-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

# Then retry build
cd /workspaces/AeThex-OS
npm run tauri:build

VM won't boot

# Check if ISO was created successfully
ls -lh ~/aethex-linux-build/*.iso

# Verify checksum
sha256sum -c ~/aethex-linux-build/*.sha256

# Try rebuilding with clean slate
sudo rm -rf ~/aethex-linux-build
sudo bash script/build-linux-iso.sh

Desktop doesn't auto-login

• Default credentials: aethex / aethex
• Check /etc/lightdm/lightdm.conf for auto-login settings
• Verify service is enabled: systemctl status lightdm

Black screen after boot

• Add nomodeset to boot parameters (press 'e' in GRUB menu)
• Or try: quiet splash nomodeset

Customization

Change Default User

Edit in script/build-linux-iso.sh:

# Replace 'aethex' with your username
useradd -m -s /bin/bash YOUR_USERNAME
echo 'YOUR_USERNAME:YOUR_PASSWORD' | chpasswd

Add Pre-installed Software

Add to package list in script/build-linux-iso.sh:

apt-get install -y \
  # ... existing packages ...
  firefox \
  gimp \
  vlc

Change Branding

• Logo: Replace configs/grub/themes/aethex/logo.png
• Colors: Edit configs/grub/themes/aethex/theme.txt
• Boot text: Edit configs/grub/grub.cfg

Next Steps

Distribution (Public Release)

1. Host ISO on CDN or GitHub Releases
2. Create installation documentation
3. Set up update repository (apt/PPA)
4. Add installer wizard (Calamares)

Production Hardening

• Enable secure boot signing
• Add encrypted home directory option
• Configure firewall rules
• Set up automatic security updates
• Add AppArmor/SELinux profiles

Advanced Features

• Live USB persistence (save data between boots)
• Network install option (PXE boot)
• Multi-language support
• Custom kernel with optimizations
• Hardware driver auto-detection

Resources

• Full documentation: AETHEX_LINUX.md
• Tauri setup: TAURI_SETUP.md
• Project overview: README.md

Support

For issues or questions:

1. Check existing documentation
2. Review system logs: journalctl -xe
3. Test in VM before real hardware
4. File issue on GitHub repository

---

Total Time to Bootable ISO: ~30-45 minutes ISO Size: 2-4 GB Minimum RAM: 2GB (4GB recommended) Minimum Disk: 10GB (20GB recommended)