Digital Garden

Recent Notes

NixOS Flakes Dendritic System Setup

2 min read

NixOS Flakes Dendritic System Setup

This note tree explains a NixOS flake that is arranged like a dendrite: a small root imports a tree of cells, branches collect modules, leaves attach behavior, and hosts select the branch set they need.

Up: MOC DevOps Automation and Configuration Management

Down: flake.nix | cells | pkgs | overlays | dev shell

What NixOS is

NixOS is a Linux distribution where system state is described with Nix modules. Instead of editing service files by hand, you declare the desired state, build it, and switch the running system to that generation.

The important mental model is that a NixOS system is an evaluated module graph. Every module contributes options or configuration, and the module system merges those contributions into one final system configuration.

What flakes add

A flake gives the repository a reproducible entry point. It pins inputs, exposes outputs, and makes commands such as nixos-rebuild, nix flake check, and nix develop evaluate the same dependency graph.

In this setup, the flake root is intentionally small. It does not define the whole machine directly. It delegates almost everything to cells/.

outputs = inputs:
  inputs.flake-parts.lib.mkFlake { inherit inputs; }
    (inputs.import-tree ./cells);

That line is the root of the dendritic pattern. flake-parts provides the flake framework, and import-tree imports every relevant cell file so each leaf can attach itself to the system.

The dendritic pattern

The architecture has five layers.

  • Root: flake.nix pins inputs and imports cells/.
  • Schema: cells/options* defines the vocabulary under my.*.
  • Branches: cells/branches/* declares named collectors such as base, desktop, and security.
  • Leaves: files under core/, shell/, desktop/, persist/, server/, secrets/, programs/, hardware/, and scripts/ append NixOS or Home Manager modules to those branch collectors.
  • Hosts: cells/hosts/* selects branches and instantiates concrete machines.

The filesystem is not only a place to store modules. It is part of the assembly mechanism.

How to read this tutorial

Start with flake.nix, then move into cells. From there, read options before branches, branches before leaves, and hosts last.

The code examples use placeholders for personal values, domains, public keys, and local secret paths. The architecture is public; identity and deployment details should stay out of public notes.

5 items under this folder.