8.2 KiB
Custom Modules
This directory contains documentation for the custom modules used in this NixOS configuration.
Overview
Modules are split into three categories:
- NixOS modules (
modules/nixos/) — system-level configuration - Home Manager modules (
modules/home/) — user-level configuration - Darwin modules (
modules/darwin/) — macOS-specific configuration
All modules are auto-discovered by Snowfall Lib and expose options under the mjallen namespace.
NixOS Modules
Boot (modules/nixos/boot/)
| Module | Description |
|---|---|
boot/common/ |
Shared boot defaults (quiet boot, Plymouth) |
boot/lanzaboote/ |
Secure Boot via Lanzaboote |
boot/systemd-boot/ |
systemd-boot (non-secure-boot systems) |
boot/plymouth/ |
Plymouth splash screen |
Desktop (modules/nixos/desktop/)
| Module | Description |
|---|---|
desktop/gnome/ |
GNOME desktop environment |
desktop/hyprland/ |
Hyprland compositor |
desktop/cosmic/ |
COSMIC desktop environment |
Development (modules/nixos/development/)
Enables development tools and language support. Options:
mjallen.development = {
enable = true;
includeLanguages = [ "python" "c" ];
includeContainers = true;
};
Hardware (modules/nixos/hardware/)
| Module | Description |
|---|---|
hardware/amd/ |
AMD GPU (AMDGPU driver, LACT) |
hardware/nvidia/ |
NVIDIA GPU |
hardware/battery/ |
Battery charge threshold management |
hardware/raspberry-pi/ |
Raspberry Pi hardware support and DT overlays |
hardware/openrgb/ |
OpenRGB for LED control |
hardware/btrfs/ |
btrfs-specific settings |
hardware/common/ |
Common hardware defaults |
Headless (modules/nixos/headless/)
Server profile — disables suspend/hibernate, enables systemd watchdog, no display manager.
mjallen.headless.enable = true;
Home Assistant (modules/nixos/homeassistant/)
Full smart home stack. See Home Assistant docs for details.
mjallen.services.home-assistant.enable = true;
Impermanence (modules/nixos/impermanence/)
Ephemeral root filesystem with explicit persistence declarations.
mjallen.impermanence = {
enable = true;
extraDirectories = [ { directory = "/var/lib/myapp"; user = "myapp"; } ];
};
Monitoring (modules/nixos/monitoring/)
Prometheus metrics and Grafana dashboards.
mjallen.monitoring.enable = true;
Network (modules/nixos/network/)
Hostname, firewall, NetworkManager profiles, static IP configuration.
mjallen.network = {
hostName = "my-host";
ipv4 = {
method = "manual";
address = "10.0.1.5/24";
gateway = "10.0.1.1";
dns = "1.1.1.1";
interface = "eth0";
};
firewall = {
enable = true;
allowedTCPPorts = [ 80 443 ];
};
};
Power (modules/nixos/power/)
UPS (NUT) support.
mjallen.power.ups.enable = true;
Security (modules/nixos/security/)
| Module | Description |
|---|---|
security/common/ |
Common hardening (kernel params, etc.) |
security/tpm/ |
TPM2 — Clevis disk unlock |
Services (modules/nixos/services/)
~50 self-hosted service modules, all built with mkModule. Each exposes at minimum enable, port, reverseProxy, and openFirewall. Common usage pattern:
mjallen.services.jellyfin = {
enable = true;
port = 8096;
reverseProxy.enable = true;
};
Available services:
actual, ai, appimage, arrs, attic, authentik, authentikRac, booklore, caddy, calibre, calibre-web, cockpit, code-server, collabora, coturn, crowdsec, dispatcharr, free-games-claimer, gitea, glance, glances, grafana, guacd, headscale, immich, jellyfin, seerr, lubelogger, manyfold, matrix, minecraft, mongodb, nebula, netbootxyz, nextcloud, ntfy, onlyoffice, opencloud, orca, paperless, paperless-ai, protonmail-bridge, restic, samba, sparky-fitness, sparky-fitness-server, sunshine, tdarr, termix, tunarr, unmanic, uptime-kuma, wyoming, your-spotify
Nebula VPN (services/nebula/)
Unified module for both lighthouse and node roles:
# Lighthouse
mjallen.services.nebula = {
enable = true;
isLighthouse = true;
port = 4242;
secretsPrefix = "pi5/nebula";
secretsFile = lib.snowfall.fs.get-file "secrets/pi5-secrets.yaml";
hostSecretName = "lighthouse";
};
# Node
mjallen.services.nebula = {
enable = true;
port = 4242;
lighthouses = [ "10.1.1.1" ];
staticHostMap = { "10.1.1.1" = [ "mjallen.dev:4242" ]; };
secretsPrefix = "mymachine/nebula";
secretsFile = lib.snowfall.fs.get-file "secrets/mymachine-secrets.yaml";
hostSecretName = "mymachine";
};
See Secrets Management for how to generate the required certificates.
SOPS (modules/nixos/sops/)
Configures sops-nix to decrypt secrets using the machine's SSH host key as an age key.
mjallen.sops = {
enable = true;
sshKeyPaths = [ "/etc/ssh/ssh_host_ed25519_key" ]; # default
};
User (modules/nixos/user/)
System user account management.
mjallen.user = {
name = "matt";
mutableUsers = false;
extraGroups = [ "docker" "video" ];
};
Home Manager Modules
Desktop
| Module | Description |
|---|---|
desktop/gnome/ |
GNOME user settings (extensions, keybindings, etc.) |
desktop/theme/ |
Theme configuration |
Programs
| Module | Description |
|---|---|
programs/btop/ |
btop system monitor |
programs/code/ |
VS Code / VSCodium settings |
programs/git/ |
Git user config |
programs/hyprland/ |
Hyprland compositor config |
programs/kitty/ |
Kitty terminal config |
programs/librewolf/ |
LibreWolf browser settings |
programs/mako/ |
Mako notification daemon |
programs/nwg-dock/ |
nwg-dock panel |
programs/nwg-drawer/ |
nwg-drawer app launcher |
programs/nwg-panel/ |
nwg-panel bar |
programs/opencode/ |
OpenCode AI coding assistant |
programs/update-checker/ |
Automatic flake update checker |
programs/waybar/ |
Waybar status bar |
programs/wlogout/ |
Logout menu |
programs/wofi/ |
Wofi launcher |
programs/zsh/ |
Zsh shell config |
Other
| Module | Description |
|---|---|
gpg/ |
GPG agent configuration |
services/pass/ |
Password store |
shell-aliases/ |
Common shell aliases |
sops/ |
User-level SOPS secrets |
stylix/ |
System-wide theming (colours, fonts, wallpaper) |
user/ |
User environment defaults |
Module Development
Using mkModule
The lib.mjallen.mkModule helper (lib/module/default.nix) creates a fully-featured NixOS module from a minimal spec:
{ config, lib, namespace, pkgs, ... }:
let
name = "my-service";
cfg = config.${namespace}.services.${name};
serviceConfig = lib.${namespace}.mkModule {
inherit config name;
description = "my service";
options = {
# extra options beyond the standard set
myOption = lib.${namespace}.mkOpt lib.types.str "default" "Description";
};
moduleConfig = {
services.my-service = {
enable = true;
port = cfg.port;
};
};
};
in
{ imports = [ serviceConfig ]; }
Standard options provided by mkModule for free: enable, port, listenAddress, openFirewall, configDir, dataDir, createUser, configureDb, environmentFile, reverseProxy.*, redis.*, extraEnvironment, hashedPassword, puid, pgid, timeZone.
Using mkContainerService
For Podman/OCI container services, use mkContainerService instead:
lib.${namespace}.mkContainerService {
inherit config name;
image = "ghcr.io/example/my-app:latest";
internalPort = 8080;
volumes = [ "${cfg.configDir}:/config" ];
};
Option helpers
lib.mjallen.mkOpt types.str "default" "description"
lib.mjallen.mkBoolOpt false "description"
lib.mjallen.mkOpt' types.int 80 # no description
lib.mjallen.enabled # { enable = true; }
lib.mjallen.disabled # { enable = false; }