nix-darwin/README.md

nix-darwin

한국어

Declarative macOS setup with nix-darwin, home-manager, nix-homebrew, and sops-nix.

What This Repo Manages

• Flake orchestration and host assembly in modules/flake/
• Auto-discovered Darwin and Home Manager aspects in modules/aspects/
• Auto-discovered host declarations in hosts/
• Encrypted secrets via SOPS (secrets/ + .sops.yaml)

Prerequisites

• macOS on Apple Silicon (aarch64-darwin)
• Nix with flakes enabled (nix-command + flakes)
• just (command runner)
• SOPS age key at:

$HOME/.config/sops/age/keys.txt

Repository Layout

• flake.nix: flake-parts entrypoint and flake inputs
• Justfile: day-to-day commands (darwin, darwin-debug, fmt, up, gc)
• modules/flake/: repo options, Darwin assembly, and shared context modules
• modules/aspects/: auto-discovered aspect entry modules such as base, homebrew, shell, editor, and desktop
• modules/aspects/_*/: ignored internal implementation trees that back the public aspect entry modules
• hosts/: auto-discovered host declarations that register system and a flat features list
• secrets/: encrypted secret files (poby.yaml)

Common Commands

# List available tasks
just

# Build and switch for current machine hostname
just darwin $(hostname)

# Build and switch with trace/verbose logs
just darwin-debug $(hostname)

# Format Nix files (from repository root)
just fmt .

# Update all flake inputs
just up

# Update one flake input
just upp nixpkgs

# Validate build without switching (example host: fenrir)
nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'

# Validate without realizing a full build
nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'

# Inspect profile history / cleanup old generations
just history
just clean
just gc

Configuration Notes

• flake.nix now uses flake-parts, keeps ./modules/flake explicit, and auto-discovers ./modules/aspects and ./hosts through import-tree.
• hosts/fenrir.nix is the current host declaration and maps fenrir to one flat feature list.
• modules/flake/darwin-configurations.nix assembles each host’s darwinConfigurations.<host> output and embeds Home Manager for user poby.
• modules/aspects/ is the feature vocabulary for hosts. The current feature set is base, nix-core, system-packages, homebrew, macos-defaults, activation, fonts, sudo-auth, shell, cli-tools, git, ssh, secrets, terminal, editor, desktop, and fenrir.
• The cli-tools aspect owns the CLI user tool set, including zoxide.
• modules/aspects/_*/ contains implementation files that are intentionally not auto-loaded. import-tree skips paths containing /_, which is the repo’s convention for internal helpers and subtrees like the NVF source.
• Home Manager is Darwin-integrated only in this phase; no standalone homeConfigurations output is exposed.

Adding A Host

• Create hosts/<hostname>.nix.
• Register repo.hosts.<hostname>.system.
• Register repo.hosts.<hostname>.features with the desired aspect names.
• Add any host-specific behavior as a new aspect in modules/aspects/ instead of modifying shared features.

Secrets

• Keep secrets encrypted in secrets/*.yaml.
• .sops.yaml enforces encryption rules for secrets/.*\.yaml.
• Home Manager reads from secrets/poby.yaml via the secrets aspect:
  • github_ssh_key
  • github_cli_token

Troubleshooting

• Use just darwin-debug <hostname> for detailed evaluation/build output.
• If evaluation fails for a host, verify it exists under darwinConfigurations.
• Dry-run evaluation with nix build .#darwinConfigurations.<host>.system --dry-run before a full switch when you only want to confirm the dependency graph.
• If settings look stale after a successful build, run switch again and verify active hostname/config values.