Installation Guide

This guide will help you install and set up SAGE OS on your system or in a virtual environment.

🎯 Prerequisites

System Requirements

Component	Minimum	Recommended
RAM	2 GB	8 GB
Storage	10 GB	50 GB
CPU	x86_64, ARM64, or RISC-V	Multi-core
Graphics	VGA compatible	Hardware acceleration

Supported Architectures

x86_64: Intel/AMD 64-bit processors
ARM64: ARM 64-bit processors (AArch64)
RISC-V: RISC-V 64-bit processors

🛠️ Development Environment Setup

Install Dependencies

=== "Ubuntu/Debian"

sudo apt update
sudo apt install -y \
    build-essential \
    nasm \
    grub-pc-bin \
    grub-efi-amd64-bin \
    xorriso \
    mtools \
    qemu-system-x86 \
    qemu-system-arm \
    qemu-system-misc \
    gcc-multilib \
    libc6-dev-i386

=== "Fedora/RHEL"

sudo dnf install -y \
    gcc \
    nasm \
    grub2-pc \
    grub2-efi-x64 \
    xorriso \
    mtools \
    qemu-system-x86 \
    qemu-system-arm \
    qemu-system-riscv

=== "Arch Linux"

sudo pacman -S \
    base-devel \
    nasm \
    grub \
    xorriso \
    mtools \
    qemu-system-x86 \
    qemu-system-arm \
    qemu-system-riscv

Install Rust Toolchain

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Add required targets
rustup target add x86_64-unknown-none
rustup target add aarch64-unknown-none
rustup target add riscv64gc-unknown-none-elf

# Install required components
rustup component add rust-src
rustup component add llvm-tools-preview

📥 Getting the Source Code

Clone Repository

# Clone the main repository
git clone https://github.com/AshishYesale7/SAGE-OS.git
cd SAGE-OS

# Switch to development branch
git checkout dev

# Initialize submodules (if any)
git submodule update --init --recursive

Verify Setup

# Check build environment
make check-env

# Verify all dependencies
./scripts/verify-dependencies.sh

🏗️ Building SAGE OS

Quick Build

# Build for x86_64 (default)
make build

# Build for specific architecture
make build ARCH=x86_64
make build ARCH=aarch64
make build ARCH=riscv64

Detailed Build Process

# Clean previous builds
make clean

# Build bootloader
make bootloader ARCH=x86_64

# Build kernel
make kernel ARCH=x86_64

# Build user space
make userspace ARCH=x86_64

# Create ISO image
make iso ARCH=x86_64

Build Configuration

Create a .config file to customize the build:

# .config
ARCH=x86_64
DEBUG=1
OPTIMIZATION=2
FEATURES=network,graphics,usb
TARGET_CPU=native

💿 Creating Installation Media

ISO Image Creation

# Create bootable ISO
make iso ARCH=x86_64

# The ISO will be created at:
# dist/sage-os-x86_64.iso

USB Drive Creation

# Create bootable USB drive (replace /dev/sdX with your USB device)
sudo dd if=dist/sage-os-x86_64.iso of=/dev/sdX bs=4M status=progress
sudo sync

Virtual Machine Images

# Create QEMU disk image
make vm-image ARCH=x86_64

# Create VirtualBox image
make vbox-image ARCH=x86_64

# Create VMware image
make vmware-image ARCH=x86_64

🖥️ Installation Methods

Method 1: Virtual Machine (Recommended for Testing)

QEMU

# Run in QEMU
make run ARCH=x86_64

# Or manually:
qemu-system-x86_64 \
    -cdrom dist/sage-os-x86_64.iso \
    -m 2G \
    -enable-kvm \
    -cpu host \
    -smp 2

VirtualBox

Create new VM with:
Type: Other
Version: Other/Unknown (64-bit)
Memory: 2048 MB
Hard disk: Create new (20 GB)
Mount the ISO and boot

VMware

Create new VM
Select "I will install the operating system later"
Choose "Other" as guest OS
Allocate resources
Mount ISO and boot

Method 2: Physical Hardware

Hardware Installation

Installing on physical hardware will erase existing data. Ensure you have backups!

Boot from USB/CD
Insert installation media
Boot from USB/CD in BIOS/UEFI
Select SAGE OS from boot menu
Installation Process
Follow on-screen instructions
Select installation disk
Configure partitions
Set up user account
Complete installation

Method 3: Network Boot (PXE)

# Set up PXE server
./scripts/setup-pxe-server.sh

# Configure DHCP for PXE boot
# Boot target machine from network

⚙️ Post-Installation Configuration

First Boot

System Configuration
Set timezone
Configure network
Create user accounts
Set up SSH keys

Package Management

# Update system
sage-pkg update

# Install additional packages
sage-pkg install development-tools

Security Setup

# Enable firewall
sage-firewall enable

# Configure secure boot
sage-secureboot setup

Development Setup

# Install development tools
sage-pkg install build-essential rust-toolchain

# Set up development environment
./scripts/setup-dev-env.sh

# Configure editor/IDE
sage-config editor vim  # or code, emacs, etc.

🔧 Troubleshooting

Common Issues

Build Failures

# Check dependencies
./scripts/check-dependencies.sh

# Clean and rebuild
make clean && make build

# Verbose build output
make build V=1

Boot Issues

UEFI Boot Problems
Disable Secure Boot in BIOS
Enable Legacy Boot mode
Check boot order
Hardware Compatibility
Check supported hardware list
Update firmware/BIOS
Try different boot parameters

Virtual Machine Issues

Performance Problems
Enable hardware acceleration (KVM/VT-x)
Increase allocated memory
Use virtio drivers
Graphics Issues
Try different graphics modes
Disable 3D acceleration
Use software rendering

Getting Help

Documentation: Check the troubleshooting guide
Issues: Report bugs on GitHub Issues
Discussions: Join GitHub Discussions
Email: Contact ashishyesale007@gmail.com

📊 Installation Verification

System Check

# Check system information
sage-info system

# Verify installation
sage-verify --full

# Run system tests
sage-test --basic

Performance Benchmarks

# Run performance tests
sage-benchmark --all

# Memory test
sage-test memory

# Storage test
sage-test storage

# Network test
sage-test network

🔄 Updates and Maintenance

System Updates

# Check for updates
sage-update check

# Install updates
sage-update install

# Automatic updates
sage-update auto-enable

Backup and Recovery

# Create system backup
sage-backup create --full

# Restore from backup
sage-backup restore --file backup.tar.gz

# Recovery mode
# Boot with 'recovery' kernel parameter

🔗 Next Steps

After successful installation:

Quick Start Guide - Get familiar with SAGE OS
First Boot - Initial system configuration
Development Setup - Set up development environment
Architecture Overview - Understand the system