nixos-dotfiles/docs/QUICK_START.md

⚡ Quick Start Guide

Get up and running with this NixOS configuration in minutes!

🎯 Prerequisites

Before you begin, ensure you have:

• ✅ NixOS installed (tested on 25.11)
• ✅ Git installed
• ✅ Basic familiarity with terminal commands
• ✅ Admin (sudo) access

📥 Installation Steps

1. Backup Your Current Configuration

# Backup your current NixOS configuration
sudo cp -r /etc/nixos /etc/nixos.backup

# Backup your home directory configs (optional but recommended)
cp -r ~/.config ~/.config.backup

2. Clone This Repository

# Clone to your home directory
git clone https://github.com/BalrajSinghGidda/nixos-dotfiles ~/nixos-dotfiles
cd ~/nixos-dotfiles

3. Review and Customize

Important: Before applying, customize these files for your system:

Edit Host-Specific Settings

# Copy your hardware configuration
sudo cp /etc/nixos/hardware-configuration.nix ~/nixos-dotfiles/hosts/nixos-btw/

# Edit host settings if needed
nvim hosts/nixos-btw/configuration.nix

Update User Information

Edit modules/home-manager/git.nix:

user.name = "YourGitHubUsername";
user.email = "your-email@example.com";

Edit modules/nixos/core.nix:

users.users.balraj = {  # Change 'balraj' to your username
  isNormalUser = true;
  extraGroups = [ "wheel" "networking" ];
};

Edit hosts/nixos-btw/home.nix:

home.username = "your-username";
home.homeDirectory = "/home/your-username";

Update Hostname (Optional)

Edit modules/nixos/core.nix:

networking.hostName = "your-hostname";  # Change from "nixos-btw"

If you change the hostname, also update flake.nix:

nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
  # ...
};

4. Test the Configuration

# Dry-run to check for errors (doesn't apply changes)
sudo nixos-rebuild dry-build --flake ~/nixos-dotfiles/#nixos-btw

5. Apply the Configuration

# Apply the configuration
sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw

This will:

• Install all system packages
• Configure system services
• Set up Home Manager
• Link dotfiles to ~/.config

6. Reboot (Recommended)

sudo reboot

🎨 First Login

After reboot, you should see:

1. Login screen - Log in with your user credentials
2. Qtile WM - Tiled window manager with Tokyo Night theme
3. Terminal - Opens Kitty with custom theme
4. System info - nitch displays on shell startup

🔧 Post-Installation

Test Key Features

# Test Neovim
nvim

# Test file manager
yazi

# Test launcher (press: Mod + p in Qtile)
# Rofi should appear

# Check Git configuration
git config --list

# Test development shell creation
make-py-devshell my-project

Verify Services

# Check PipeWire audio
pactl info

# Check Bluetooth
bluetoothctl show

# Check Docker (rootless)
docker ps

📝 Making Changes

Update System Configuration

# Edit any .nix file
nvim ~/nixos-dotfiles/modules/nixos/packages.nix

# Apply changes
sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw

Update User Configuration

# Edit home-manager files
nvim ~/nixos-dotfiles/modules/home-manager/apps.nix

# Apply changes (same command as system)
sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw

Update Dotfiles

# Edit application configs
nvim ~/nixos-dotfiles/config/kitty/kitty.conf

# Changes apply immediately (or restart the application)

🚀 Useful Aliases

This configuration includes helpful aliases:

nc          # Quick edit nixos-dotfiles in Neovim
nrs         # Rebuild NixOS system
btw         # Echo "I use NixOS, btw"
ls          # Enhanced ls with icons and git status
cd          # Smart directory navigation with zoxide

❓ Common Issues

Issue: "error: flake not found"

Solution: Make sure you're in the correct directory or use full path:

sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw

Issue: Home Manager file conflicts

Solution: Home Manager creates backups. Check *.backup files:

ls ~/.config/*.backup

Remove or merge conflicts, then rebuild.

Issue: Graphics/display issues

Solution: Your hardware config may need adjustment:

# Copy your original hardware config
sudo cp /etc/nixos.backup/hardware-configuration.nix ~/nixos-dotfiles/hosts/nixos-btw/
sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw

Issue: Permission denied for Docker

Solution: Add yourself to docker group (already in services.nix):

# Re-login or run:
newgrp docker

🔄 Rolling Back

If something goes wrong:

# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

# Or boot into previous generation from bootloader
sudo reboot
# Select older generation from systemd-boot menu

📚 Next Steps

• Read ARCHITECTURE.md to understand the structure
• Check MODULE_GUIDE.md for customization details
• Explore individual configs in config/ directories
• Join the NixOS community: Discourse, Reddit

💡 Tips

1. Keep it in Git: Always commit changes before rebuilding
2. Test before switching: Use nixos-rebuild test for temporary changes
3. Update regularly: Run nix flake update to update dependencies
4. Read error messages: Nix errors are detailed and usually helpful
5. Start small: Make incremental changes and test frequently

---

🎉 Congratulations! You're now running a fully declarative NixOS setup!