External System Module Template

This directory contains a template for creating external system configuration modules that can be referenced from the main nixos-systems repository.

Overview

External modules allow you to maintain system configurations in separate Git repositories and reference them from the main nixos-systems/inventory.nix file using builtins.fetchGit or builtins.fetchTarball.

Usage

1. Create Your Module Repository

Copy default.nix from this template to your own Git repository. Customize it with your system configuration.

2. Reference It in inventory.nix

{
  "my-system-type" = {
    devices = {
      "hostname" = builtins.fetchGit {
        url = "https://github.com/your-org/your-config-repo";
        rev = "abc123def456...";  # Full commit hash for reproducibility
        ref = "main";              # Optional: branch/tag name
      };
    };
  };
}

3. Module Structure

Your default.nix must:

Accept { inputs, ... } as parameters (you'll receive the same flake inputs)
Return a valid NixOS module with { config, lib, pkgs, ... }: { ... }
Export configuration under the config attribute

Examples

Simple Configuration Module

{ inputs, ... }:

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

{
  config = {
    time.timeZone = "America/New_York";
    
    environment.systemPackages = with pkgs; [
      vim
      git
      htop
    ];
    
    services.openssh.enable = true;
  };
}

Advanced Module with Options

{ inputs, ... }:

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

{
  options.myorg.databaseUrl = lib.mkOption {
    type = lib.types.str;
    description = "Database connection URL";
  };

  config = {
    # Use the option
    services.postgresql = {
      enable = true;
      # ... configuration using config.myorg.databaseUrl
    };
  };
}

Benefits

Separation of Concerns: Keep specialized configurations in dedicated repositories
Reusability: Share configurations across multiple NixOS fleets
Version Control: Pin to specific commits for reproducibility
Team Ownership: Different teams can maintain their own config repos
Security: Private repositories for sensitive configurations

Integration with nixos-systems

External modules are automatically integrated into the nixos-systems build:

They receive the same flake inputs (nixpkgs, home-manager, etc.)
They can use athenix.* options if defined in the host type
They are merged with local overrides and base configuration
They work with all build methods (ISO, LXC, Proxmox, etc.)