Horizon

Type Bootstrap Engine

Stages 3

Total Time 12–20 hours

Horizon is the LFS-style bootstrap engine for Astaraxia. It builds a complete, bootable system from scratch on any Linux host - no pre-built tarballs required. Three stages, one script, a lot of compilation.

Time warning: A full bootstrap takes 12–20 hours depending on your hardware. Set up a tmux session. Go touch grass. Come back to a system.

Philosophy

Horizon follows the Linux From Scratch methodology with Gentoo-style stage separation:

Stage 1 - Build a minimal cross-toolchain that is independent of the host system
Stage 2 - Use that toolchain to prepare the chroot environment
Stage 3 - Rebuild everything from inside the chroot with correct paths, producing the final system

The result is a system that shares zero assumptions with the host that built it.

Prerequisites

A Linux host system (any distro)
10 GB+ free disk space (20 GB recommended)
Astral 2.0.5.0+ installed on the host
Basic Linux knowledge
gcc, make, bison, flex, texinfo, perl on the host

Quick Start

# Install Astral on your host first
curl -O https://raw.githubusercontent.com/Astaraxia-Linux/Astral/main/astral
chmod +x astral && sudo mv astral /usr/bin/

# Set your target mount point
export LFS=/mnt/lfs
sudo mkdir -pv $LFS

# Initialize Horizon (downloads stage scripts)
sudo astral -h --init

# Stage 1 - temporary toolchain (~2-4 hours)
sudo astral -h --stage 1

# Stage 2 - chroot preparation (~3-5 hours)
sudo astral -h --stage 2

# Enter chroot and run Stage 3
sudo astral --chroot $LFS
astral -h --stage 3

# Exit chroot, configure bootloader
exit

Stage 1 - Temporary Toolchain

Builds a minimal cross-compilation toolchain that is completely independent of the host system's libraries and compiler. Everything is installed to $LFS/tools.

What gets built:

Binutils (cross-assembler and linker)
GCC (cross-compiler, C and C++ only)
Linux API headers
Glibc (for the target)
Libstdc++

sudo astral -h --stage 1

Check progress with astral -h --status. Logs go to /var/log/astral/horizon.log.

If Stage 1 fails, you can usually re-run it. The scripts check what's already been built and skip completed steps.

Stage 2 - Chroot Preparation

Uses the Stage 1 toolchain to build additional tools needed inside the chroot. At the end of this stage, the $LFS directory is ready to be entered as a self-contained environment.

What gets built:

Coreutils, util-linux, bash
Findutils, grep, sed, gawk
Make, patch, tar, xz
Basic filesystem structure under $LFS

sudo astral -h --stage 2

Stage 3 - Final System

Run inside the chroot. Rebuilds everything with the correct installation paths and produces the final bootable Astaraxia base system.

What gets built:

Glibc (final, correct paths)
GCC, Binutils (final)
All base system packages (curl, wget, openssl, ncurses, shadow, etc.)
Init system (OpenRC by default)
Basic networking

# Enter the chroot
sudo astral --chroot $LFS

# Inside chroot:
astral -h --stage 3

After Bootstrap

Stage 3 leaves you with a functional base system but no bootloader or kernel. You need to configure those manually:

# Still inside chroot - install kernel
astral -S sys-kernel/linux
cd /usr/src/linux
make menuconfig
make -j$(nproc)
make modules_install
make install

# Install GRUB bootloader
astral -S sys-boot/grub
grub-install /dev/sdX          # replace sdX with your disk
grub-mkconfig -o /boot/grub/grub.cfg

# Set root password
passwd

# Configure fstab
# Edit /etc/fstab to match your partition layout

# Exit chroot and reboot
exit
reboot

Troubleshooting

Problem	Fix
Build fails in Stage 1	Check `/var/log/astral/horizon.log`. Usually a missing host dep - install it and re-run.
Disk full	Each stage needs ~3 GB. Check with `df -h $LFS`. Clear `$LFS/sources` tarballs after each stage if needed.
Chroot fails to enter	Make sure Stage 2 completed fully. Run `astral -h --status` to check.
Stage 3 fails on glibc	The Stage 1 toolchain may be contaminated by the host. Start Stage 1 over with a clean `$LFS/tools`.
No network after boot	Configure your init system to start NetworkManager or dhcpcd at boot.

Horizon Commands

Command	Description
astral -h --init	Initialize Horizon, download stage scripts
astral -h --stage 1	Run Stage 1 (temporary toolchain)
astral -h --stage 2	Run Stage 2 (chroot prep)
astral -h --stage 3	Run Stage 3 (final system, inside chroot)
astral -h --status	Show progress of current/last stage
astral --chroot $LFS	Enter the LFS chroot environment