gentoo-legion-python/procedure.md

# 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:

```bash
# 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:

```bash
# 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`.

```bash
# Configure network
net-setup

# Verify DNS
ping -c 2 gentoo.org
```

### 3. Clone Repository

```bash
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:

```bash
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:**
```bash
python setup.py all
```

---

## Stage 2: Base System (Inside Chroot)

After entering chroot, clone the repo:

```bash
# 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

```bash
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

```bash
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:

```bash
nmtui
```

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

Or via command line:

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

Verify connectivity:

```bash
ping -c 2 gentoo.org
```

### Clone Repository (as user)

Switch to your user account and clone the repo:

```bash
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):

```bash
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:
```bash
# 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)

```bash
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

```bash
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 |