NixOS Modules Overview

Introduction

This homelab provides a comprehensive collection of reusable NixOS modules organized into three main categories:

Core - Essential system configuration (boot, networking, secrets, users)
Desktop - Desktop environment and features
Hosting - Single-node and clustering infrastructure

Module Structure

Modules are located in modules/nixos/ and follow a hierarchical structure:

modules/nixos/
├── core/           # Core system modules
│   ├── boot.nix
│   ├── gitops.nix
│   ├── hardware/
│   ├── networking/
│   ├── secrets.nix
│   ├── users.nix
│   └── clamav.nix
├── desktop/        # Desktop environment modules
│   ├── environments/
│   ├── features/
│   └── services/
└── hosting/        # Hosting/clustering modules
    ├── single-node/
    └── clustering/

Using Modules

Modules are imported automatically when you use the homelab flake. Simply enable them in your system configuration:

# systems/my-system/default.nix
{
  core = {
    boot.enable = true;
    networking.tailscale.enable = true;
    users.myuser = {
      admin = true;
      hashedPassword = "...";
    };
  };

  desktop = {
    environments.kde.enable = true;
  };

  hosting = {
    single-node.enable = true;
  };
}

Module Categories

Core Modules

Core modules provide essential system functionality:

Boot - Systemd-boot, ZRAM swap, Plymouth, secure boot
GitOps - Automated system updates from Git repositories
Hardware - GPU, Bluetooth, HID device support
Networking - Network Manager, Tailscale, OpenSSH
Secrets - SOPS-based secret management
Users - Declarative user management with home-manager integration
ClamAV - Antivirus scanning and protection

View Core Module Reference →

Desktop Modules

Desktop modules configure graphical environments:

Environments - KDE Plasma, COSMIC desktop
Display Managers - SDDM, greetd
Window Managers - Hyprland with UWSM
Features - Gaming, printing, virtualization
Services - PipeWire, Flatpak, ASUS laptop tools

View Desktop Module Reference →

Hosting Modules

Hosting modules enable container and cluster orchestration:

Single-Node - Docker-based container hosting with Traefik reverse proxy
Clustering - K3s Kubernetes clusters with multi-node support

View Hosting Module Reference →

Configuration Patterns

Basic System Configuration

A minimal desktop system:

{
  core = {
    boot.enable = true;
    hardware.enable = true;
    networking.network-manager.enable = true;
    users.alice = {
      admin = true;
      hashedPassword = "$y$j9T$...";
      publicKey = "ssh-ed25519 AAAA...";
    };
  };

  desktop.environments.kde.enable = true;
}

Server with Container Hosting

A server with Docker and Tailscale:

{
  core = {
    boot.enable = true;
    networking = {
      ipv4_address = "192.168.1.100";
      tailscale.enable = true;
    };
    secrets = {
      enable = true;
      defaultSopsFile = ./secrets.yaml;
    };
    users.sysadmin = {
      admin = true;
      publicKey = "ssh-ed25519 AAAA...";
    };
  };

  hosting = {
    single-node.enable = true;
    enableNvidiaSupport = true;
  };
}

Multi-Node Kubernetes Cluster

K3s leader node:

{
  core = {
    boot.enable = true;
    networking = {
      ipv4_address = "10.0.0.10";
      tailscale.enable = true;
    };
    secrets.enable = true;
  };

  hosting.clustering.backends.k3s = {
    enable = true;
    mode = "leader";
    nodeIP = "10.0.0.10";
  };
}

K3s agent node:

{
  hosting.clustering.backends.k3s = {
    enable = true;
    mode = "agent";
    leaderIP = "https://10.0.0.10:6443";
    nodeIP = "10.0.0.11";
  };
}

Module Development

Creating a New Module

Modules follow the standard NixOS module pattern:

{
  lib,
  config,
  pkgs,
  ...
}: let
  cfg = config.myCategory.myModule;
in {
  options.myCategory.myModule = {
    enable = lib.mkEnableOption "My module description";
    
    setting = lib.mkOption {
      type = lib.types.str;
      default = "default-value";
      description = "Description of this setting";
      example = "example-value";
    };
  };

  config = lib.mkIf cfg.enable {
    # Module implementation
  };
}

Best Practices

Use enable options - Every module should have an enable option
Provide defaults - Sensible defaults reduce configuration burden
Add examples - Show real-world usage in option descriptions
Document options - Clear descriptions for all configurable options
Use assertions - Validate incompatible option combinations
Integrate with home-manager - Extend user configurations when appropriate

Next Steps

Core Module Reference - Detailed core module documentation
Desktop Module Reference - Desktop environment options
Hosting Module Reference - Container and cluster setup
System Configuration - Real-world system configurations

NixOS Modules

Home Manager Modules

Nix-on-Droid Modules

Introduction

Module Structure

Using Modules

Module Categories

Core Modules

Desktop Modules

Hosting Modules

Configuration Patterns

Basic System Configuration

Server with Container Hosting

Multi-Node Kubernetes Cluster

Module Development

Creating a New Module

Best Practices

Next Steps

Build docs developers (and LLMs) love

NixOS Modules

Home Manager Modules

Nix-on-Droid Modules

​Introduction

​Module Structure

​Using Modules

​Module Categories

​Core Modules

​Desktop Modules

​Hosting Modules

​Configuration Patterns

​Basic System Configuration

​Server with Container Hosting

​Multi-Node Kubernetes Cluster

​Module Development

​Creating a New Module

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Introduction

Module Structure

Using Modules

Module Categories

Core Modules

Desktop Modules

Hosting Modules

Configuration Patterns

Basic System Configuration

Server with Container Hosting

Multi-Node Kubernetes Cluster

Module Development

Creating a New Module

Best Practices

Next Steps