84 lines
5.7 KiB
Markdown
84 lines
5.7 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
This repository is a simplified `flake-parts` NixOS flake. `flake.nix` imports `./modules` through `import-tree`, so normal `.nix` files under `modules/` are loaded automatically unless their file or directory name starts with `_`.
|
||
|
||
- `modules/flake-parts.nix` defines the `flake-parts` setup, formatter, and the exported `nixosConfigurations`.
|
||
- `modules/hosts/<name>/default.nix` defines one top-level `flake.modules.nixos.<host>` module and assembles that machine by importing reusable features, user modules, and host-local helpers.
|
||
- `modules/hosts/<name>/_*.nix` are private host-local helper modules such as hardware and disk layout files.
|
||
- `modules/users/<name>.nix` defines one reusable NixOS user module and the baseline Home Manager imports for that account.
|
||
- `modules/features/*.nix` contains reusable NixOS and Home Manager feature modules.
|
||
- `modules/features/<feature>/default.nix` is used when a feature needs private helper files, for example `niri/_bindings.nix`.
|
||
- `modules/features/services/*.nix` contains reusable service-oriented NixOS modules.
|
||
- `modules/secrets/sops.nix` wires `sops-nix` for both NixOS and Home Manager.
|
||
- `modules/secrets/secrets.yaml` stores encrypted secrets, with `.sops.yaml` defining SOPS creation rules.
|
||
- `modules/_treefmt.nix` configures repository formatting.
|
||
|
||
Keep host files thin. Shared behavior belongs in `modules/features/` or `modules/users/`. Host files should mainly compose imports and hold host-only settings such as monitor layouts, hardware quirks, boot tweaks, and machine-local firewall or service choices.
|
||
|
||
## Mental Model
|
||
This repo is direct module composition around `flake.modules`, not the old inventory-driven dendritic design.
|
||
|
||
- Reusable building blocks are exposed as `flake.modules.nixos.<name>` and `flake.modules.homeManager.<name>`.
|
||
- Host modules are the composition root. They import the reusable NixOS modules they need, enable Home Manager, and add any host-specific Home Manager imports inline.
|
||
- User modules define the Unix user plus that account’s baseline Home Manager setup.
|
||
- There is no `config.repo`, inventory schema, profiles layer, or attachment builder anymore.
|
||
|
||
In practice:
|
||
|
||
- Prefer importing a feature module directly over inventing a repo-local option just to toggle it.
|
||
- Put cross-host reusable behavior in `modules/features/`.
|
||
- Put account-specific defaults in `modules/users/`.
|
||
- Keep private helper files `_`-prefixed so `import-tree` does not expose them as top-level modules.
|
||
- Match the existing split between NixOS composition in host modules and Home Manager composition in user or host modules.
|
||
|
||
## Current Host Composition
|
||
There are three exported hosts:
|
||
|
||
- `orion`: server-oriented host with `kiri`, SOPS, and service modules such as Caddy, Gitea, Vaultwarden, Radicale, Actual, and OpenSSH.
|
||
- `polaris`: graphical desktop host with `kiri` and `ergon`, hardware imports, Niri, Steam, local desktop features, and host-specific monitor layout.
|
||
- `zenith`: graphical laptop host with `kiri` and `ergon`, Niri, laptop hardware support, firmware updates, and host-specific monitor layout.
|
||
|
||
When adjusting user-facing software, check whether it belongs in:
|
||
|
||
- a user baseline in `modules/users/<name>.nix`
|
||
- a reusable Home Manager feature in `modules/features/*.nix`
|
||
- a host-local extension inside `modules/hosts/<name>/default.nix`
|
||
|
||
Be careful not to move host-specific Home Manager imports into a user baseline unless that behavior should apply on every host that imports that user module.
|
||
|
||
## Validation And Development Commands
|
||
Run commands from the repository root.
|
||
|
||
- `nix build --no-link --show-trace .#nixosConfigurations.<host>.config.system.build.toplevel`: baseline validation for one host.
|
||
- `nix build --no-link --show-trace .#nixosConfigurations.orion.config.system.build.toplevel .#nixosConfigurations.polaris.config.system.build.toplevel .#nixosConfigurations.zenith.config.system.build.toplevel`: validate all defined hosts in one invocation.
|
||
- `nixos-rebuild build --flake .#<host>`: use when you specifically want `nixos-rebuild` semantics without activation.
|
||
- `nix eval --json .#nixosConfigurations.<host>.config.<option>`: inspect a single evaluated option while iterating.
|
||
- `nix fmt`: format the repository using the flake-provided formatter from `modules/_treefmt.nix`.
|
||
- `nix store diff-closures <old> <new>`: compare built system closures when reviewing refactors for parity or regressions.
|
||
|
||
This repo does not define a first-party `checks` output. Validation is primarily host builds plus targeted `nix eval` checks.
|
||
|
||
## Coding Style & Naming Conventions
|
||
Use two-space indentation and standard Nix attrset formatting. Prefer small `let` bindings, lowerCamelCase local names, and lowercase file names.
|
||
|
||
- Define reusable modules as `flake.modules.nixos.<name>` or `flake.modules.homeManager.<name>`.
|
||
- Keep one obvious feature per file or directory.
|
||
- Use `default.nix` only when the feature needs private helper files alongside it.
|
||
- Match surrounding style instead of reformatting unrelated code.
|
||
- Prefer explicit host imports over hidden indirection.
|
||
|
||
## Commit
|
||
Follow the existing history style: short imperative subjects, optionally with a conventional prefix, for example `refactor: simplify host composition`.
|
||
|
||
## Security & Configuration Tips
|
||
Never commit plaintext secrets. Add or update secrets through `modules/secrets/secrets.yaml` and reference them via `config.sops.secrets.<name>.path`.
|
||
|
||
Be explicit and cautious with changes to:
|
||
|
||
- firewall and OpenSSH settings
|
||
- disk layout and boot configuration
|
||
- SOPS key handling and admin user access
|
||
- firmware, hardware, and authentication settings
|
||
- host-vs-user module boundaries, because it is easy to accidentally broaden behavior to the wrong machines
|