mirror of
https://github.com/BalrajSinghGidda/nixos-dotfiles.git
synced 2026-04-07 09:27:23 +00:00
Major restructure: Add comprehensive documentation, modular Home Manager, and helper files
This commit is contained in:
BalrajSinghGidda
164
docs/ARCHITECTURE.md
Normal file
164
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 🏗️ Architecture Overview
|
||||
|
||||
This document explains how the NixOS dotfiles repository is organized and how the different components work together.
|
||||
|
||||
## 📂 Directory Structure
|
||||
|
||||
```
|
||||
nixos-dotfiles/
|
||||
├── flake.nix # Main entry point - defines inputs and system configuration
|
||||
├── flake.lock # Locked versions of dependencies
|
||||
│
|
||||
├── hosts/ # Host-specific configurations
|
||||
│ └── nixos-btw/ # Configuration for the "nixos-btw" machine
|
||||
│ ├── default.nix # Host entry point - imports all host configs
|
||||
│ ├── configuration.nix # Host-specific system settings (currently minimal)
|
||||
│ ├── hardware-configuration.nix # Hardware-specific settings (auto-generated)
|
||||
│ └── home.nix # Home Manager configuration for this host
|
||||
│
|
||||
├── modules/ # Reusable configuration modules
|
||||
│ ├── nixos/ # System-level NixOS modules
|
||||
│ │ ├── default.nix # Imports all NixOS modules
|
||||
│ │ ├── core.nix # Core system settings (boot, networking, users)
|
||||
│ │ ├── packages.nix # System-wide packages and fonts
|
||||
│ │ ├── services.nix # System services (X11, audio, bluetooth, etc.)
|
||||
│ │ ├── wallpapers.nix # Custom wallpapers package
|
||||
│ │ └── wallpapers/ # Wallpaper files
|
||||
│ │
|
||||
│ └── home-manager/ # User-level Home Manager modules
|
||||
│ ├── default.nix # Imports all Home Manager modules
|
||||
│ ├── apps.nix # User applications and tools
|
||||
│ ├── git.nix # Git and GitHub CLI configuration
|
||||
│ ├── shell.nix # Bash shell configuration
|
||||
│ ├── devshell-scripts.nix # Custom development shell scripts
|
||||
│ └── devshell-scripts/ # Shell script implementations
|
||||
│
|
||||
└── config/ # Application dotfiles (managed via Home Manager)
|
||||
├── nvim/ # Neovim configuration
|
||||
├── qtile/ # Qtile window manager configuration
|
||||
├── rofi/ # Rofi launcher configuration
|
||||
├── picom/ # Picom compositor configuration
|
||||
└── kitty/ # Kitty terminal configuration
|
||||
```
|
||||
|
||||
## 🔄 Configuration Flow
|
||||
|
||||
### System Build Process
|
||||
|
||||
1. **Entry Point**: `flake.nix`
|
||||
- Defines NixOS and Home Manager as inputs
|
||||
- Creates `nixosConfigurations.nixos-btw` configuration
|
||||
|
||||
2. **Host Configuration**: `hosts/nixos-btw/default.nix`
|
||||
- Imports hardware configuration
|
||||
- Imports shared NixOS modules from `modules/nixos/`
|
||||
|
||||
3. **NixOS Modules**: `modules/nixos/`
|
||||
- **core.nix**: Boot loader, networking, timezone, users
|
||||
- **packages.nix**: System packages, fonts
|
||||
- **services.nix**: X11, audio (PipeWire), Bluetooth, Docker, etc.
|
||||
|
||||
4. **Home Manager**: Integrated in `flake.nix`
|
||||
- User configuration from `hosts/nixos-btw/home.nix`
|
||||
- Imports modules from `modules/home-manager/`
|
||||
|
||||
5. **Home Manager Modules**: `modules/home-manager/`
|
||||
- **apps.nix**: User packages and CLI tools
|
||||
- **git.nix**: Git and GitHub configuration
|
||||
- **shell.nix**: Bash prompt, aliases, environment variables
|
||||
|
||||
6. **Dotfiles**: Managed in `hosts/nixos-btw/home.nix`
|
||||
- Configs symlinked from `config/` to `~/.config/`
|
||||
|
||||
## 🎯 Design Principles
|
||||
|
||||
### Modularity
|
||||
- Each module handles a specific domain (core system, packages, services, etc.)
|
||||
- Modules are reusable across different hosts
|
||||
- Easy to enable/disable features by commenting imports
|
||||
|
||||
### Separation of Concerns
|
||||
- **System-level** (modules/nixos/): Requires root, affects all users
|
||||
- **User-level** (modules/home-manager/): Per-user configuration
|
||||
- **Host-specific** (hosts/): Machine-specific settings
|
||||
- **Application configs** (config/): Dotfiles for specific programs
|
||||
|
||||
### Declarative Configuration
|
||||
- Everything is defined in Nix expressions
|
||||
- Reproducible across machines
|
||||
- Version-controlled and atomic updates
|
||||
|
||||
## 🔌 Key Components
|
||||
|
||||
### Flakes
|
||||
This configuration uses Nix flakes for:
|
||||
- Dependency management (pinned versions in `flake.lock`)
|
||||
- Reproducible builds
|
||||
- Easy sharing and composition
|
||||
|
||||
### Home Manager
|
||||
Manages user environment:
|
||||
- User packages
|
||||
- Dotfiles and configurations
|
||||
- Shell environment
|
||||
- Program-specific settings
|
||||
|
||||
### Custom Packages
|
||||
- **wallpapers**: Custom package bundling wallpaper images
|
||||
- **devshell-scripts**: Custom scripts for creating development environments
|
||||
|
||||
## 🚀 Adding New Features
|
||||
|
||||
### Add a System Package
|
||||
Edit `modules/nixos/packages.nix`:
|
||||
```nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
# ... existing packages
|
||||
your-new-package
|
||||
];
|
||||
```
|
||||
|
||||
### Add a User Package
|
||||
Edit `modules/home-manager/apps.nix`:
|
||||
```nix
|
||||
home.packages = with pkgs; [
|
||||
# ... existing packages
|
||||
your-new-package
|
||||
];
|
||||
```
|
||||
|
||||
### Add a System Service
|
||||
Edit `modules/nixos/services.nix`:
|
||||
```nix
|
||||
services.your-service = {
|
||||
enable = true;
|
||||
# ... configuration
|
||||
};
|
||||
```
|
||||
|
||||
### Add a New Module
|
||||
1. Create `modules/nixos/your-module.nix` or `modules/home-manager/your-module.nix`
|
||||
2. Add to respective `default.nix`:
|
||||
```nix
|
||||
imports = [
|
||||
# ... existing imports
|
||||
./your-module.nix
|
||||
];
|
||||
```
|
||||
|
||||
## 🔍 Understanding the Build
|
||||
|
||||
When you run `sudo nixos-rebuild switch --flake .#nixos-btw`:
|
||||
|
||||
1. Nix reads `flake.nix`
|
||||
2. Looks up `nixosConfigurations.nixos-btw`
|
||||
3. Evaluates all imported modules
|
||||
4. Builds the system closure
|
||||
5. Activates the new configuration
|
||||
6. Home Manager runs and sets up user environment
|
||||
|
||||
## 📚 Further Reading
|
||||
|
||||
- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
|
||||
- [Home Manager Manual](https://nix-community.github.io/home-manager/)
|
||||
- [Nix Flakes](https://nixos.wiki/wiki/Flakes)
|
||||
617
docs/MODULE_GUIDE.md
Normal file
617
docs/MODULE_GUIDE.md
Normal file
@@ -0,0 +1,617 @@
|
||||
# 📦 Module Guide
|
||||
|
||||
This guide explains each module in detail and how to customize them.
|
||||
|
||||
## 📑 Table of Contents
|
||||
|
||||
- [NixOS Modules](#nixos-modules)
|
||||
- [core.nix](#corenix)
|
||||
- [packages.nix](#packagesnix)
|
||||
- [services.nix](#servicesnix)
|
||||
- [wallpapers.nix](#wallpapersnix)
|
||||
- [Home Manager Modules](#home-manager-modules)
|
||||
- [apps.nix](#appsnix)
|
||||
- [git.nix](#gitnix)
|
||||
- [shell.nix](#shellnix)
|
||||
- [devshell-scripts.nix](#devshell-scriptsnix)
|
||||
|
||||
---
|
||||
|
||||
## 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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
```nix
|
||||
pkgs.stdenv.mkDerivation {
|
||||
name = "wallpapers";
|
||||
src = ./wallpapers/Pictures;
|
||||
installPhase = ''
|
||||
mkdir -p $out/share/wallpapers
|
||||
cp -r $src/* $out/share/wallpapers/
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```nix
|
||||
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**:
|
||||
```nix
|
||||
programs.gemini-cli = {
|
||||
enable = true;
|
||||
settings = {
|
||||
theme = "Default";
|
||||
preferredEditor = "nvim";
|
||||
autoAccept = true;
|
||||
};
|
||||
defaultModel = "gemini-2.5-pro";
|
||||
};
|
||||
```
|
||||
|
||||
**Common customizations**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
```nix
|
||||
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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
```nix
|
||||
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**:
|
||||
|
||||
```nix
|
||||
# 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**:
|
||||
```nix
|
||||
pkgs.stdenv.mkDerivation {
|
||||
name = "devshell-scripts";
|
||||
src = ./devshell-scripts;
|
||||
installPhase = ''
|
||||
mkdir -p $out/bin
|
||||
cp -r $src/* $out/bin/
|
||||
chmod +x $out/bin/*
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```nix
|
||||
# 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`:
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
# ... existing imports
|
||||
./my-module.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Home Manager Module Template
|
||||
|
||||
```nix
|
||||
# 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`:
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
# ... existing imports
|
||||
./my-module.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Happy customizing! 🎉
|
||||
264
docs/QUICK_START.md
Normal file
264
docs/QUICK_START.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# ⚡ 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
```nix
|
||||
user.name = "YourGitHubUsername";
|
||||
user.email = "your-email@example.com";
|
||||
```
|
||||
|
||||
Edit `modules/nixos/core.nix`:
|
||||
```nix
|
||||
users.users.balraj = { # Change 'balraj' to your username
|
||||
isNormalUser = true;
|
||||
extraGroups = [ "wheel" "networking" ];
|
||||
};
|
||||
```
|
||||
|
||||
Edit `hosts/nixos-btw/home.nix`:
|
||||
```nix
|
||||
home.username = "your-username";
|
||||
home.homeDirectory = "/home/your-username";
|
||||
```
|
||||
|
||||
#### Update Hostname (Optional)
|
||||
|
||||
Edit `modules/nixos/core.nix`:
|
||||
```nix
|
||||
networking.hostName = "your-hostname"; # Change from "nixos-btw"
|
||||
```
|
||||
|
||||
If you change the hostname, also update `flake.nix`:
|
||||
```nix
|
||||
nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
|
||||
# ...
|
||||
};
|
||||
```
|
||||
|
||||
### 4. Test the Configuration
|
||||
|
||||
```bash
|
||||
# Dry-run to check for errors (doesn't apply changes)
|
||||
sudo nixos-rebuild dry-build --flake ~/nixos-dotfiles/#nixos-btw
|
||||
```
|
||||
|
||||
### 5. Apply the Configuration
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check PipeWire audio
|
||||
pactl info
|
||||
|
||||
# Check Bluetooth
|
||||
bluetoothctl show
|
||||
|
||||
# Check Docker (rootless)
|
||||
docker ps
|
||||
```
|
||||
|
||||
## 📝 Making Changes
|
||||
|
||||
### Update System Configuration
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Edit application configs
|
||||
nvim ~/nixos-dotfiles/config/kitty/kitty.conf
|
||||
|
||||
# Changes apply immediately (or restart the application)
|
||||
```
|
||||
|
||||
## 🚀 Useful Aliases
|
||||
|
||||
This configuration includes helpful aliases:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
|
||||
```
|
||||
|
||||
### Issue: Home Manager file conflicts
|
||||
|
||||
**Solution**: Home Manager creates backups. Check `*.backup` files:
|
||||
```bash
|
||||
ls ~/.config/*.backup
|
||||
```
|
||||
|
||||
Remove or merge conflicts, then rebuild.
|
||||
|
||||
### Issue: Graphics/display issues
|
||||
|
||||
**Solution**: Your hardware config may need adjustment:
|
||||
```bash
|
||||
# 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):
|
||||
```bash
|
||||
# Re-login or run:
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
## 🔄 Rolling Back
|
||||
|
||||
If something goes wrong:
|
||||
|
||||
```bash
|
||||
# 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](./ARCHITECTURE.md) to understand the structure
|
||||
- Check [MODULE_GUIDE.md](./MODULE_GUIDE.md) for customization details
|
||||
- Explore individual configs in `config/` directories
|
||||
- Join the NixOS community: [Discourse](https://discourse.nixos.org/), [Reddit](https://reddit.com/r/nixos)
|
||||
|
||||
## 💡 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!
|
||||
Reference in New Issue
Block a user