projects/gentoo-legion

Fork 0

Damien Coles 9a4a970f76 public-ready-init

2026-01-24 20:47:35 -05:00

7.6 KiB

Raw Blame History

Gentoo Installation Guide - Legion Laptop

Complete installation guide for Gentoo Linux with Hyprland, greetd, and hybrid GPU support.

Hardware Requirements

CPU: AMD Ryzen (tested with 5900HX)
iGPU: AMD Radeon integrated
dGPU: NVIDIA GeForce (tested with RTX 3050 Ti Mobile)
RAM: 16GB+ recommended
Storage: NVMe or SSD recommended

Pre-Installation

1. Prepare LUKS Passphrase

Generate a strong passphrase for disk encryption:

openssl rand -base64 64 | tr -dc 'A-Za-z0-9' | head -c 56

Important:

Store this passphrase securely (password manager, hardware key, or offline backup)
You'll need to enter it at every boot

2. Boot Live Environment

HiDPI Fix (4K display): At the GRUB menu, press e to edit the boot entry, find the linux line, add video=1920x1080 at the end, then Ctrl+X to boot.

# Configure network
net-setup

3. Verify DNS Resolution

cat /etc/resolv.conf
# Should have valid nameservers (1.1.1.1, 8.8.8.8, etc.)

Stage 1: Disk Setup & Stage3

4. Run init.sh

Clone this repository and run the initialization script:

git clone https://github.com/<user>/gentoo-legion
cd gentoo-legion
./install/init.sh

This handles:

Disk partitioning (EFI 512MB, Swap 16GB, LUKS root)
LUKS2 encryption setup
Btrfs subvolume creation (@, @home, @var, @log, @snapshots)
Stage3 download and extraction
Copying Portage configs

You'll be prompted for the LUKS passphrase twice (format + open).

5. Enter Chroot

./install/chroot.sh

Stage 2: Base System Configuration

6. Verify Network

ping -c 2 gentoo.org

If no network, check /etc/resolv.conf has valid nameservers.

7. Sync Portage & Select Profile

emerge --sync
eselect profile list
# Select: default/linux/amd64/23.0/desktop
eselect profile set <number>

8. Enable GURU Overlay

Required for Hyprland ecosystem packages:

emerge app-eselect/eselect-repository
eselect repository enable guru
emerge --sync

9. Configure ccache

emerge dev-util/ccache
mkdir -p /var/cache/ccache
# ccache.conf was already copied by init.sh

10. Install Firmware & Compile @world

emerge sys-kernel/linux-firmware --autounmask-write
dispatch-conf  # Choose 'u' to update
emerge sys-kernel/linux-firmware
emerge --update --deep --newuse @world
# This will take a while

11. Re-enable Harfbuzz

After @world completes, restore harfbuzz support:

# Remove the -harfbuzz line from circular-dependencies
nano /etc/portage/package.use/circular-dependencies

# Rebuild with full support
emerge -1 media-libs/freetype media-libs/harfbuzz

12. Set Timezone & Locale

echo "America/New_York" > /etc/timezone  # Adjust for your timezone
emerge --config sys-libs/timezone-data

nano /etc/locale.gen
# Uncomment: en_US.UTF-8 UTF-8

locale-gen

eselect locale list
eselect locale set <number>  # en_US.utf8

echo "LANG=en_US.UTF-8" > /etc/locale.conf

env-update && source /etc/profile

13. Set Hostname

echo "<your-hostname>" > /etc/hostname

Stage 3: Services & Kernel

14. Run services.sh

cd /path/to/gentoo-legion
./install/services.sh
# Installs and configures OpenRC services

15. Verify Dracut Configuration

ls -la /etc/dracut.conf.d/
# Should show: crypt.conf, nvidia.conf

If missing, create manually:

mkdir -p /etc/dracut.conf.d
echo 'add_dracutmodules+=" crypt "' > /etc/dracut.conf.d/crypt.conf
echo 'add_drivers+=" nvidia nvidia_modeset nvidia_uvm nvidia_drm "' > /etc/dracut.conf.d/nvidia.conf
echo 'force_drivers+=" nvidia nvidia_modeset nvidia_uvm nvidia_drm "' >> /etc/dracut.conf.d/nvidia.conf

16. Compile Kernel

emerge sys-kernel/gentoo-kernel
# This will also take a while
# Dracut automatically includes NVIDIA modules in initramfs

17. Verify fstab and crypttab

cat /etc/crypttab
# Should show: cryptroot UUID=<uuid> none luks

cat /etc/fstab
# Should show EFI, encrypted swap, and Btrfs mounts

Stage 4: User Configuration

18. Set Root Password

passwd

19. Install Shell & Tools

emerge app-shells/zsh app-shells/gentoo-zsh-completions \
       app-portage/gentoolkit app-portage/portage-utils app-portage/eix

# Copy shell configs
cp shell/zshrc.example /root/.zshrc
mkdir -p /root/.config
cp shell/starship.toml /root/.config/starship.toml
chsh -s /bin/zsh

20. Configure sudo & Create User

emerge app-admin/sudo
visudo
# Uncomment: %wheel ALL=(ALL:ALL) ALL

useradd -m -G users,wheel,audio,video,input,lp,cdrom,portage,usb,render,network,power -s /bin/zsh <username>
passwd <username>

# Copy shell configs for user
cp shell/zshrc.example /home/<username>/.zshrc
mkdir -p /home/<username>/.config
cp shell/starship.toml /home/<username>/.config/starship.toml
chown -R <username>:<username> /home/<username>

Stage 5: Graphics & Bootloader

21. Configure NVIDIA

emerge x11-drivers/nvidia-drivers

# Blacklist nouveau
echo "blacklist nouveau" > /etc/modprobe.d/blacklist-nouveau.conf
echo "options nouveau modeset=0" >> /etc/modprobe.d/blacklist-nouveau.conf

# Enable NVIDIA DRM
echo "options nvidia_drm modeset=1 fbdev=1" > /etc/modprobe.d/nvidia.conf

22. Install & Configure GRUB

emerge sys-boot/grub
grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=Gentoo

nano /etc/default/grub

Required GRUB settings for LUKS + NVIDIA:

GRUB_CMDLINE_LINUX_DEFAULT="nvidia_drm.modeset=1 acpi_backlight=native"
GRUB_ENABLE_CRYPTODISK=y

Generate config:

grub-mkconfig -o /boot/grub/grub.cfg

23. Verify Initramfs Setup

# Check LUKS/crypt modules
lsinitrd /boot/initramfs-*.img | grep -E "(crypt|luks)"

# Check NVIDIA modules
lsinitrd /boot/initramfs-*.img | grep nvidia

24. Verify Boot Services

rc-update show boot | grep -E "(dbus|elogind)"

# If missing:
rc-update add dbus boot
rc-update add elogind boot

25. Exit & Reboot

exit
umount -lR /mnt/gentoo
cryptsetup close cryptroot
reboot
# Remove installation media

First Boot:

GRUB loads, system prompts for LUKS passphrase
Enter your passphrase
System boots to greetd/regreet login screen

Stage 6: Desktop Environment

26. Install Hyprland Desktop Set

# Login as your user
emerge @hyprland

27. Install KooL's Dotfiles

This configuration is designed to work with KooL's Hyprland dotfiles. Install them:

# Clone the dotfiles installer
git clone --depth=1 https://github.com/JaKooLit/Hyprland-Dots
cd Hyprland-Dots

# Run the installer (select options as needed)
chmod +x copy.sh
./copy.sh

Notes:

The installer will prompt for various options (fonts, themes, etc.)
Skip package installation if you've already emerged @hyprland
After installation, copy configs from this repo's hypr/ directory to customize for your setup

See: https://github.com/JaKooLit/Hyprland-Dots

28. Configure User Session Logging

mkdir -p ~/.local/log

Post-Installation

See the following guides for additional configuration:

Hybrid GPU Guide - AMD + NVIDIA configuration
greetd Setup - Display manager configuration
Troubleshooting - Common issues and fixes

Quick Reference

Update system:

emerge --sync
emerge -avuDN @world

Create snapshot before risky operation:

sudo snapper create -d "before <operation>"

Service management (OpenRC):

rc-service <service> start|stop|restart|status
rc-update add|del <service> <runlevel>
loginctl reboot|poweroff|suspend  # NOT systemctl

7.6 KiB Raw Blame History