# NixOS + Hyprland Configuration - Project Overview

## 🎯 What This Is

This is a complete, production-ready NixOS configuration featuring Hyprland as a Wayland compositor. Everything is declared in code, making your entire operating system reproducible from a fresh install with a single command.

## 📦 What You're Getting

### Core System
- **NixOS** with Flakes enabled for reproducible builds
- **Hyprland** - Modern Wayland compositor with beautiful animations
- **Home Manager** - Declarative user environment management
- **Full Wayland Support** with XWayland fallback

### Desktop Environment
- **Waybar** - Highly customizable status bar
- **Wofi** - Application launcher
- **Dunst** - Notification daemon
- **Hyprpaper** - Wallpaper manager
- **SWWW** - Alternative animated wallpaper daemon

### Tools & Applications
- **Kitty & Alacritty** - Modern GPU-accelerated terminals
- **ZSH** with Oh-My-Zsh - Enhanced shell experience
- **Firefox** - Web browser
- **VSCode** - Code editor
- **Thunar** - File manager
- **Modern CLI tools** - ripgrep, fd, bat, eza, fzf, etc.

### System Features
- PipeWire audio system
- NetworkManager for networking
- Bluetooth support
- Printing support (CUPS)
- SSH server
- Graphics drivers setup

## 📁 File Structure Explained

```
nixos-config/
├── flake.nix                   # Main entry point - defines all inputs and outputs
├── configuration.nix           # System-wide settings (bootloader, networking, users)
├── hardware-configuration.nix  # Auto-generated hardware-specific settings
│
├── modules/
│   ├── system.nix             # System packages and essential services
│   └── hyprland.nix           # Hyprland system-level configuration
│
├── home/
│   ├── home.nix               # User packages and general home-manager config
│   ├── hyprland.nix           # Hyprland user settings, keybindings, appearance
│   └── waybar.nix             # Status bar configuration and styling
│
├── bootstrap.sh               # Automated setup script for fresh installs
├── README.md                  # Comprehensive documentation
├── SETUP.md                   # Quick setup guide
└── KEYBINDINGS.md            # Keyboard shortcuts reference
```

## 🚀 Quick Start Workflow

### 1. Push to Your Git Server
```bash
cd nixos-config
git init
git add .
git commit -m "Initial NixOS configuration"
git remote add origin https://git.cribdev.com/YOUR-USERNAME/nixos-config.git
git push -u origin main
```

### 2. Fresh Install (On New Machine)
```bash
# One command to rule them all
nix-shell -p git --run "bash <(curl -s https://git.cribdev.com/raw/YOUR-USERNAME/nixos-config/main/bootstrap.sh)"
```

### 3. What the Bootstrap Does
1. Installs git temporarily
2. Clones your configuration
3. Copies hardware-configuration.nix
4. Prompts for hostname and username
5. Updates configuration files
6. Optionally builds the system immediately

### 4. Result
After reboot, you have a fully configured system with Hyprland!

## 🔧 Customization Points

### Before First Push

1. **Edit `flake.nix`:**
   - Change hostname from "myhost"
   - Change username from "yourusername"

2. **Edit `configuration.nix`:**
   - Set your timezone (currently Europe/Oslo)
   - Adjust locale settings
   - Configure your user account

3. **Edit `home/home.nix`:**
   - Set git username and email
   - Add/remove packages you want

4. **Edit `home/hyprland.nix`:**
   - Customize keybindings
   - Adjust colors and appearance
   - Configure monitor settings

5. **Edit `bootstrap.sh`:**
   - Update the GIT_REPO variable with your actual git URL

### After Installation

You can always modify the configuration and rebuild:
```bash
cd ~/.config/nixos
# Make your changes
sudo nixos-rebuild switch --flake .#HOSTNAME
```

Or use the convenient alias after first build:
```bash
update
```

## 🎨 Ricing Capabilities

This configuration includes extensive customization options:

### Visual Customization
- **Window Decorations**: Rounded corners, borders, shadows
- **Animations**: Smooth transitions and effects
- **Colors**: Fully customizable color schemes
- **Transparency**: Blur effects and opacity settings
- **Status Bar**: Custom Waybar themes

### Included Ricing Tools
- Hyprpaper (wallpapers)
- SWWW (animated wallpapers)
- Waybar (customizable bar)
- Dunst (notification styling)
- Wofi (launcher themes)
- GTK/Qt theme support

### Where to Customize
- **Colors**: `home/hyprland.nix` (general section)
- **Waybar Style**: `home/waybar.nix` (style section)
- **Animations**: `home/hyprland.nix` (animations section)
- **Terminal**: `home/home.nix` (kitty settings)

## 🔑 Key Features

### Declarative
Everything is code. No hidden state. Reproducible across machines.

### Atomic Updates
Changes are atomic - either they work completely or rollback automatically.

### Rollback Capability
Every build creates a generation. Easy to rollback if something breaks.

### Reproducible
Same configuration = same system, regardless of when/where you build.

### Version Controlled
Your entire OS is in git. Fork it, branch it, merge configurations.

## 📚 Next Steps

1. **Personalize** the configuration files
2. **Push** to your git server
3. **Install** NixOS on target machine
4. **Run** bootstrap script
5. **Enjoy** your custom system!

## 🐛 Troubleshooting

### Common Issues

**Hyprland won't start**
- Check logs: `journalctl -xe`
- Verify GPU drivers in `hardware-configuration.nix`

**Monitor configuration wrong**
- Edit `home/hyprland.nix` monitor settings
- Use `hyprctl monitors` to see detected monitors

**Packages not found**
- Update flake: `nix flake update`
- Rebuild: `sudo nixos-rebuild switch --flake .#HOSTNAME`

**Need different keyboard layout**
- Edit `home/hyprland.nix` input section
- Change `kb_layout` value

## 🎓 Learning Resources

- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
- [Hyprland Wiki](https://wiki.hyprland.org/)
- [Home Manager Docs](https://nix-community.github.io/home-manager/)
- [NixOS Search](https://search.nixos.org/) - Find packages

## 🌟 Why This Approach?

**Traditional Linux Setup:**
- Install OS
- Install packages one by one
- Configure everything manually
- Hope you documented it
- Pray when setting up a new machine

**This NixOS Setup:**
- Install NixOS (minimal)
- Run one command
- Get coffee ☕
- Everything configured automatically
- Reproducible on any machine

## 💡 Pro Tips

1. **Always commit changes** before rebuilding
2. **Test on a VM first** for major changes
3. **Keep hardware-configuration.nix** separate per machine
4. **Use branches** for experimental configurations
5. **Document** your customizations in comments

---

**You now have a fully declarative, reproducible, version-controlled operating system! 🎉**

Any questions or issues? Check the README.md for detailed information.