hdh20267-nix/README.md

User Configuration Template

This directory contains templates for creating external user configuration modules that can be referenced from the main nixos-systems/users.nix file.

Overview

External user modules allow users to maintain their personal configurations (dotfiles, packages, settings) in separate Git repositories and reference them from the main nixos-systems repository using builtins.fetchGit.

Structure

user-dotfiles-repo/
├── home.nix          # Required: Home-manager configuration
├── nixos.nix         # Optional: System-level NixOS configuration
├── README.md         # Documentation
└── dotfiles/         # Optional: Dotfiles to symlink

Usage

1. Create Your User Configuration Repository

Copy the templates from this directory to your own Git repository:

• home.nix - Required for home-manager configuration
• nixos.nix - Optional for system-level configuration

2. Reference It in users.nix

{
  ugaif.users = {
    myusername = {
      description = "My Name";
      extraGroups = [ "wheel" "networkmanager" ];
      shell = pkgs.zsh;
      
      # Option 1: External module from Git
      home = builtins.fetchGit {
        url = "https://github.com/username/dotfiles";
        rev = "abc123def456...";  # Full commit hash for reproducibility
        ref = "main";              # Optional: branch/tag name
      };
      
      # Option 2: Local path for testing
      # home = /path/to/local/dotfiles;
      
      # Option 3: Inline configuration
      # home = {
      #   home.packages = [ pkgs.vim ];
      #   programs.git.enable = true;
      # };
    };
  };
}

3. Enable on Systems

Enable the user in inventory.nix:

{
  "my-system" = {
    devices = {
      "hostname" = {
        extraUsers = [ "myusername" ];
      };
    };
  };
}

File Descriptions

home.nix (Required)

This file contains your home-manager configuration. It must be a valid NixOS module that accepts { inputs, ... } and returns a home-manager configuration.

Must export:

• Home-manager options (programs.*, home.packages, etc.)

Receives:

• inputs - Flake inputs (nixpkgs, home-manager, etc.)
• config - Home-manager config
• pkgs - Nixpkgs package set
• osConfig - Access to OS-level configuration

nixos.nix (Optional)

This file contains system-level NixOS configuration. Only needed for:

• System services related to the user
• System packages requiring root
• Special permissions or system settings

Examples

Minimal home.nix

{ inputs, ... }:

{ config, lib, pkgs, ... }:

{
  home.packages = with pkgs; [
    vim
    git
    htop
  ];

  programs.git = {
    enable = true;
    userName = "My Name";
    userEmail = "me@example.com";
  };
}

With Dotfiles

{ inputs, ... }:

{ config, lib, pkgs, ... }:

{
  home.packages = with pkgs; [ ripgrep fd bat ];

  # Symlink dotfiles
  home.file.".bashrc".source = ./dotfiles/bashrc;
  home.file.".vimrc".source = ./dotfiles/vimrc;
  
  programs.git = {
    enable = true;
    userName = "My Name";
    userEmail = "me@example.com";
  };
}

With System Configuration (nixos.nix)

{ inputs, ... }:

{ config, lib, pkgs, ... }:

{
  # Add user to docker group
  users.users.myusername.extraGroups = [ "docker" ];
  
  # Install system package
  environment.systemPackages = [ pkgs.docker ];
}

Integration Features

External user modules:

• Receive the same flake inputs as nixos-systems
• Can use all home-manager options
• Optionally provide system-level configuration (nixos.nix)
• System zsh theme applied if useZshTheme = true (default)
• System nvim config applied if useNvimPlugins = true (default)
• Merged with inventory.nix user settings (groups, shell, etc.)

Development Workflow

1. Create your user config repository with home.nix
2. Test locally: home = /path/to/local/repo;
3. Build: nix build .#nixosConfigurations.hostname.config.system.build.toplevel
4. Commit and push changes
5. Update users.nix with commit hash
6. Deploy to systems

Benefits

• Personal Ownership: Users maintain their own configs
• Version Control: Track dotfile changes over time
• Portability: Use same config across multiple machines
• Reproducibility: Pin to specific commits
• Privacy: Use private repositories for personal settings
• Separation: Keep personal configs separate from system configs