nixos-config/PROJECT_OVERVIEW.md

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

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)

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

cd ~/.config/nixos
# Make your changes
sudo nixos-rebuild switch --flake .#HOSTNAME

Or use the convenient alias after first build:

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
• Hyprland Wiki
• Home Manager Docs
• NixOS Search - 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.