nixos-dotfiles/docs/MODULE_GUIDE.md

📦 Module Guide

This guide explains each module in detail and how to customize them.

📑 Table of Contents

• NixOS Modules
  • core.nix
  • packages.nix
  • services.nix
  • wallpapers.nix
• Home Manager Modules
  • apps.nix
  • git.nix
  • shell.nix
  • devshell-scripts.nix

---

NixOS Modules

Located in modules/nixos/ - These require sudo to modify and affect the entire system.

core.nix

Purpose: Essential system configuration - boot, networking, users, and kernel modules.

What it does:

• Configures systemd-boot bootloader
• Sets hostname and enables NetworkManager
• Configures timezone
• Creates user accounts
• Enables Nix flakes
• Loads Dell-specific kernel modules

Common customizations:

# Change hostname
networking.hostName = "my-nixos-machine";

# Change timezone
time.timeZone = "America/New_York";

# Add a new user
users.users.newuser = {
  isNormalUser = true;
  extraGroups = [ "wheel" "networkmanager" ];
  packages = with pkgs; [ firefox chromium ];
};

# Add kernel modules
boot.kernelModules = [
  # ... existing modules
  "your-module"
];

Dependencies: None

---

packages.nix

Purpose: System-wide packages and fonts available to all users.

What it does:

• Installs essential CLI tools (git, vim, neovim, etc.)
• Installs GUI applications (kitty, rofi, libreoffice)
• Installs development tools (direnv, lazygit, etc.)
• Configures system fonts (Nerd Fonts, etc.)
• Includes custom wallpapers package

Package categories:

# Essential tools
vim wget git gh

# Terminal & multiplexers
kitty zellij tmux

# Window manager & desktop
picom rofi xwallpaper feh

# Development
direnv lazygit redis

# Utilities
brightnessctl pamixer blueman dunst maim slop

# Productivity
libreoffice

# System monitoring
nitch

Common customizations:

# Add new packages
environment.systemPackages = with pkgs; [
  # ... existing packages
  vscode
  discord
  spotify
];

# Add new fonts
fonts.packages = with pkgs; [
  # ... existing fonts
  nerd-fonts.fira-code
  google-fonts
];

# Remove packages you don't need
# Just comment out or delete the line

Dependencies: wallpapers.nix

---

services.nix

Purpose: System services and daemons - X11, audio, bluetooth, Docker, etc.

What it does:

• Enables X11 window system
• Configures Qtile window manager
• Sets up PipeWire (audio server)
• Enables PulseAudio compatibility
• Configures Bluetooth with experimental features
• Sets up rootless Docker
• Enables Flatpak support
• Configures Tailscale VPN

Service breakdown:

# Display server
services.xserver = {
  enable = true;
  xkb.layout = "us";
  windowManager.qtile = {
    enable = true;
    backend = "x11";
  };
};

# Audio stack
services.pipewire = {
  enable = true;
  alsa.enable = true;
  pulse.enable = true;
};

# Bluetooth
services.blueman.enable = true;
hardware.bluetooth = {
  enable = true;
  powerOnBoot = true;
  settings.General.Experimental = true;
};

# Container runtime
virtualisation.docker = {
  enable = true;
  rootless = {
    enable = true;
    setSocketVariable = true;
  };
};

# VPN
services.tailscale.enable = true;

# Package management
services.flatpak.enable = true;

Common customizations:

# Switch to Wayland
services.xserver.enable = false;  # Disable X11
programs.wayland.enable = true;

# Change window manager to i3
services.xserver.windowManager.i3.enable = true;
services.xserver.windowManager.qtile.enable = false;

# Disable Bluetooth
hardware.bluetooth.enable = false;
services.blueman.enable = false;

# Enable printing
services.printing.enable = true;

# Enable SSH server
services.openssh = {
  enable = true;
  settings.PermitRootLogin = "no";
};

# Add more audio codecs
services.pipewire.extraConfig.pipewire."92-low-latency" = {
  context.properties = {
    default.clock.rate = 48000;
    default.clock.quantum = 32;
  };
};

Dependencies: None

---

wallpapers.nix

Purpose: Custom package that bundles wallpaper images.

What it does:

• Creates a derivation containing wallpaper files
• Installs wallpapers to the Nix store
• Makes them available systemwide

Structure:

pkgs.stdenv.mkDerivation {
  name = "wallpapers";
  src = ./wallpapers/Pictures;
  installPhase = ''
    mkdir -p $out/share/wallpapers
    cp -r $src/* $out/share/wallpapers/
  '';
}

Usage:

# Wallpapers are located at:
/nix/store/.../share/wallpapers/

# Set with feh
feh --bg-scale /nix/store/.../share/wallpapers/nix.png

# Or use xwallpaper
xwallpaper --zoom /path/to/wallpaper.png

Adding wallpapers:

1. Place images in modules/nixos/wallpapers/Pictures/
2. Rebuild system
3. Wallpapers are now in the Nix store

Dependencies: None (but used by packages.nix)

---

Home Manager Modules

Located in modules/home-manager/ - User-level configuration, no sudo required.

apps.nix

Purpose: User packages and command-line tools.

What it does:

• Installs user-specific packages
• Configures Gemini CLI (AI assistant)
• Includes custom devshell scripts

Package categories:

home.packages = with pkgs; [
  # Code tools
  ripgrep nil nixpkgs-fmt nodejs gcc

  # File management
  yazi eza zoxide

  # Package management
  flatpak

  # Development
  python313Packages.euporie

  # Custom scripts
  devshell-scripts
];

Gemini CLI configuration:

programs.gemini-cli = {
  enable = true;
  settings = {
    theme = "Default";
    preferredEditor = "nvim";
    autoAccept = true;
  };
  defaultModel = "gemini-2.5-pro";
};

Common customizations:

# Add more packages
home.packages = with pkgs; [
  # ... existing packages
  neofetch
  htop
  btop
  
  # Language-specific tools
  rustc
  cargo
  go
  python311
];

# Configure Gemini CLI
programs.gemini-cli.settings = {
  theme = "Dark";
  defaultModel = "gemini-1.5-pro";
};

# Disable Gemini CLI
programs.gemini-cli.enable = false;

Dependencies: devshell-scripts.nix

---

git.nix

Purpose: Git and GitHub CLI configuration.

What it does:

• Configures Git user identity
• Enables GitHub CLI (gh)
• Sets up git credential helper
• Configures gh preferences

Current configuration:

programs.git = {
  enable = true;
  settings = {
    user.name = "BalrajSinghGidda";
    user.email = "anonystargamerz@gmail.com";
  };
};

programs.gh = {
  enable = true;
  gitCredentialHelper.enable = true;
  settings = {
    git_protocol = "https";
    prompt = "enable";
    editor = "nvim";
  };
};

Common customizations:

# Update user info (REQUIRED for your setup!)
programs.git.settings = {
  user.name = "YourUsername";
  user.email = "your-email@example.com";
};

# Add Git aliases
programs.git.settings.alias = {
  st = "status";
  co = "checkout";
  br = "branch";
  ci = "commit";
  unstage = "reset HEAD --";
};

# Configure default branch
programs.git.settings.init.defaultBranch = "main";

# Add signing
programs.git.settings.commit.gpgsign = true;
programs.git.settings.user.signingkey = "YOUR_GPG_KEY";

# Use SSH for GitHub
programs.gh.settings.git_protocol = "ssh";

Dependencies: None

---

shell.nix

Purpose: Bash shell environment - prompt, aliases, environment variables.

What it does:

• Configures Bash with completion
• Sets custom PS1 prompt
• Defines useful aliases
• Configures environment variables
• Integrates direnv and zoxide
• Shows nitch on startup

Shell aliases:

shellAliases = {
  nc = "nvim ~/nixos-dotfiles/.";
  btw = "echo I use NixOS, btw";
  nrs = "sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw";
  edit-config = "nvim ~/nixos-dotfiles/configuration.nix";
  edit-home-config = "nvim ~/nixos-dotfiles/home.nix";
  ls = "eza --long -ahF --no-user --no-permissions --git --icons=always --color=always --grid";
  cd = "z";
  bm = "bashmount";
};

Custom prompt:

• Cyan username@hostname
• Green current directory
• Light blue prompt symbol

Common customizations:

# Add more aliases
shellAliases = {
  # ... existing aliases
  ll = "ls -la";
  ".." = "cd ..";
  gs = "git status";
  gp = "git push";
  gl = "git pull";
  nv = "nvim";
  update = "nix flake update ~/nixos-dotfiles && nrs";
};

# Customize prompt
bashrcExtra = ''
  # Starship prompt (alternative)
  eval "$(starship init bash)"
  
  # Or custom prompt
  export PS1="\[\e[1;32m\]\u@\h \[\e[1;34m\]\w \[\e[1;31m\]\$ \[\e[0m\]"
'';

# Add environment variables
bashrcExtra = ''
  export EDITOR="nvim"
  export VISUAL="nvim"
  export BROWSER="firefox"
  export PATH="$HOME/.local/bin:$PATH"
'';

# Remove nitch startup
# Just delete or comment out the 'nitch' line in bashrcExtra

Dependencies: None (uses eza and zoxide from apps.nix)

---

devshell-scripts.nix

Purpose: Custom scripts for creating development environments.

What it does:

• Packages custom shell scripts
• Makes them available in PATH
• Provides commands for setting up dev environments

Available scripts:

• make-py-devshell - Python development environment
• make-cpp-devshell - C++ development environment
• make-go-devshell - Go development environment
• make-java-devshell - Java development environment
• make-ruby-devshell - Ruby development environment
• make-rust-devshell - Rust development environment

Structure:

pkgs.stdenv.mkDerivation {
  name = "devshell-scripts";
  src = ./devshell-scripts;
  installPhase = ''
    mkdir -p $out/bin
    cp -r $src/* $out/bin/
    chmod +x $out/bin/*
  '';
}

Usage:

# Create a Python project with dev environment
make-py-devshell my-python-project
cd my-python-project
direnv allow

# Create a Rust project
make-rust-devshell my-rust-project

Adding new scripts:

1. Create script in modules/home-manager/devshell-scripts/
2. Make it executable
3. Rebuild Home Manager

Dependencies: None (but scripts use direnv from apps.nix)

---

🔗 Module Dependencies

flake.nix
  ├── hosts/nixos-btw/default.nix
  │   ├── configuration.nix
  │   ├── hardware-configuration.nix
  │   └── modules/nixos/
  │       ├── core.nix
  │       ├── packages.nix (uses wallpapers.nix)
  │       ├── services.nix
  │       └── wallpapers.nix
  │
  └── home-manager
      ├── hosts/nixos-btw/home.nix
      └── modules/home-manager/
          ├── apps.nix (uses devshell-scripts.nix)
          ├── git.nix
          ├── shell.nix
          └── devshell-scripts.nix

🎯 Best Practices

1. Keep modules focused: Each module should handle one domain
2. Comment your changes: Future you will thank present you
3. Test incrementally: Make small changes and test frequently
4. Use meaningful names: If you split a module, name it descriptively
5. Document customizations: Add comments explaining why you made changes

🚀 Creating New Modules

NixOS Module Template

# modules/nixos/my-module.nix
{ config, pkgs, ... }:

{
  # Your system-level configuration here
  environment.systemPackages = with pkgs; [
    # packages
  ];
  
  services.my-service = {
    enable = true;
    # configuration
  };
}

Then add to modules/nixos/default.nix:

{
  imports = [
    # ... existing imports
    ./my-module.nix
  ];
}

Home Manager Module Template

# modules/home-manager/my-module.nix
{ config, pkgs, ... }:

{
  # Your user-level configuration here
  home.packages = with pkgs; [
    # packages
  ];
  
  programs.my-program = {
    enable = true;
    # configuration
  };
}

Then add to modules/home-manager/default.nix:

{
  imports = [
    # ... existing imports
    ./my-module.nix
  ];
}

---

Happy customizing! 🎉