nix-los/INDEX.md

Project Index

Quick reference to all files and their purposes.

Getting Started

Start here in this order:

1. README.md - Feature overview and quick start
2. SETUP.md - Step-by-step installation guide
3. QUICKREF.md - Command reference for daily use

Documentation

• README.md - Overview, features, directory structure, usage patterns
• SETUP.md - Detailed setup from scratch, per-scenario instructions
• QUICKREF.md - Command reference, common tasks, one-liners
• CUSTOMIZATION.md - Advanced patterns, extension examples
• ARCHITECTURE.md - Design principles, data flow, scalability
• INDEX.md - This file

Configuration Files

Core Configuration

• flake.nix - Main entry point
  • Defines all inputs (nixpkgs, home-manager, sops-nix, disko)
  • Specifies all outputs (nixosConfigurations, homeConfigurations)
  • Includes development shell and installer app
  • Requires customization: Replace youruser with actual username

Host Configurations (Per-Machine)

• hosts/laptop/default.nix - Laptop configuration template

  • Networking hostname
  • Disko disk partitioning
  • Development tools to enable
  • Requires customization: Hostname, disk device, language selection

• hosts/server/default.nix - Server configuration template

  • Minimal development tools
  • Same structure as laptop, customize as needed

NixOS System Modules (Shared)

• nixos/default.nix - System configuration entry point

  • Imports all modules
  • System packages (git, curl, vim, htop)
  • Nix settings, garbage collection, locale
  • Touch rarely: Mostly imports

• nixos/modules/system.nix - System base configuration

  • User creation (currently youruser - customize)
  • Sudo configuration
  • System state version
  • Options exposed: custom.system.enable

• nixos/modules/development.nix - Development tools module

  • Language-specific packages (rust, python, nodejs, go, ruby)
  • Build tools (gcc, cmake, gdb, etc)
  • Container support (docker/podman)
  • Options exposed: custom.development.enable, custom.development.languages
  • Example: Set languages = [ "rust" "python" ] to install

• nixos/modules/shell.nix - Shell configuration

  • Zsh, bash, fish support
  • Starship prompt, direnv integration
  • Options exposed: custom.shell.enable, custom.shell.defaultShell

• nixos/modules/secrets-example.nix - Secrets integration example

  • Shows how to use sops-nix for encrypted secrets
  • NOT imported by default
  • Uncomment in nixos/default.nix to enable
  • Reference for managing SSH keys, API tokens, passwords

• nixos/modules/example-template.nix - Template for new modules

  • Shows the module pattern: options + config
  • Copy and customize for new features

Home Manager User Configuration (Portable)

• home/default.nix - User configuration entry point

  • Imports all home modules
  • Home username, home directory, stateVersion
  • User-level packages (utilities, tools)
  • Environment variables
  • Requires customization: Username, email (in git.nix)

• home/modules/shell.nix - Shell environment

  • Zsh configuration (autosuggestion, syntax highlighting)
  • Shell aliases (ls → exa, cat → bat)
  • Starship prompt setup
  • Direnv integration for per-project shells
  • Zsh-z plugin for directory navigation

• home/modules/editor.nix - Editor configuration

  • Neovim as primary editor
  • LSP setup (language servers)
  • Plugins: telescope, lualine, treesitter, git integration
  • Alternative: VSCode (commented out)
  • Note: Basic config, customize for your needs

• home/modules/git.nix - Git configuration

  • Git username, email
  • Default branch, pull strategy
  • Common aliases (st, co, br, ci)
  • Requires customization: Your name and email

• home/modules/dev-tools.nix - Development utilities

  • Debuggers (lldb, gdb)
  • Version managers (fnm, pyenv)
  • Build tools (cmake, ninja, meson)
  • System utilities (tmux, htop, iotop)
  • Container tools (podman, podman-compose)
  • Tmux configuration with mouse support and vi keybindings

• home/modules/example-template.nix - Template for new user modules

  • Shows home-manager module pattern
  • Copy and customize for new user features

Secrets Management

• secrets/.sops.yaml - SOPS encryption configuration

  • Specifies which keys can decrypt secrets
  • Points to your age public key
  • Requires: Replace placeholder with your actual age public key

• secrets/secrets.yaml - Encrypted secrets file

  • SSH keys, API tokens, passwords
  • Encrypted with sops (safe to commit)
  • Usage: Edit with sops secrets/secrets.yaml
  • Never: Commit unencrypted version

Build & Deployment

No separate deployment files needed - everything flows through flake.nix:

flake.nix
  ├─ nixosConfigurations.laptop → Deploy with: sudo nixos-rebuild switch --flake .#laptop
  ├─ homeConfigurations.youruser@linux → Deploy with: home-manager switch --flake .#youruser@linux
  ├─ devShells.default → Enter with: nix develop
  └─ apps.installer → Run with: nix run .#installer -- laptop

Support Files

• .gitignore - Prevents committing secrets, temp files, nix artifacts
• flake.lock - COMMIT THIS: Pins all dependencies for reproducibility

Quick Navigation

"I want to..."

Task	File	Line	Command
Change my hostname	hosts/laptop/default.nix	8	sed -i 's/laptop/myname/' ...
Change my username	flake.nix	~40, 70	Global replace: "youruser"
Add a programming language	hosts/laptop/default.nix	35	Add to languages = [...]
Install new system package	nixos/default.nix	14	Add to systemPackages
Install new user package	home/default.nix	16	Add to home.packages
Change default shell	nixos/modules/shell.nix	11	Change defaultShell = "fish"
Add SSH key to secrets	secrets/secrets.yaml	8	sops secrets/secrets.yaml
Use unstable package	home/modules/dev-tools.nix	varies	Use pkgs-unstable.package
Create a new module	nixos/modules/example-template.nix	—	Copy template, customize
Add a new machine	hosts/	—	mkdir newhost && cp laptop/* newhost/

File Customization Checklist

On first setup, customize these:

• flake.nix - Replace all youruser (3 locations)
• hosts/laptop/default.nix - Set networking.hostName, verify /dev/sda disk
• home/default.nix - Set home.username
• home/modules/git.nix - Set userName and userEmail
• secrets/.sops.yaml - Add your age public key
• secrets/secrets.yaml - Add actual SSH keys and API tokens

File Statistics

• Documentation: 6 files (README, SETUP, QUICKREF, CUSTOMIZATION, ARCHITECTURE, INDEX)
• Configuration: 1 core file (flake.nix)
• System modules: 5 files (default, system, development, shell, secrets-example)
• Home modules: 6 files (default, shell, editor, git, dev-tools, example-template)
• Hosts: 2 example files (laptop, server)
• Secrets: 2 files (.sops.yaml, secrets.yaml)
• Support: 2 files (.gitignore, flake.lock)

Total: ~24 files, all under 500 lines each

Update Schedule

When to update inputs

# Monthly (security patches)
nix flake update nixpkgs
sudo nixos-rebuild switch --flake .#laptop

# Less frequently (minor version bumps)
nix flake update

# Test before committing
nix flake check
sudo nixos-rebuild test --flake .#laptop

When to add modules

Add modules when:

• Feature can be enabled/disabled independently
• Reused across multiple machines
• Follows the options + config pattern

Related Resources

• NixOS Manual: https://nixos.org/manual/nixos/stable
• Home Manager: https://nix-community.github.io/home-manager
• Nix Flakes: https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake
• sops-nix: https://github.com/mic92/sops-nix
• Disko: https://github.com/nix-community/disko

---

Next Step: Read README.md for a feature overview, then SETUP.md for installation instructions.