78 lines
6.3 KiB
Markdown
78 lines
6.3 KiB
Markdown
---
|
|
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.
|
|
|
|
Naming rules for new hosts:
|
|
|
|
- Treat the host directory name as the canonical host slug for new work.
|
|
- Prefer `modules/hosts/<slug>/default.nix` as the main entrypoint for a host directory.
|
|
- Use the same slug for the primary `hostname` binding, `flake.nixosConfigurations.<slug>`, and `networking.hostName` unless the task explicitly requires a different deployed hostname.
|
|
- If the host exports a host-local Home Manager module, name it `flake.modules.homeManager.<slug>`.
|
|
- For standalone Home Manager configurations, prefer `flake.homeConfigurations."<username>@<slug>"` so the exported key still carries the host slug.
|
|
- Name host-local helper modules with the same slug as a prefix, for example `flake.modules.nixos.<slug>-hardware` or `flake.modules.nixos.<slug>-configuration`, to make ownership obvious and avoid collisions with shared modules.
|
|
- Keep host-local secrets and auxiliary files under the same host slug directory. Do not point a new host at another host's path just because the contents are similar.
|
|
|
|
Allowed exception for immutable deployed hostnames:
|
|
|
|
- If the deployed hostname is externally constrained and cannot change, use that deployed hostname as the canonical slug for exported keys and `hostname` bindings, even if the directory name differs.
|
|
- In that case, keep the exception explicit in comments or reports so future cleanup work does not accidentally rename a live hostname contract.
|
|
|
|
When working in existing hosts that predate these rules:
|
|
|
|
- Preserve the current public names by default.
|
|
- If the user asks for a rename or cleanup, update the directory slug, exported flake keys, host-local module names, and `networking.hostName` together in one change so the host identity stays coherent.
|
|
|
|
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 |