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.

Directory Structure

.
├── checks/                # Pre-commit hooks and other checks
├── flake.nix              # Main flake configuration
├── homes/                 # Home-manager configurations for users
│   ├── aarch64-darwin/    # macOS home configurations
│   ├── aarch64-linux/     # ARM Linux home configurations
│   └── x86_64-linux/      # x86 Linux home configurations
├── modules/               # Reusable configuration modules
│   ├── home/              # Home-manager modules
│   └── nixos/             # NixOS system modules
│       ├── boot/          # Boot configuration modules
│       ├── desktop/       # Desktop environment modules
│       ├── hardware/      # Hardware-specific modules
│       ├── homeassistant/ # Home Assistant modules
│       ├── network/       # Network configuration modules
│       ├── services/      # Service configuration modules
│       └── ...            # Other module categories
├── overlays/              # Nixpkgs overlays
├── packages/              # Custom package definitions
├── secrets/               # Encrypted secrets (managed with sops-nix)
└── systems/               # System-specific configurations
    ├── aarch64-darwin/    # macOS system configurations
    ├── aarch64-linux/     # ARM Linux system configurations
    └── x86_64-linux/      # x86 Linux system configurations
        ├── jallen-nas/    # NAS server configuration
        ├── matt-nixos/    # Desktop configuration
        ├── nuc-nixos/     # NUC configuration
        ├── pi4/           # Raspberry Pi 4 configuration
        └── ...            # Other system configurations

Flake Structure

The flake.nix file defines the inputs (external dependencies) and outputs (configurations) of this repository:

Inputs

nixpkgs-unstable: The unstable channel of Nixpkgs
nixpkgs-stable: The stable channel of Nixpkgs (25.11)
home-manager: User environment management
snowfall-lib: Library for structuring flake repositories
impermanence: Persistent state management
lanzaboote: Secure boot implementation
nixos-hardware: Hardware-specific configurations
sops-nix: Secret management
disko: Disk partitioning and formatting
And more specialized inputs

Outputs

The outputs are generated using Snowfall Lib's mkFlake function, which automatically discovers and assembles:

NixOS system configurations: For each system in the systems/ directory
Home Manager configurations: For each configuration in the homes/ directory
Packages: From the packages/ directory
Modules: From the modules/ directory
Overlays: From the overlays/ directory

Module System

The module system uses a modular approach where:

Common modules are defined in modules/nixos/ and modules/home/
System-specific modules are defined in systems/<architecture>/<hostname>/

Each module follows the NixOS module pattern, with:

default.nix: Main module implementation
options.nix: Option declarations

Integration with Snowfall Lib

Snowfall Lib provides:

Automatic discovery of modules, overlays, and packages
Consistent structure across the repository
Common utilities for working with flakes

Secrets Management

Secrets are managed using sops-nix, with:

Encrypted secret files in the secrets/ directory
.sops.yaml configuration file in the root
Key management integrated into the configuration

Deployment Process

Systems are built and deployed using:

nixos-rebuild switch --flake .#hostname

This command:

Evaluates the flake for the specified hostname
Builds the resulting configuration
Activates it on the current system

4.2 KiB Raw Blame History