Skip to content

Latest commit

 

History

History
132 lines (96 loc) · 5.14 KB

README.org

File metadata and controls

132 lines (96 loc) · 5.14 KB

/etc/nixos – Repository Layout Guide

Overview

This repo is structured to keep machine-wide (system) configuration separate from user-level (home) configuration, while still allowing host-specific overrides.

High-level rule of thumb:

  • NixOS (system): anything that affects the whole machine (services, drivers, desktop, system packages, users/groups, hardware).
  • Home Manager (user): anything that lives in $HOME (shell config, git config, CLI toolbox, per-user app settings).

Directory map

hosts

Per-machine configuration. Each host gets its own directory.

  • hosts/nomad/configuration.nix Host-specific NixOS settings (hostname, networking quirks, device-specific settings, host-specific enables/disables, etc.).
  • hosts/nomad/hardware-configuration.nix Hardware autodetected config generated by NixOS (filesystems, initrd modules, etc.). Treat this as host-specific and avoid “hand-tuning” unless you know why.

Add a new machine by creating hosts/<hostname>/{configuration.nix,hardware-configuration.nix} and adding it to flake.nix under nixosConfigurations.

modules

Reusable NixOS modules that define “roles” or “shared machine behavior”.

  • modules/common.nix Shared system defaults used by all hosts (time zone, locale, nix settings, common services, etc.).
  • modules/desktop-kde.nix Desktop role module (KDE + display manager + desktop services).
  • modules/packages.nix (SYSTEM packages) Machine-wide packages: think GUI apps, admin tools, workstation-wide utilities. Use this for packages that should exist regardless of which user is logged in.

    Good examples:

    • GUI apps you want available system-wide (CAD tools, IDEs, emulators)
    • System/admin tooling (things you might want available in root contexts)
    • Hardware/programmer tools you want on the whole machine

    Try not to put “my personal CLI toolbox” here—put that in Home Manager.

  • modules/user-angelo.nix (SYSTEM user account) Defines the user account (groups, sudo/wheel access, etc.). Keep this file focused on account creation + group membership. Avoid personal dotfiles or large per-user package lists here; those belong in Home Manager.

home

Home Manager configs. Everything here is user-scoped and intended to be reproducible across machines.

  • home/angelo/default.nix Entry point for Angelo’s Home Manager config. Imports the rest of the user modules.
  • home/angelo/packages.nix (USER packages) Angelo’s CLI/dev toolbox (per-user packages). Use this for tools you want as part of your everyday environment:
    • CLI utilities (rg, fd, jq, curl, htop, etc.)
    • Dev tools (uv, gh, language runtimes, formatters, linters)
    • Things that primarily operate in $HOME or your project dirs

    This complements modules/packages.nix:

    • modules/packages.nix = machine-wide / GUI / admin tools
    • home/angelo/packages.nix = personal CLI/dev toolbox
  • home/angelo/git.nix Git configuration (name/email, aliases, line ending policy, defaults). No secrets should be committed here.
  • home/angelo/direnv.nix Enables direnv + nix-direnv for “auto enter devshell” workflows. Typical project pattern: an .envrc containing use flake.
  • home/angelo/bash.nix Bash setup: aliases, prompt tweaks, environment variables, completion.
  • home/angelo/shell.nix Optional “shell-agnostic” settings. If unused or duplicated with bash.nix, consider consolidating.

Top-level files

  • flake.nix / flake.lock Main entry point. Wires together:
    • the NixOS system modules (/modules)
    • each host under /hosts
    • Home Manager for the user under /home
  • configuration.nix / hardware-configuration.nix (top-level) Often leftover from pre-flake setups. If nothing imports these, they’re redundant and can be removed or kept only for reference.

Workflows / commands

Rebuild the system (NixOS + Home Manager as a NixOS module)

From /etc/nixos:

sudo nixos-rebuild switch --flake /etc/nixos#nomad

This applies:

  • NixOS system changes (modules + host config)
  • Home Manager changes for Angelo (because HM is integrated as a NixOS module)

Update flake inputs (nixpkgs / home-manager)

nix flake update
sudo nixos-rebuild switch --flake /etc/nixos#nomad

Check what config file “wins” for git

Git may read both $HOME/.gitconfig and $XDG_CONFIG_HOME/git/config. Home Manager usually manages the XDG one.

git config --show-origin --list | head -n 50
git config --show-origin --get-regexp '^alias\.'

Practical guidelines

  • Put “this machine needs X” in /modules (system).
  • Put “I, Angelo, prefer X” in /home/angelo (user).
  • Avoid putting credentials/tokens into Nix files. Manage those interactively (e.g. gh auth login).
  • Keep /hosts/<name>/hardware-configuration.nix host-specific and minimal.

Suggested next expansions

  • Add home/angelo/vscode.nix (settings + a core extension list)
  • Add home/angelo/ssh.nix (safe ssh config, no private keys)
  • Split /modules/packages.nix into role-based modules if it grows (e.g. modules/cad.nix, modules/gaming.nix)