gentoo-legion/README.md

# Gentoo Legion

Complete Gentoo Linux installation with Hyprland, greetd, and hybrid GPU support for Lenovo Legion laptops and similar AMD + NVIDIA setups.

## About

This represents my third attempt at getting Gentoo running properly on this laptop with my preferred Hyprland setup. The hybrid GPU setup was the main challenge - particularly understanding how the USB-C ports route through the NVIDIA GPU while the laptop panel connects to the AMD iGPU. Once that clicked, everything fell into place.

The result is a lean system that idles under 2GB of RAM while still providing a full Hyprland desktop. I opted for the distribution kernel (`gentoo-kernel`) rather than a custom compile - it works out of the box with the hardware and saves hours of configuration.

Your mileage may vary - I tried to isolate as many of the use flags as I could

## Features

- **Full disk encryption** - LUKS2 with Btrfs subvolumes
- **Hybrid GPU support** - AMD iGPU + NVIDIA dGPU working together
- **Hyprland desktop** - Modern Wayland compositor with greetd + regreet login
- **OpenRC init** - Traditional init system, no systemd
- **Automated installation** - Scripts for disk setup, chroot, and service configuration

## Hardware Tested

**Lenovo Legion S7 15ACH6**
- AMD Ryzen 9 5900HX (Zen 3, 16 threads)
- AMD Radeon Vega (Cezanne) - integrated GPU
- NVIDIA GeForce RTX 3050 Ti Mobile - discrete GPU
- 24GB DDR4 RAM (THIS IS AN UPGRADE FROM STANDARD! 8GB ON THIS MODEL IS SOLDERED)
- NVMe SSD with LUKS2 encryption

This configuration should work with other Legion models and similar AMD + NVIDIA hybrid laptops with minor adjustments.

## Quick Start

1. Boot Gentoo minimal install ISO
2. Clone this repository:
   ```bash
   git clone https://github.com/<user>/gentoo-legion
   cd gentoo-legion
   ```
3. Follow the [Installation Guide](docs/installation.md)

## Directory Structure

```
gentoo-legion/
├── docs/                    # Documentation
│   ├── installation.md      # Full installation guide
│   ├── hybrid-gpu.md        # AMD+NVIDIA GPU configuration
│   ├── greetd-setup.md      # Display manager setup
│   └── troubleshooting.md   # Common issues and fixes
├── install/                 # Installation scripts
│   ├── init.sh              # Stage 1: Disk partitioning, LUKS, Btrfs
│   ├── chroot.sh            # Chroot helper script
│   └── services.sh          # Stage 3: Service configuration
├── portage/                 # Portage configuration → /etc/portage/
│   ├── make.conf            # Compiler flags, USE flags
│   ├── package.use/         # Package-specific USE flags
│   ├── package.accept_keywords/  # ~amd64 keywords
│   ├── package.license/     # License acceptance
│   └── sets/                # Package sets (@hyprland)
├── system/                  # System configuration
│   ├── ccache.conf          # Compiler cache config
│   ├── dracut.conf.d/       # Initramfs configuration
│   └── conf.d/              # OpenRC service configs
├── greetd/                  # Display manager configuration
│   ├── config.toml          # greetd main config
│   ├── regreet.toml         # GTK greeter theming
│   ├── hyprland.conf        # Greeter Hyprland session
│   ├── greetd.pam           # PAM configuration
│   └── start-hyprland-dbus  # User session launcher
├── firewall/                # iptables rules
│   ├── iptables.rules.example   # IPv4 rules (customize)
│   └── ip6tables.rules      # IPv6 rules
├── hypr/                    # Hyprland configuration
│   ├── ENVariables.conf     # GPU environment variables
│   ├── monitors.conf.example    # Monitor layout (customize)
│   └── wlogout-layout       # Power menu for OpenRC
└── shell/                   # Shell configuration
    ├── zshrc.example        # Zsh config (customize)
    └── starship.toml        # Starship prompt theme
```

## Configuration Categories

### Copy As-Is
These files can be copied directly to your system:

| Source | Destination |
|--------|-------------|
| `portage/*` | `/etc/portage/` |
| `system/ccache.conf` | `/etc/ccache.conf` |
| `system/dracut.conf.d/*` | `/etc/dracut.conf.d/` |
| `system/conf.d/{iptables,ip6tables,snapper}` | `/etc/conf.d/` |
| `greetd/*` | `/etc/greetd/` (and `/etc/pam.d/greetd`) |
| `firewall/ip6tables.rules` | `/etc/iptables/` |
| `shell/starship.toml` | `~/.config/starship.toml` |

### Customize Before Use
These files need editing for your system:

| File | What to customize |
|------|-------------------|
| `system/conf.d/dmcrypt.example` | Set your swap partition device |
| `firewall/iptables.rules.example` | Add your trusted networks |
| `hypr/monitors.conf.example` | Configure your display layout |
| `shell/zshrc.example` | Add your aliases, paths, etc. |

## Key Technologies

- **Compositor**: [Hyprland](https://hyprland.org/) with [KooL's dotfiles](https://github.com/JaKooLit/Hyprland-Dots)
- **Display Manager**: [greetd](https://sr.ht/~kennylevinsen/greetd/) + [regreet](https://github.com/rharish101/ReGreet)
- **Init System**: OpenRC
- **Filesystem**: Btrfs with zstd compression
- **Encryption**: LUKS2 (dm-crypt)
- **Snapshots**: Snapper for system rollback
- **Shell**: Zsh with Starship prompt

## Documentation

- [Installation Guide](docs/installation.md) - Complete step-by-step installation
- [Hybrid GPU Guide](docs/hybrid-gpu.md) - AMD + NVIDIA configuration
- [greetd Setup](docs/greetd-setup.md) - Display manager configuration
- [Troubleshooting](docs/troubleshooting.md) - Common issues and fixes

## Btrfs Subvolume Layout

| Subvolume | Mount Point | Purpose |
|-----------|-------------|---------|
| @ | / | Root filesystem |
| @home | /home | User data |
| @var | /var | Variable data |
| @log | /var/log | System logs |
| @snapshots | /.snapshots | Snapper backups |

## OpenRC Services

**Boot runlevel:** dbus, elogind, dmcrypt

**Default runlevel:** sysklogd, sshd, NetworkManager, chronyd, cronie, power-profiles-daemon, display-manager, bluetooth, iptables, ip6tables

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test your changes on actual hardware if possible
4. Submit a pull request

## License

MIT License - See [LICENSE](LICENSE)

## Acknowledgments

- [JaKooLit](https://github.com/JaKooLit) for Hyprland dotfiles
- [Gentoo Wiki](https://wiki.gentoo.org/) for comprehensive documentation
- [Hyprland](https://hyprland.org/) for the compositor
- The Gentoo and Hyprland communities