Repository Architecture

This document provides an overview of the repository architecture, explaining how the various components fit together.

Overview

This NixOS configuration repository is built using Nix Flakes and Snowfall Lib to provide a modular, maintainable configuration for multiple systems. The Snowfall namespace is mjallen, so all custom options are accessed as mjallen.<domain>.<name>.

Directory Structure

.
├── flake.nix              # Main flake — inputs, outputs, Snowfall config
├── flake.lock             # Locked dependency versions
├── .sops.yaml             # SOPS key management rules
├── treefmt.nix            # Code formatter configuration
├── qemu.nix               # QEMU VM testing config
│
├── checks/                # Pre-commit hooks and CI checks
│
├── docs/                  # Documentation (this directory)
│
├── homes/                 # Home Manager configurations
│   ├── aarch64-darwin/    # macOS user configs
│   ├── aarch64-linux/     # ARM Linux user configs
│   └── x86_64-linux/      # x86 Linux user configs
│
├── lib/                   # Custom Nix library utilities
│   ├── module/            # mkModule, mkOpt, mkBoolOpt helpers
│   ├── file/              # File/path utilities
│   └── versioning/        # Package version pinning helpers
│
├── modules/               # Reusable configuration modules
│   ├── home/              # Home Manager modules
│   ├── nixos/             # NixOS system modules
│   └── darwin/            # nix-darwin modules (macOS)
│
├── overlays/              # Nixpkgs overlays
│
├── packages/              # Custom package definitions
│
├── secrets/               # SOPS-encrypted secret files
│
└── systems/               # Per-host system configurations
    ├── aarch64-darwin/    # macOS (nix-darwin) hosts
    ├── aarch64-linux/     # ARM Linux hosts
    ├── x86_64-install-iso/# Install ISO configurations
    └── x86_64-linux/      # x86_64 Linux hosts

Flake Inputs

Input	Source	Purpose
`nixpkgs-unstable`	`github:NixOS/nixpkgs/nixos-unstable`	Primary package set
`nixpkgs-stable`	`github:NixOS/nixpkgs/nixos-25.11`	Stable package set
`nixpkgs-otbr`	`github:mrene/nixpkgs` (fork)	OpenThread Border Router packages
`home-manager-unstable`	`github:nix-community/home-manager`	User environment management
`home-manager-stable`	`github:nix-community/home-manager/release-25.11`	Stable home-manager
`snowfall-lib`	`github:mjallen18/snowfall-lib`	Flake structure library (personal fork)
`impermanence`	`github:nix-community/impermanence`	Ephemeral root filesystem support
`lanzaboote`	`github:nix-community/lanzaboote/v1.0.0`	Secure Boot
`nixos-hardware`	`github:NixOS/nixos-hardware`	Hardware-specific NixOS configs
`sops-nix`	`github:Mic92/sops-nix`	Secret management
`disko`	`github:nix-community/disko`	Declarative disk partitioning
`cosmic`	`github:lilyinstarlight/nixos-cosmic`	COSMIC desktop environment
`jovian`	`github:Jovian-Experiments/Jovian-NixOS`	Steam Deck / handheld support
`nixos-apple-silicon`	`github:nix-community/nixos-apple-silicon`	Asahi Linux / Apple Silicon
`darwin`	`github:nix-darwin/nix-darwin`	macOS system configuration
`nix-homebrew`	`github:zhaofengli/nix-homebrew`	Declarative Homebrew (macOS)
`stylix`	`github:nix-community/stylix`	System-wide theming
`nix-vscode-extensions`	`github:nix-community/nix-vscode-extensions`	VS Code extension packages
`authentik-nix`	`github:nix-community/authentik-nix`	Authentik SSO
`nix-cachyos-kernel`	`github:xddxdd/nix-cachyos-kernel`	CachyOS optimised kernels
`lsfg-vk`	`github:pabloaul/lsfg-vk-flake`	Lossless Scaling frame generation (Linux)
`nix-index-database`	`github:nix-community/nix-index-database`	Pre-built nix-index database
`steam-rom-manager`	`github:mjallen18/nix-steam-rom-manager`	Steam ROM Manager package
`nix-plist-manager`	`github:sushydev/nix-plist-manager`	macOS plist management
`nix-rosetta-builder`	`github:cpick/nix-rosetta-builder`	Rosetta build support (macOS)
`pre-commit-hooks-nix`	`github:cachix/pre-commit-hooks.nix`	Pre-commit hooks
`treefmt-nix`	`github:numtide/treefmt-nix`	Code formatting

nixpkgs and home-manager are aliases pointing to the unstable variants.

Module System

Structure

All modules follow a standard Snowfall Lib pattern and are automatically discovered. Each module exposes options under the mjallen namespace:

# Enable a module
mjallen.services.jellyfin.enable = true;
mjallen.desktop.gnome.enable = true;
mjallen.hardware.amd.enable = true;

`mkModule` helper

Most service modules are built with lib.mjallen.mkModule (lib/module/default.nix), which provides a standard set of options:

Option	Default	Description
`enable`	`false`	Enable/disable the module
`port`	`80`	Service listen port
`listenAddress`	`"0.0.0.0"`	Bind address
`openFirewall`	`true`	Open firewall ports
`configDir`	`/var/lib/<name>`	Config directory
`dataDir`	`/var/lib/<name>/data`	Data directory
`createUser`	`false`	Create a dedicated system user
`configureDb`	`false`	Create a PostgreSQL database
`environmentFile`	`null`	Path to an env-file
`reverseProxy.enable`	`false`	Add a Caddy reverse proxy block
`reverseProxy.subdomain`	`<name>`	Caddy subdomain
`redis.enable`	`false`	Create a dedicated Redis instance

NixOS modules (`modules/nixos/`)

Category	Paths	Description
Boot	`boot/common/`, `boot/lanzaboote/`, `boot/plymouth/`, `boot/systemd-boot/`	Bootloader configurations
Desktop	`desktop/gnome/`, `desktop/hyprland/`, `desktop/cosmic/`	Desktop environments
Development	`development/`	Dev tools, language support, containers
Hardware	`hardware/amd/`, `hardware/nvidia/`, `hardware/battery/`, `hardware/raspberry-pi/`, `hardware/openrgb/`, ...	Hardware-specific configs
Headless	`headless/`	Headless server profile (watchdog, no suspend)
Home Assistant	`homeassistant/`	Smart home automation suite
Impermanence	`impermanence/`	Ephemeral root + persistent state
Monitoring	`monitoring/`	Prometheus/Grafana metrics
Network	`network/`	Hostname, firewall, NetworkManager, static IP
Power	`power/`	UPS support
Programs	`programs/`	System-wide programs (nix-index, gnupg, etc.)
Security	`security/common/`, `security/tpm/`	Common hardening, TPM unlock
Services	`services/<name>/`	~50 self-hosted service modules (see below)
SOPS	`sops/`	Secret management setup
System	`system/`	Miscellaneous system settings
User	`user/`	User account management
Virtualization	`virtualization/`	libvirt, containers

Home Manager modules (`modules/home/`)

Category	Paths	Description
Desktop	`desktop/gnome/`, `desktop/theme/`	GNOME and theming
GPG	`gpg/`	GPG agent configuration
Programs	`programs/btop/`, `programs/git/`, `programs/zsh/`, `programs/kitty/`, `programs/waybar/`, `programs/hyprland/`, `programs/wofi/`, `programs/mako/`, `programs/wlogout/`, `programs/librewolf/`, `programs/opencode/`, `programs/update-checker/`, ...	User applications
Services	`services/pass/`	Password store integration
Shell	`shell-aliases/`	Common shell aliases
SOPS	`sops/`	User-level secret integration
Stylix	`stylix/`	System-wide theming
User	`user/`	User environment defaults

Secrets Management

Secrets are encrypted with SOPS using age keys derived from each machine's SSH host key (/etc/ssh/ssh_host_ed25519_key). The .sops.yaml file maps secret file path patterns to the set of age recipients that can decrypt them.

Each host has its own secrets file:

File	Host
`secrets/secrets.yaml`	Shared (all hosts)
`secrets/nas-secrets.yaml`	jallen-nas
`secrets/pi5-secrets.yaml`	pi5
`secrets/allyx-secrets.yaml`	allyx
`secrets/nuc-secrets.yaml`	nuc-nixos
`secrets/mac-secrets.yaml`	macbook-pro-nixos
`secrets/desktop-secrets.yaml`	matt-nixos

See the Secrets Management section of the root README for full details on generating keys and adding secrets.

Deployment

# NixOS system
sudo nixos-rebuild switch --flake .#hostname

# macOS (nix-darwin)
darwin-rebuild switch --flake .#hostname

# Home Manager only
home-manager switch --flake .#username@hostname

8.8 KiB Raw Blame History