projects/gentoo-legion-python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
gentoo-legion-python/procedure.md
Damien Coles 6e8d1c9392 public-ready-init
2026-02-05 18:05:06 -05:00

10 KiB
Raw Permalink Blame History

Gentoo Installation Procedure - Legion Laptop

Automated installation using Python scripts for Lenovo Legion laptops with AMD + NVIDIA hybrid graphics.

Hardware

Tested on Legion S7 15ACH6:

  • CPU: AMD Ryzen 9 5900HX (16 threads, Zen 3)
  • iGPU: AMD Radeon Vega (Cezanne)
  • dGPU: NVIDIA GeForce RTX 3050 Ti Mobile
  • RAM: 24GB DDR4
  • Storage: NVMe with LUKS2 encryption

Should work on other Legion models with similar hardware.

Quick Start

Two commands handle the entire installation:

# Phase 1: Live environment -> chroot -> first reboot
python setup.py --install   # Run once outside chroot, once inside

# Phase 2: After first boot
python setup.py --desktop   # Installs Hyprland + optional fingerprint

--install auto-detects whether you're in the live environment or chroot:

  • Outside chroot: Runs disk → stage3 → config → fstab → chroot
  • Inside chroot: Runs sync → world → firmware → kernel → services → users → nvidia → bootloader

Idempotency

All commands are safe to re-run. If interrupted or if something fails:

  • Simply run the same command again
  • Completed steps are detected and skipped
  • Partial state is handled gracefully (e.g., LUKS exists but not mounted)

Example: If world fails mid-compile, just run python setup.py --install again.

Pre-Installation

1. Prepare LUKS Passphrase

Generate a strong passphrase for disk encryption:

# Generate 56-char alphanumeric passphrase
openssl rand -base64 64 | tr -dc 'A-Za-z0-9' | head -c 56

Store securely (password manager, hardware key, offline backup).

2. Boot Live Environment

At GRUB menu, press e, add video=1920x1080 to the linux line (HiDPI fix), then Ctrl+X.

# Configure network
net-setup

# Verify DNS
ping -c 2 gentoo.org

3. Clone Repository

emerge --ask dev-vcs/git
git clone https://github.com/<your-username>/gentoo-legion-python /root/gentoo
cd /root/gentoo

Stage 1: Disk Setup (Pre-Chroot)

Run from live environment:

python setup.py

Select commands in order, or run individually:

1) disk - Partition, Encrypt, Mount

  • Creates GPT partition table
  • EFI partition (1GB)
  • Swap partition (24GB)
  • LUKS2 encrypted root (remaining space)
  • Btrfs with subvolumes (@, @home, @var, @log, @snapshots)
  • Mounts everything to /mnt/gentoo

Re-running: If LUKS already exists, you'll be prompted to reformat or reuse. Select reuse to skip destructive steps and just mount the existing setup.

2) stage3 - Download & Extract

  • Fetches latest stage3-amd64-openrc tarball
  • Verifies checksum
  • Extracts to /mnt/gentoo

3) config - Copy Portage Configuration

Copies from portage/ to /mnt/gentoo/etc/portage/:

  • make.conf
  • package.use/
  • package.accept_keywords/
  • package.env/
  • package.license/
  • env/
  • sets/

Also copies from repo root to /mnt/gentoo/etc/:

  • dracut.conf.d/

4) fstab - Generate Filesystem Config

Generates:

  • /etc/fstab (EFI, Btrfs subvolumes)
  • /etc/conf.d/dmcrypt (encrypted swap)

5) chroot - Prepare & Enter

  • Copies resolv.conf for network
  • Mounts /proc, /sys, /dev, /run
  • Enters chroot

Or run all pre-chroot steps:

python setup.py all

Stage 2: Base System (Inside Chroot)

After entering chroot, clone the repo:

# Sync portage first (needed to install anything)
emerge --sync

# Install git and clone repo
emerge --ask dev-vcs/git
git clone https://github.com/<your-username>/gentoo-legion-python /root/gentoo
cd /root/gentoo
python setup.py --install

The --install command will pick up where it left off (inside chroot it runs sync → world → ... → bootloader).

7) sync - Portage Sync & Profile

  • Syncs portage tree (webrsync)
  • Sets profile: default/linux/amd64/23.0/desktop
  • Enables GURU overlay (required for Hyprland)
  • Sets timezone (America/New_York)
  • Configures locale (en_US.UTF-8)
  • Sets hostname
  • Activates encrypted swap for builds

Note: ccache is enabled automatically via FEATURES="ccache" in make.conf.

8) world - Update @world

emerge --ask --verbose --update --deep --newuse @world

This takes several hours. Swap is active to prevent OOM.

Circular Dependencies: After @world completes, the script automatically:

  1. Reads package.use/circular-dependencies for temporarily disabled USE flags
  2. Clears the file (keeps header comments)
  3. Rebuilds affected packages with full USE flags (freetype, harfbuzz, libwebp, pillow)

9) firmware - Install Linux Firmware

emerge sys-kernel/linux-firmware

10) kernel - Install Kernel

Choose:

  1. gentoo-kernel-bin - Precompiled, fastest
  2. gentoo-kernel - Compiled locally

Dracut auto-generates initramfs with crypt + NVIDIA modules.

Stage 3: Services & Configuration

11) services - System Services

Installs and configures:

  • System: sysklogd, cronie
  • Network: NetworkManager, chrony, iptables
  • Bluetooth: bluez, blueman
  • Desktop: udisks, power-profiles-daemon, rtkit
  • Display Manager: SDDM
  • Containers: podman, podman-compose
  • Backup: snapper

Configures OpenRC runlevels:

  • boot: dbus, elogind, dmcrypt
  • default: All services listed above

Copies from repo:

  • conf.d/ → /etc/conf.d/ (dmcrypt, iptables, snapper configs)
  • iptables/ → /var/lib/iptables/rules-save and /var/lib/ip6tables/rules-save
  • udev/ → /etc/udev/rules.d/ (power profile rules)

12) users - Shell & User Setup

Installs shell tools:

  • zsh, zsh-autosuggestions, zsh-syntax-highlighting
  • starship, zoxide, fzf, lsd
  • gentoolkit, portage-utils, eix

Then:

  1. Copies .zshrc and starship.toml to /root
  2. Sets root shell to zsh
  3. Prompts for root password
  4. Configures sudo (enables wheel group)
  5. Creates user with groups: users, wheel, input
  6. Copies shell config to user home
  7. Prompts for user password

Stage 4: Graphics & Bootloader

13) nvidia - NVIDIA Drivers

  1. Installs nvidia-drivers
  2. Blacklists nouveau (/etc/modprobe.d/blacklist-nouveau.conf)
  3. Configures DRM modeset (/etc/modprobe.d/nvidia.conf)
  4. Copies dracut nvidia.conf for early KMS
  5. Optionally rebuilds initramfs
  6. Verifies NVIDIA modules in initramfs

14) bootloader - GRUB Installation

  1. Copies dracut crypt.conf for LUKS support
  2. Installs GRUB
  3. Installs to EFI partition (--bootloader-id=Gentoo)
  4. Configures /etc/default/grub:
    • GRUB_CMDLINE_LINUX_DEFAULT="nvidia_drm.modeset=1 acpi_backlight=native"
    • GRUB_ENABLE_CRYPTODISK=y
    • GRUB_GFXMODE=1920x1080 (HiDPI fix)
  5. Generates grub.cfg
  6. Verifies initramfs - checks for crypt/LUKS and NVIDIA modules

First Boot

After GRUB, you'll be prompted for your LUKS passphrase, then login as root.

Connect to WiFi

NetworkManager has no saved connections yet. Use the TUI:

nmtui

Select Activate a connection → choose your network → enter password.

Or via command line:

nmcli device wifi list
nmcli device wifi connect "YourSSID" password "YourPassword"

Verify connectivity:

ping -c 2 gentoo.org

Clone Repository (as user)

Switch to your user account and clone the repo:

su - <username>
git clone https://github.com/<your-username>/gentoo-legion-python ~/gentoo

Stage 5: Desktop Environment

Install Hyprland Desktop

As your user (not root):

sudo emerge --ask @hyprland

This installs:

  • Hyprland compositor
  • Waybar, swaync, rofi, wlogout
  • Qt/GTK theming (Kvantum, qt5ct, qt6ct)
  • Fonts (Nerd Fonts, JetBrains Mono, etc.)
  • Media tools (mpv, ffmpeg)
  • File manager (Nautilus)
  • And more...

Post-Install Configuration

Copy Hyprland configs for multi-monitor setup:

# GPU auto-detect (comment out explicit AQ_* settings)
cp ~/gentoo/hypr/ENVariables.conf ~/.config/hypr/UserConfigs/

# Triple monitor layout (customize for your setup)
cp ~/gentoo/hypr/monitors.conf ~/.config/hypr/

15) fingerprint - Fingerprint Authentication (Optional)

python setup.py fingerprint

Sets up the Elan fingerprint reader (04f3:0c4b) for authentication:

  1. Installs fprintd and libfprint packages
  2. Downloads Lenovo TOD driver (libfprint-2-tod1-elan.so)
  3. Enrolls fingerprints for user
  4. Configures PAM for SDDM and hyprlock

Usage after setup:

  • SDDM/hyprlock: Press Enter on empty password field to activate fingerprint
  • Enroll more fingers: fprintd-enroll -f <finger> <username>
  • Test: fprintd-verify <username>

Note: Fingerprint is configured as an alternative to password, not a replacement.

Utilities

Swap Management

python setup.py swap-on   # Activate encrypted swap
python setup.py swap-off  # Deactivate encrypted swap

Swap auto-activates during sync for heavy builds.

Quick Reference

Complete Installation Order

Pre-chroot (live environment):

disk → stage3 → config → fstab → chroot

Inside chroot:

sync → world → firmware → kernel → services → users → nvidia → bootloader

After reboot:

nmtui (connect WiFi) → su - <username> → emerge @hyprland → configure Hyprland

Troubleshooting

Command failed mid-way: Just run the same command again. All commands are idempotent and will skip completed steps.

Build OOM: Activate swap with python setup.py swap-on

Initramfs missing modules: Run python setup.py bootloader to verify

NVIDIA not loading: Check /etc/modprobe.d/ configs, rebuild initramfs with dracut --force

Firewall not active: Verify /var/lib/iptables/rules-save exists

USE flag / keyword changes: Handled automatically. The installer uses --autounmask-write and auto-dispatches config changes on retry.

Disk already partitioned: The disk command detects existing LUKS and offers to reuse it instead of reformatting.

WiFi not working after reboot: Ensure NetworkManager service is running (rc-service NetworkManager status). Check nmcli device to see if the WiFi adapter is recognized.

File Locations

Config Location
Portage /etc/portage/
Dracut /etc/dracut.conf.d/
Firewall rules /var/lib/iptables/rules-save
NVIDIA modprobe /etc/modprobe.d/nvidia.conf
GRUB /etc/default/grub
Shell config ~/.zshrc, ~/.config/starship.toml