8.7 KiB
8.7 KiB
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 |
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