john/dendritic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

hosts instructions

Browse Source
This commit is contained in:
John Lancaster
2026-06-30 23:08:46 -05:00
parent f22e8cb1d5
commit e76fc00a98
1 changed files with 58 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/instructions/hosts.instructions.md
+58
View File
@@ -0,0 +1,58 @@
---
description: "Use when defining or modifying hosts and host-local data under modules/hosts. Explains how this repo exports nixosConfigurations and homeConfigurations, when to create flake.modules.nixos or flake.modules.homeManager helpers, and how secrets, defaults, keys, and hardware files fit into a host definition."
applyTo: 'modules/hosts/**/*.nix, modules/hosts/**/secrets.yaml, modules/hosts/**/defaults.json, modules/hosts/**/fingerprint, modules/hosts/**/*.pub'
---
# Host Definitions
Host files under `modules/hosts` are flake entrypoints, not just loose Nix snippets. Because `modules` is auto-imported through `import-tree` and `flake-file`, files here usually export one or more of these attributes:
- `flake.nixosConfigurations.<name>` for a bootable NixOS machine or container.
- `flake.homeConfigurations.<name>` for a standalone Home Manager target.
- `flake.modules.nixos.<name>` or `flake.modules.homeManager.<name>` when a host is split into reusable host-local modules that are then assembled by a nearby entrypoint.
Follow the existing host patterns in this tree:
- Keep the host entrypoint file focused on composing modules into `nixosSystem` or `homeManagerConfiguration`.
- If a host has substantial machine-specific logic, put that logic in sibling files such as `configuration.nix` or `hardware.nix`, export them as `flake.modules.nixos.<name>`, and have the entrypoint import those modules.
- For Home Manager only hosts, define `flake.modules.homeManager.<name>` and then expose a matching `flake.homeConfigurations` entry.
- Prefer composing from shared modules in `self.modules.nixos` or `inputs.self.modules.homeManager` instead of re-implementing shared behavior inline.
Treat host-local data as part of the host definition:
- Keep hardware-specific settings in the host directory, typically in `hardware.nix`.
- Keep install-time or machine-specific configuration in the same host directory, typically in `configuration.nix`.
- Keep host-local secret references beside the host and wire them through `sops.defaultSopsFile` and `mysops.hostSecretFile` instead of pointing at unrelated locations.
- Preserve nearby auxiliary files such as `defaults.json`, fingerprints, public keys, and `secrets.yaml`; these are part of the host contract.
For host-adjacent data files:
- Keep `secrets.yaml` scoped to the host that consumes it; do not reuse another host's secret file as a shortcut.
- Treat files such as `defaults.json`, `fingerprint`, and `*.pub` as inputs consumed by the host module. Update references together with the data when changing paths or filenames.
- Avoid moving or renaming these files unless the corresponding Nix references are updated in the same change.
Naming in this tree is not perfectly uniform, so preserve existing interfaces unless the task is explicitly a rename:
- The directory name, exported flake key, and `networking.hostName` may differ.
- Some hosts export from `default.nix`, while others keep the main definition in a differently named file such as `soteria.nix`.
- Do not normalize names or move files just for consistency unless the user asks for that structural change.
Use nearby hosts as composition examples:
- `john-p14s` splits the reusable machine logic into `configuration.nix` and `hardware.nix`, exports `flake.modules.nixos.p14sConfiguration` and `flake.modules.nixos.p14sHardware`, and assembles them from `default.nix`.
- `janus` defines a host-local reusable module (`flake.modules.nixos.janus-ca`) in the same file that also exports the final `flake.nixosConfigurations.janus` host.
- `john-pc` is a Home Manager target, so it exports a `flake.modules.homeManager` module and a `flake.homeConfigurations` entry rather than a `nixosConfiguration`.
- `soteria` combines a NixOS host, a host-local Home Manager module, and host-local secrets in one host directory.
When adding or changing a host:
- Mirror the local style first. Small hosts may define the full configuration inline; larger hosts should split reusable modules out.
- Keep `let` bindings such as `username`, `hostname`, `flakeDir`, and package aliases near the top when the file already follows that pattern.
- Add shared behavior by importing existing modules, not by copying option blocks between hosts.
- If the change affects both system and Home Manager state for a host, update both sides in the same host area when that host already models both.
For reviews and answers, distinguish between these layers:
- host entrypoint wiring in `modules/hosts/...`
- reusable shared modules in `modules/nixos`, `modules/programs`, `modules/services`, and `modules/users`
- host-local modules exported from a host directory and then consumed by its entrypoint