From e76fc00a98c1e80aab141221fbfe4a303d654c62 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Tue, 30 Jun 2026 23:08:46 -0500 Subject: [PATCH] hosts instructions --- .github/instructions/hosts.instructions.md | 58 ++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .github/instructions/hosts.instructions.md diff --git a/.github/instructions/hosts.instructions.md b/.github/instructions/hosts.instructions.md new file mode 100644 index 0000000..f982818 --- /dev/null +++ b/.github/instructions/hosts.instructions.md @@ -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.` for a bootable NixOS machine or container. +- `flake.homeConfigurations.` for a standalone Home Manager target. +- `flake.modules.nixos.` or `flake.modules.homeManager.` 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.`, and have the entrypoint import those modules. +- For Home Manager only hosts, define `flake.modules.homeManager.` 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 \ No newline at end of file