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

```bash
# Configure network
net-setup
```

### 3. Verify DNS Resolution
```bash
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:
```bash
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
```bash
./install/chroot.sh
```

---

## Stage 2: Base System Configuration

### 6. Verify Network
```bash
ping -c 2 gentoo.org
```
If no network, check `/etc/resolv.conf` has valid nameservers.

### 7. Sync Portage & Select Profile
```bash
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:
```bash
emerge app-eselect/eselect-repository
eselect repository enable guru
emerge --sync
```

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

### 10. Install Firmware & Compile @world
```bash
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:
```bash
# 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
```bash
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
```bash
echo "<your-hostname>" > /etc/hostname
```

---

## Stage 3: Services & Kernel

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

### 15. Verify Dracut Configuration
```bash
ls -la /etc/dracut.conf.d/
# Should show: crypt.conf, nvidia.conf
```

If missing, create manually:
```bash
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
```bash
emerge sys-kernel/gentoo-kernel
# This will also take a while
# Dracut automatically includes NVIDIA modules in initramfs
```

### 17. Verify fstab and crypttab
```bash
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
```bash
passwd
```

### 19. Install Shell & Tools
```bash
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
```bash
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
```bash
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
```bash
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:
```bash
GRUB_CMDLINE_LINUX_DEFAULT="nvidia_drm.modeset=1 acpi_backlight=native"
GRUB_ENABLE_CRYPTODISK=y
```

Generate config:
```bash
grub-mkconfig -o /boot/grub/grub.cfg
```

### 23. Verify Initramfs Setup
```bash
# 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
```bash
rc-update show boot | grep -E "(dbus|elogind)"

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

### 25. Exit & Reboot
```bash
exit
umount -lR /mnt/gentoo
cryptsetup close cryptroot
reboot
# Remove installation media
```

**First Boot:**
1. GRUB loads, system prompts for LUKS passphrase
2. Enter your passphrase
3. System boots to greetd/regreet login screen

---

## Stage 6: Desktop Environment

### 26. Install Hyprland Desktop Set
```bash
# Login as your user
emerge @hyprland
```

### 27. Install KooL's Dotfiles

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

```bash
# 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
```bash
mkdir -p ~/.local/log
```

---

## Post-Installation

See the following guides for additional configuration:
- [Hybrid GPU Guide](hybrid-gpu.md) - AMD + NVIDIA configuration
- [greetd Setup](greetd-setup.md) - Display manager configuration
- [Troubleshooting](troubleshooting.md) - Common issues and fixes

### Quick Reference

**Update system:**
```bash
emerge --sync
emerge -avuDN @world
```

**Create snapshot before risky operation:**
```bash
sudo snapper create -d "before <operation>"
```

**Service management (OpenRC):**
```bash
rc-service <service> start|stop|restart|status
rc-update add|del <service> <runlevel>
loginctl reboot|poweroff|suspend  # NOT systemctl
```