athenix/USER_CONFIGURATION.md

External User Configuration

This document explains how to use external modules for user configuration in nixos-systems.

Overview

Users can now maintain their home-manager configurations in separate Git repositories and reference them from users.nix using builtins.fetchGit, similar to how external system configurations work.

Changes from Previous System

Before (Flakes)

hdh20267 = {
  description = "Hunter Halloran";
  flakeUrl = "github:hdh20267/dotfiles";
};

After (Modules with fetchGit)

hdh20267 = {
  description = "Hunter Halloran";
  home = builtins.fetchGit {
    url = "https://github.com/hdh20267/dotfiles";
    rev = "abc123...";
  };
};

Configuration Methods

1. External Repository (fetchGit)

myuser = {
  description = "My Name";
  extraGroups = [ "wheel" "networkmanager" ];
  home = builtins.fetchGit {
    url = "https://github.com/username/dotfiles";
    rev = "commit-hash";  # For reproducibility
    ref = "main";         # Optional branch
  };
};

2. Local Path (for testing)

myuser = {
  description = "My Name";
  home = /home/username/dev/dotfiles;
};

3. Inline Configuration

myuser = {
  description = "My Name";
  home = {
    home.packages = with pkgs; [ vim git ];
    programs.git = {
      enable = true;
      userName = "My Name";
    };
  };
};

4. No External Config (legacy)

myuser = {
  description = "My Name";
  homePackages = [ pkgs.vim ];
  # home = null;  # Default
};

External Repository Structure

When using fetchGit or a path, the repository must contain:

Required: home.nix

{ inputs, ... }:

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

{
  # Home-manager configuration
  home.packages = with pkgs; [ ... ];
  programs.git = { ... };
}

Optional: nixos.nix

{ inputs, ... }:

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

{
  # System-level configuration (if needed)
  users.users.myuser.extraGroups = [ "docker" ];
}

Integration with System

External user modules:

1. Receive inputs: Same flake inputs as nixos-systems (nixpkgs, home-manager, etc.)
2. Access osConfig: Can read system configuration via osConfig parameter
3. Merged with system settings: Combined with inventory.nix user settings
4. System themes applied: Zsh/nvim themes from system if enabled

Module Loading Order

For home-manager configuration:

1. External module (home.nix)
2. System theme module (if useZshTheme = true)
3. System nvim config (if useNvimPlugins = true)

For NixOS configuration:

1. User's NixOS module (nixos.nix, if exists)
2. All other system modules

Available Parameters

In home.nix, you receive:

• inputs - Flake inputs (nixpkgs, home-manager, etc.)
• config - Home-manager configuration
• lib - Nixpkgs library functions
• pkgs - Package set
• osConfig - OS-level configuration (readonly)

In nixos.nix, you receive:

• inputs - Flake inputs
• config - NixOS configuration
• lib - Nixpkgs library functions
• pkgs - Package set

User Options in users.nix

When defining a user with external config:

username = {
  # Required
  description = "Full Name";
  
  # External configuration
  home = builtins.fetchGit { ... };
  
  # System settings (still configured here)
  extraGroups = [ "wheel" ];
  hashedPassword = "$6$...";
  opensshKeys = [ "ssh-ed25519 ..." ];
  shell = pkgs.zsh;
  
  # Control system integration
  useZshTheme = true;      # Apply system zsh theme
  useNvimPlugins = true;   # Apply system nvim config
  
  # Legacy options (ignored if home is set)
  homePackages = [ ];      # Use home.packages in home.nix instead
  extraImports = [ ];      # Use imports in home.nix instead
};

Examples

Minimal Dotfiles Repository

my-dotfiles/
├── home.nix
└── README.md

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

my-dotfiles/
├── home.nix
├── nixos.nix
├── dotfiles/
│   ├── bashrc
│   └── vimrc
└── README.md

home.nix:

{ inputs, ... }:
{ config, lib, pkgs, ... }:
{
  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-level packages
  environment.systemPackages = [ pkgs.docker ];
}

Migration Guide

From flakeUrl to home

1. Update users.nix:

   - flakeUrl = "github:user/dotfiles";
   + home = builtins.fetchGit {
   +   url = "https://github.com/user/dotfiles";
   +   rev = "latest-commit-hash";
   + };
   

2. Update your dotfiles repository:

   • Rename or ensure you have home.nix (not flake.nix)
   • Change module signature from flake to simple module:

     - { inputs, outputs, ... }:
     + { inputs, ... }:
     { config, lib, pkgs, ... }:
     

3. Optional: Add nixos.nix for system-level config

4. Test locally first:

   home = /path/to/local/dotfiles;
   

5. Deploy:

   nix flake check
   ./deploy hostname
   

Benefits

• No Flakes Required: Simpler for users unfamiliar with flakes
• Explicit Versioning: Pin to specific commits with rev
• Faster Evaluation: No flake evaluation overhead
• Local Testing: Easy to test with local paths
• Flexibility: Supports Git, paths, or inline configs
• Reproducibility: Commit hashes ensure exact versions

Templates

See /home/engr-ugaif/user-config-template/ for templates and detailed examples.