2.7 KiB
2.7 KiB
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):
{ 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
- Always gate with
lib.mkIf cfg.enable. Defaultenabletofalse. There is no master server switch — each service is turned on per-host inhosts/<hostname>.nix. - Never open firewall ports unconditionally. Expose an
openFirewalloption and wrap theallowedTCPPorts/allowedUDPPortsinlib.mkIf cfg.openFirewall. - Pick the namespace that matches the neighbours. Service modules under
services/and the K3s/K8s roles useskyg.nixos.server.*; the older cross-cutting modules (admin,timers,arrs,dns) useskyg.server.*. Don't invent a third. - Containers go through
virtualisation.oci-containers. This honours the Docker/Podman choice frommodules/nixos/common/containers/. Don't hardcodedocker runin a service (theopenwrtdeploy script is the only sanctioned shell-out, and it lives elsewhere). - NFS-backed volumes: create them with
system.activationScripts+docker volume create --driver local --opt type=nfs, and reference homelab hosts by their*.lab.internalnames. - Scheduled jobs (backups, auto-updates) should use the
skyg.server.timers.<name>helper intimers.nixrather than hand-writingsystemd.timers/systemd.services. - Secrets (tokens, API keys, join tokens) come from agenix (
config.age.secrets.*) or anenvironmentFilepath — never hardcoded, never committed. Seecolibri.nix/signal-cli.nixfor theenvironmentFile(agenix) pattern andk3s//dns/routing/forenvPath/secret-file patterns. - Stable identities. Where a service stores data on NFS, keep its
uid/gidfixed and unique (seearrs/andjellyfin.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.