Files
nixos-setup/modules/nixos/server/GUIDELINES.md
T
2026-10-16 16:59:09 -04:00

58 lines
2.7 KiB
Markdown

# Guidelines — modules/nixos/server/
How to add and modify homelab server roles/services. Read alongside the repo-root
`GUIDELINES.md`.
---
## Anatomy of a service module
Most files here follow the same shape. When adding a new service, mirror an existing one
(`jellyfin.nix` for a simple native service):
```nix
{ config, lib, pkgs, ... }:
let cfg = config.skyg.nixos.server.services.<name>;
in {
options.skyg.nixos.server.services.<name> = {
enable = lib.mkEnableOption "Enable <Name>";
openFirewall = lib.mkEnableOption "Open ports for <Name>"; # if it serves traffic
port = lib.mkOption { type = lib.types.port; default = <n>; };
};
config = lib.mkIf cfg.enable {
# ...
};
}
```
Then add it to `services/default.nix`'s `imports` list (and to the `services/ABOUTME.md`).
## Rules
1. **Always gate with `lib.mkIf cfg.enable`.** Default `enable` to `false`. There is no
master server switch — each service is turned on per-host in `hosts/<hostname>.nix`.
2. **Never open firewall ports unconditionally.** Expose an `openFirewall` option and wrap
the `allowedTCPPorts`/`allowedUDPPorts` in `lib.mkIf cfg.openFirewall`.
3. **Pick the namespace that matches the neighbours.** Service modules under `services/` and
the K3s/K8s roles use `skyg.nixos.server.*`; the older cross-cutting modules
(`admin`, `timers`, `arrs`, `dns`) use `skyg.server.*`. Don't invent a third.
4. **Containers go through `virtualisation.oci-containers`.** This honours the Docker/Podman
choice from `modules/nixos/common/containers/`. Don't hardcode `docker run` in a service
(the `openwrt` deploy script is the only sanctioned shell-out, and it lives elsewhere).
5. **NFS-backed volumes**: create them with `system.activationScripts` + `docker volume
create --driver local --opt type=nfs`, and reference homelab hosts by
their `*.lab.internal` names.
6. **Scheduled jobs** (backups, auto-updates) should use the `skyg.server.timers.<name>`
helper in `timers.nix` rather than hand-writing `systemd.timers`/`systemd.services`.
7. **Secrets** (tokens, API keys, join tokens) come from **agenix** (`config.age.secrets.*`)
or an `environmentFile` path — never hardcoded, never committed. See `colibri.nix`/
`signal-cli.nix` for the `environmentFile` (agenix) pattern and `k3s/`/`dns/routing/`
for `envPath`/secret-file patterns.
8. **Stable identities.** Where a service stores data on NFS, keep its `uid`/`gid` fixed and
unique (see `arrs/` and `jellyfin.nix`) so ownership survives across hosts.
## Validation
Do **not** build or switch (see root `GUIDELINES.md`). Use `nix-instantiate --parse` on the
file for a syntax check; the user applies and verifies the service themselves.