100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
```nix
|
|
{ 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
|
|
|
|
```nix
|
|
{ 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 ugaif.* 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.)
|