Files
2026-10-16 16:59:09 -04:00

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

  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.