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/
├── user.nix          # Optional: User options AND home-manager configuration
├── nixos.nix         # Optional: System-level NixOS configuration
├── README.md         # Documentation
└── dotfiles/         # Optional: Dotfiles to symlink

Note: Both .nix files are optional, but at least one should be present for the module to be useful.

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 = {
      # Option 1: Set user options in users.nix
      description = "My Name";
      extraGroups = [ "wheel" "networkmanager" ];
      shell = pkgs.zsh;
      
      # Option 2: Or let the external module's user.nix set these options
      
      # Reference external dotfiles module
      external = builtins.fetchGit {
        url = "https://github.com/username/dotfiles";
        rev = "abc123def456...";  # Full commit hash for reproducibility
        ref = "main";              # Optional: branch/tag name
      };
      
      # Or use local path for testing
      # external = /path/to/local/dotfiles;
      # };
    };
  };
}

3. Enable on Systems

Enable the user in inventory.nix:

{
  "my-system" = {
    devices = {
      "hostname" = {
        ugaif.users.myusername.enable = true;
      };
    };
  };
}

File Descriptions

user.nix (Optional)

This file serves dual purpose:

Sets ugaif.users.<username> options (description, shell, extraGroups, etc.)
Provides home-manager configuration (programs., home., services.*)

How it works:

The ugaif.users.<username> options are extracted and loaded as data during module evaluation
These options override any defaults set in users.nix (which uses lib.mkDefault)
The home-manager options (home.*, programs.*, etc.) are imported as a module for home-manager
External module options take precedence over users.nix base configuration

The same file is imported in two contexts:

As a NixOS module to read ugaif.users options
As a home-manager module for home., programs., services.*, etc.

Simply include both types of options in the same file.

Receives:

inputs - Flake inputs (nixpkgs, home-manager, etc.)
config - Config (NixOS or home-manager depending on context)
lib - Nixpkgs library
pkgs - Nixpkgs package set
osConfig - (home-manager context only) OS-level configuration

Example: See user.nix template

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

Receives:

inputs - Flake inputs (nixpkgs, home-manager, etc.)
config - NixOS config
lib - Nixpkgs library
pkgs - Nixpkgs package set

Examples

Minimal user.nix

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

{
  # User account options (imported as NixOS module)
  ugaif.users.myuser = {
    description = "My Name";
    shell = pkgs.zsh;
    extraGroups = [ "wheel" "networkmanager" ];
  };

  # Home-manager configuration (imported into home-manager)
  home.packages = with pkgs; [
    vim
    git
    htop
  ];

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

With Dotfiles

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

{
  ugaif.users.myuser = {
    description = "My Name";
    shell = pkgs.zsh;
  };

  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 set user options via user.nix (description, shell, home-manager, etc.)
Optionally provide system-level configuration (nixos.nix)
System zsh theme applied if useZshTheme = true (default)
System nvim config applied if useNvimPlugins = true (default)
Settings from user.nix override base users.nix definitions

Development Workflow

Create your user config repository with user.nix and/or nixos.nix
Set user options in user.nix OR in the main users.nix
Test locally: external = /path/to/local/repo;
Build: nix build .#nixosConfigurations.hostname.config.system.build.toplevel
Commit and push changes
Update users.nix with commit hash
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