added manual secrets

This commit is contained in:
ari committed 2026-06-26 16:07:47 -04:00
1 parent 672657c111
commit d9cacefa0f
34 files changed
+1428 -10

No files matched your search

+40
View File
@@ -0,0 +1,40 @@
# modules/nixos/
All Linux/NixOS-specific modules, grouped by scope. `default.nix` simply imports the three
subtrees below; every option here lives under `skyg.nixos.*` (with a few legacy
`skyg.server.*` and `skyg.core.*` exceptions noted in the subfolders).
## Structure
```
nixos/
├── default.nix # imports common/ + server/ + desktop/
├── common/ # Settings every Linux host gets (core, networking, ssh, fonts, hardware…)
├── server/ # Opt-in server roles & services (K3s/K8s, ARRs, DNS, AI, media…)
└── desktop/ # Opt-in desktop: tilers, theming, browsers, crypto wallets, printers…
```
## How it composes
- `common/` is always active (it sets base system options directly, gated only per-feature).
- `server/` and `desktop/` are large opt-in trees. Most leaf modules do nothing until their
`enable` option is set, so importing the whole tree is cheap.
- The two top-level gates are `skyg.nixos.desktop.enable` and the per-service enables under
`skyg.nixos.server.*` / `skyg.server.*`.
## Option Namespace
```
skyg.nixos.common.* → common/
skyg.nixos.desktop.* → desktop/
skyg.nixos.server.* → server/ (most services)
skyg.server.* → server/ (arrs, admin, exporters, timers, dns — legacy prefix)
skyg.core.qemu.* → common/qemu.nix
```
## Conventions
- New shared Linux behaviour goes in `common/`; opt-in roles go in `server/` or `desktop/`.
- Gate everything behind an `enable` option with `lib.mkIf cfg.enable { ... }`.
- Note the naming split: newer server modules use `skyg.nixos.server.*` while several older
ones use `skyg.server.*`. Match the surrounding file when extending.
+51
View File
@@ -0,0 +1,51 @@
# modules/nixos/common/
Baseline settings every Linux host receives. `default.nix` imports each file/subfolder and
sets a few always-on defaults (`EDITOR=vi`, `NIXPKGS_ALLOW_UNFREE`, local bin in PATH).
Most leaf modules expose a `skyg.nixos.common.*` enable flag and stay inert until switched on.
## Files
```
common/
├── default.nix # Imports everything below + always-on env defaults
├── core.nix # System packages, nh, nix-ld, timezone (Toronto), locale, GC cron
├── networking.nix # skyg.core.hostName, NetworkManager, NFS server
├── user.nix # skyg.user.createSystemUser — creates the system user/groups + zsh shell
├── fonts.nix # System font packages + fontconfig defaults (Fira Code, Noto, …)
├── ssh-server.nix # skyg.nixos.common.ssh-server — hardened sshd + master pubkey
├── qemu.nix # skyg.core.qemu — QEMU/quickemu + SPICE guest tooling
├── containers/ # Docker vs Podman runtime selection
├── hardware/ # GPU, fan control, audio, laptop power, Coral TPU udev
└── pritunl/ # Pritunl VPN client service
```
## Notable details
- **`core.nix`** sets `time.timeZone = "America/Toronto"`, `i18n` to `en_CA.UTF-8`, enables
`programs.nh` with auto-clean, and adds a daily `nix-collect-garbage --delete-older-than 7d`
cron job for both root and the user.
- **`networking.nix`** defines `skyg.core.hostName`, enables NetworkManager + the NFS server,
and disables the flaky `NetworkManager-wait-online` unit.
- **`user.nix`** creates the actual system user (in `wheel` + `networkmanager`) with zsh as
the login shell; gated by `skyg.user.createSystemUser` (default `true`).
- **`ssh-server.nix`** ships the master public key and a hardened sshd config
(key-only auth, long keepalives). Disabled by default.
## Option Namespace
```
skyg.core.hostName → networking.nix
skyg.user.createSystemUser → user.nix
skyg.core.qemu.* → qemu.nix
skyg.nixos.common.ssh-server.* → ssh-server.nix
skyg.nixos.common.containers.* → containers/
skyg.nixos.common.hardware.* → hardware/
skyg.nixos.common.pritunl.* → pritunl/
```
## Conventions
- This tree is for behaviour that is reasonable on *any* Linux host. Anything role-specific
belongs in `server/` or `desktop/`.
- Hostname-independent defaults can be set directly; anything optional gets an `enable` gate.
@@ -0,0 +1,41 @@
# modules/nixos/common/containers/
Container runtime configuration. Picks **one** of Docker or Podman based on
`skyg.nixos.common.containers.runtime` and configures it consistently (compose tooling,
user group membership, OCI backend, metrics).
## Files
```
containers/
├── default.nix # Shared options: runtime, enableOnBoot, registries, metrics port
├── docker.nix # Applied when runtime == "docker"
└── podman.nix # Applied when runtime == "podman" (dockerCompat + socket)
```
## Behaviour
- `runtime` defaults to `"docker"`. Each backend file gates on `cfg.runtime == "<name>"`,
so exactly one applies.
- **Docker** enables autoprune, sets `insecure-registries` from `localDockerRegistries`
(default `minipc1.lab.internal:5001`), exposes metrics on `metricsPort` (9323), adds the
user to the `docker` group, and installs `docker-compose`.
- **Podman** enables `dockerCompat` + docker socket so `docker`/`oci-containers` keep working,
and installs `podman-compose` + `podman-tui`.
- `openMetricsPort` opens the metrics port in the firewall (Docker only).
## Option Namespace
```
skyg.nixos.common.containers.runtime → "docker" | "podman"
skyg.nixos.common.containers.enableOnBoot
skyg.nixos.common.containers.localDockerRegistries
skyg.nixos.common.containers.metricsPort
skyg.nixos.common.containers.openMetricsPort
```
## Conventions
- Always select the runtime via the `runtime` option; do not enable both backends manually.
- `virtualisation.oci-containers.backend` is set by whichever runtime is active, so server
service modules can declare containers backend-agnostically.
+42
View File
@@ -0,0 +1,42 @@
# modules/nixos/common/hardware/
Per-device hardware modules. `default.nix` imports them all and turns on a couple of
always-safe defaults (`services.fwupd`, `hardware.enableAllFirmware`); each specific module
is gated by its own `skyg.nixos.common.hardware.*` enable flag so a host only pulls in what
its physical hardware needs.
## Files
```
hardware/
├── default.nix # imports + fwupd + enableAllFirmware
├── amdgpu.nix # skyg.nixos.common.hardware.amdgpu — amdgpu driver + ROCm ICD
├── nvidia.nix # skyg.nixos.common.hardware.nvidia — driver + container toolkit
├── sound.nix # skyg.nixos.common.hardware.sound — PipeWire ALSA/JACK + rtkit
├── pipewire.nix # skyg.nixos.common.hardware.pipewire — full PipeWire stack
├── fan2go.nix # skyg.nixos.common.hardware.fan2go — fan2go curve-based fan control
├── fancontrol.nix # skyg.nixos.common.hardware.fancontrol — lm_sensors fancontrol
├── laptop-power.nix # skyg.nixos.common.hardware.laptop-power-mgr — lid events + power mgmt
└── coral-tpu-udev.nix # skyg.nixos.common.hardware.udevrules.coraltpu — Coral TPU udev rules
```
## Option Namespace
```
skyg.nixos.common.hardware.amdgpu.enable
skyg.nixos.common.hardware.nvidia.enable
skyg.nixos.common.hardware.sound.enable
skyg.nixos.common.hardware.pipewire.enable
skyg.nixos.common.hardware.fan2go.{enable,dbPath}
skyg.nixos.common.hardware.fancontrol.{enable,configName}
skyg.nixos.common.hardware.laptop-power-mgr.enable
skyg.nixos.common.hardware.udevrules.coraltpu.{enable,symlinkName}
```
## Conventions
- One module per hardware concern; each defaults to `false` and is enabled per-host based on
the machine's actual hardware.
- `fan2go` and `fancontrol` are alternatives — pick one per host depending on the board.
- Keep these orthogonal to `*.hardware-configuration.nix` (that file is generated and must
never be hand-edited).
+22
View File
@@ -0,0 +1,22 @@
# modules/nixos/common/pritunl/
Pritunl VPN **client**. Installs `pritunl-client` and runs the
`pritunl-client-service` systemd unit so VPN profiles can be managed on the host.
## Files
```
pritunl/
└── default.nix # skyg.nixos.common.pritunl.enable
```
## Option Namespace
```
skyg.nixos.common.pritunl.enable # default false
```
## Conventions
- This only provisions the client daemon; VPN profiles/credentials are imported at runtime,
not declared here.
+51
View File
@@ -0,0 +1,51 @@
# modules/nixos/desktop/
Everything that turns a host into a workstation. The whole tree is gated by the master
switch `skyg.nixos.desktop.enable`; individual desktop environments, tilers, and extras
have their own sub-options so a host enables only the stack it actually uses.
## Files
```
desktop/
├── default.nix # skyg.nixos.desktop.enable — display manager, dbus, libinput, pipewire, xdg portals
├── wayland.nix # Wayland session vars (NIXOS_OZONE_WL) + clipboard/utils
├── x11/ # X11 server + libinput-gestures (skyg.nixos.desktop.x11.*)
├── tiler/ # Tiling WMs (niri / hyprland) + DankMaterialShell + swww
├── stylix/ # System-wide theming via Stylix (gruvbox-dark-hard)
├── packages.nix # Desktop apps: chromium, flatpak, vlc, ghostty, clipboard tools
├── crypto.nix # skyg.nixos.desktop.crypto — hardware wallet apps + udev rules
├── printers.nix # CUPS printing + drivers (always on when desktop enabled)
├── gnome.nix # skyg.nixos.desktop.gnome — GNOME + pop-shell
├── kde.nix # skyg.nixos.desktop.kde — Plasma 6
└── cosmic.nix # skyg.nixos.desktop.cosmic — COSMIC DE
```
## How it composes
- `default.nix` (`skyg.nixos.desktop.enable`) provides the shared desktop substrate: display
manager, dbus, libinput, PipeWire (pulse/jack), upower, avahi, and the full xdg portal set.
- The DE/WM modules (`gnome`, `kde`, `cosmic`, `tiler`) are independent enables — pick the
one(s) a host should offer.
- `packages.nix`, `wayland.nix`, and `printers.nix` activate automatically with the master
desktop enable; `crypto` is a separate opt-in.
## Option Namespace
```
skyg.nixos.desktop.enable → default.nix (master switch)
skyg.nixos.desktop.gnome.enable → gnome.nix
skyg.nixos.desktop.kde.enable → kde.nix
skyg.nixos.desktop.cosmic.enable → cosmic.nix
skyg.nixos.desktop.tiler.* → tiler/
skyg.nixos.desktop.stylix.enable → stylix/ (default true)
skyg.nixos.desktop.crypto.enable → crypto.nix
skyg.nixos.desktop.x11.* → x11/
```
## Conventions
- Nothing in this tree should activate unless `skyg.nixos.desktop.enable` is set — gate new
modules accordingly (most check `config.skyg.nixos.desktop.enable`).
- Greeter/login is handled by DankMaterialShell on tiler hosts; do not configure
`services.greetd` manually (see the repo-root `GUIDELINES.md`).
+59
View File
@@ -0,0 +1,59 @@
# Guidelines — modules/nixos/desktop/
Conventions for the desktop/workstation tree. Read alongside the repo-root `GUIDELINES.md`.
---
## Everything hangs off the master switch
`skyg.nixos.desktop.enable` is the gate for the whole tree. New desktop modules must not
activate unless it (or their own sub-option) is set:
```nix
let cfg = config.skyg.nixos.desktop; in {
config = lib.mkIf cfg.enable { ... };
}
```
Sub-features (a DE, a tiler, crypto wallets, gestures) get their **own** `enable` option so a
host opts into exactly the stack it wants.
## Greeter / login — do not hand-roll
Desktop/tiler hosts use **DankMaterialShell (DMS)** for the greeter, configured via
`programs.dank-material-shell` (see `tiler/default.nix` and the repo-root `GUIDELINES.md`).
- Do **not** configure `services.greetd` manually on these hosts.
- The keyring (`gnome-keyring`) provides the SSH agent on tiler hosts, so
`programs.ssh.startAgent` stays **off**. Don't re-enable it.
## Tilers
- Enable a compositor (`skyg.nixos.desktop.tiler.niri` or `…tiler.hyprland`), which flips the
shared `tiler.enable` for you. Don't set `tiler.enable` directly.
- Shared Wayland tooling, keyring, and polkit live in `tiler/default.nix` — add anything
common to *all* tilers there, not in the individual compositor files.
## Theming
- Global theming is **Stylix** (`stylix/`), enabled by default and gated on `desktop.enable`.
- Change the look in `stylix/default.nix` (base16 scheme + fonts). Avoid scattering per-app
color overrides elsewhere; let Stylix drive it.
## Desktop environments are independent
`gnome.nix`, `kde.nix`, and `cosmic.nix` are mutually independent opt-ins. A host can enable
more than one, but typically picks a single primary DE/WM. Each excludes the upstream apps it
doesn't want (terminals, text editors, etc.) — keep that list curated rather than installing
everything.
## Config symlinks
Some modules symlink files from the repo's `configs/` directory into `~/.config` via
activation scripts (e.g. `x11/lib-gesture.nix` → `libinput-gestures.conf`). Edit the file in
`configs/`, not the module, when changing that behaviour.
## Validation
Do **not** build or switch. `nix-instantiate --parse` is the only safe local check; the user
validates on real hardware.
+29
View File
@@ -0,0 +1,29 @@
# modules/nixos/desktop/stylix/
System-wide theming through [Stylix](https://github.com/danth/stylix). Applies a single
base16 scheme and font set across the desktop (GTK, Qt, terminals, etc.) automatically.
## Files
```
stylix/
└── default.nix # skyg.nixos.desktop.stylix.enable (default true)
```
## Behaviour
- Defaults to **enabled**, but only takes effect when `skyg.nixos.desktop.enable` is also set.
- Scheme: `gruvbox-dark-hard`, dark polarity, `autoEnable = true`.
- Fonts: DejaVu (serif/sans/mono) + Noto Color Emoji.
## Option Namespace
```
skyg.nixos.desktop.stylix.enable # default true; gated on desktop.enable
```
## Conventions
- To change the global theme, edit the `base16Scheme`/`fonts` here rather than overriding
per-app theming downstream.
- Disable via `skyg.nixos.desktop.stylix.enable = false` on hosts that want manual theming.
+40
View File
@@ -0,0 +1,40 @@
# modules/nixos/desktop/tiler/
Tiling Wayland compositors and their shared plumbing. The shared `tiler.enable` switch
brings in DankMaterialShell (DMS), the gnome-keyring/secrets stack, polkit, and a common set
of Wayland control/capture tools. Each compositor module turns this on automatically.
## Files
```
tiler/
├── default.nix # skyg.nixos.desktop.tiler.enable — DMS, keyring, polkit, shared packages
├── niri.nix # skyg.nixos.desktop.tiler.niri — niri compositor (sets tiler.enable)
├── hyprland.nix # skyg.nixos.desktop.tiler.hyprland — Hyprland (sets tiler.enable)
└── swww.nix # skyg.nixos.desktop.tiler.background — swww/waypaper wallpaper tools
```
## Behaviour
- Enabling either `niri` or `hyprland` sets `skyg.nixos.desktop.tiler.enable = true`, which
pulls in the shared substrate. You normally enable only the compositor option.
- The shared substrate configures **gnome-keyring as the SSH agent** (so
`programs.ssh.startAgent = false`), enables polkit, and installs control tools
(pavucontrol, playerctl, brightnessctl, blueman) and screen-capture tools
(slurp, satty, wf-recorder).
- `background` is an independent opt-in for swww + waypaper wallpaper management.
## Option Namespace
```
skyg.nixos.desktop.tiler.enable → default.nix (usually set indirectly)
skyg.nixos.desktop.tiler.niri.enable
skyg.nixos.desktop.tiler.hyprland.enable
skyg.nixos.desktop.tiler.background.enable
```
## Conventions
- Don't set `tiler.enable` directly — enable a compositor and let it flip the shared switch.
- Greeter is DMS-managed (`programs.dank-material-shell`); never hand-roll `services.greetd`.
- Keyring provides the SSH agent here — keep `programs.ssh.startAgent` off.
+30
View File
@@ -0,0 +1,30 @@
# modules/nixos/desktop/x11/
X11 server setup and touchpad gesture support for desktop hosts.
## Files
```
x11/
├── default.nix # Enables services.xserver (us layout) when desktop.enable is set
└── lib-gesture.nix # skyg.nixos.desktop.x11.enableLibGestures — libinput-gestures + tools
```
## Behaviour
- `default.nix` enables `services.xserver` with a US keyboard layout whenever
`skyg.nixos.desktop.enable` is on (X is kept available even on Wayland-first hosts).
- `lib-gesture.nix` is an independent opt-in that installs `libinput-gestures`, `wmctrl`,
`xdotool`, adds the user to the `input` group, and symlinks
`configs/libinput-gestures.conf` into the user's `~/.config`.
## Option Namespace
```
skyg.nixos.desktop.x11.enableLibGestures # default false
```
## Conventions
- Gesture config is sourced from `configs/libinput-gestures.conf` via an activation symlink —
edit the config there, not in the module.
+50
View File
@@ -0,0 +1,50 @@
# modules/nixos/server/
Opt-in server roles and self-hosted services for the homelab. `default.nix` imports every
subtree; each module/service is individually enabled — there is **no** single master server
switch, so a host only runs what it explicitly turns on.
## Structure
```
server/
├── default.nix # imports everything below
├── admin.nix # skyg.server.admin — www-data group/user for shared web data
├── exporters.nix # skyg.server.exporters — Prometheus node exporter (:9100)
├── timers.nix # skyg.server.timers — generic attrset → systemd timer+oneshot service
├── arrs/ # *arr media-automation stack (prowlarr/sonarr/radarr) + postgres
├── dns/ # Local DNS resolver, certbot, local CA
├── k3s/ # Single-binary K3s cluster role
├── k8s/ # Full upstream Kubernetes (master/node)
└── services/ # Self-hosted apps (jellyfin, audiobookshelf, comfyui, scrypted, dockge, ai…)
```
## Notable details
- **`timers.nix`** is a reusable helper: anything added to `skyg.server.timers.<name>`
(with `script`, `OnCalendar`, `wantedBy`) becomes a systemd timer + oneshot service. Other
modules (e.g. `services/scrypted.nix`) use it for backups/auto-updates.
- **`exporters.nix`** enables the Prometheus node exporter with the systemd collector and
opens port 9100.
- Naming: this tree mostly uses the legacy `skyg.server.*` prefix for cross-cutting modules
(admin/exporters/timers/arrs/dns) and `skyg.nixos.server.*` for the K3s/K8s roles and the
service modules under `services/`.
## Option Namespace
```
skyg.server.admin.enable → admin.nix
skyg.server.exporters.enable → exporters.nix
skyg.server.timers.<name> → timers.nix
skyg.server.arrs.* → arrs/
skyg.server.dns.* → dns/
skyg.nixos.server.k3s.* → k3s/
skyg.nixos.server.k8s.* → k8s/
skyg.nixos.server.services.* → services/
```
## Conventions
- Every role/service defaults to `false`; enable per-host in `hosts/<hostname>.nix`.
- Services that need ports should expose an `openFirewall` option rather than opening ports
unconditionally. See `GUIDELINES.md` in this folder for the full service-authoring pattern.
+62
View File
@@ -0,0 +1,62 @@
# 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, `dockge.nix`/`scrypted.nix` for containerized
NFS-backed services):
```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`, `exporters`, `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` (see `dockge.nix`), 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 `openclaw.nix` for
the agenix-token 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.
## Gotcha: openclaw.nix
`openclaw.nix` is **not** imported by `services/default.nix`. If you enable it, import it
explicitly. Don't assume every file in `services/` is wired in.
## 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.
+40
View File
@@ -0,0 +1,40 @@
# modules/nixos/server/arrs/
The *arr media-automation stack (Prowlarr / Sonarr / Radarr) plus a shared PostgreSQL
backend. `arrs/default.nix` defines a `makeConfig` helper that generates a consistent option
set (enable, package, openFirewall, user/group, fixed uid/gid, port) for each *arr app.
## Files
```
arrs/
├── default.nix # skyg.server.arrs.* — shared options + makeConfig per-app option builder
├── db.nix # Shared PostgreSQL instance for the *arr apps
└── prowlarr.nix # Prowlarr service definition
```
## Fixed identities & ports
| App | uid/gid | default port |
|----------|---------|--------------|
| prowlarr | 9000 | 9096 |
| sonarr | 9001 | 8989 |
| radarr | 9002 | 7878 |
Postgres listens on `5432`; shared data lives under `/var/lib/arrs` (`rootDataDir`).
## Option Namespace
```
skyg.server.arrs.enable
skyg.server.arrs.openFirewall
skyg.server.arrs.rootDataDir
skyg.server.arrs.database.port
skyg.server.arrs.{prowlarr,sonarr,radarr}.{enable,package,openFirewall,user,group,uid,gid,port}
```
## Conventions
- New *arr apps should be added via the `makeConfig` helper with a unique uid/gid/port, then
given their own definition file (mirroring `prowlarr.nix`).
- Keep the fixed uid/gid scheme stable — it keeps NFS-backed data ownership consistent.
+39
View File
@@ -0,0 +1,39 @@
# modules/nixos/server/dns/
Local DNS and certificate infrastructure for the `*.lab.internal` / `*.internal` homelab.
`default.nix` imports the three independent submodules below.
## Structure
```
dns/
├── default.nix # imports routing/ + certbot/ + local-ca/
├── routing/ # skyg.server.dns.routing — dnsmasq resolver + static A records
├── certbot/ # skyg.server.dns.certbot — Let's Encrypt via certbot + nginx
└── local-ca/ # skyg.server.dns.local-ca — internal certificate authority scaffolding
```
## Notable details
- **`routing/`** runs dnsmasq, generating exact + wildcard `address=` entries from
`addresses`, forwarding the rest to `upstreamServers` (default 1.1.1.1/1.0.0.1). It can
also pull additional `address=` lines from an **agenix secret** named via
`addressesSecretName` (decrypted into a `conf-file`).
- **`certbot/`** wires up daily `certbot renew --nginx`, with a `testMode` dry-run option and
a `certbot-get-certs` shell alias built from `publicDomains` + `email`.
- **`local-ca/`** sets up the directory/structure for an internal CA; the actual key/cert
generation is currently scaffolded (commented openssl steps) rather than fully implemented.
## Option Namespace
```
skyg.server.dns.routing.{enable,addresses,addressesSecretName,upstreamServers,listenAddresses,openFirewall}
skyg.server.dns.certbot.{enable,publicDomains,email,testMode}
skyg.server.dns.local-ca.{enable,caCert,caKey,domain,organization,...}
```
## Conventions
- The three submodules are independent; enable only what a host needs.
- DNS records that must stay private should live in the agenix secret referenced by
`addressesSecretName`, not in plaintext `addresses`.
@@ -0,0 +1,33 @@
# modules/nixos/server/dns/certbot/
Let's Encrypt certificate management via **certbot** + the nginx plugin, for public-facing
domains.
## Files
```
certbot/
└── default.nix # skyg.server.dns.certbot.*
```
## Behaviour
- Installs `certbot` + `certbot-nginx` and enables nginx.
- Sets up a `certbot-renew` systemd service + daily timer (uses `renew --dry-run` when
`testMode = true`).
- Provides a `certbot-get-certs` shell alias that runs a non-interactive
`certonly --nginx` for every domain in `publicDomains`, registered with `email`.
## Option Namespace
```
skyg.server.dns.certbot.enable
skyg.server.dns.certbot.publicDomains # list of domains
skyg.server.dns.certbot.email # ACME account email
skyg.server.dns.certbot.testMode # dry-run renewals
```
## Conventions
- Initial issuance is manual (run `certbot-get-certs`); renewal is automated by the timer.
- For internal-only domains use the `local-ca` sibling module instead of Let's Encrypt.
@@ -0,0 +1,30 @@
# modules/nixos/server/dns/local-ca/
Scaffolding for an internal Certificate Authority used to issue certs for private
`*.internal` domains that should not go through Let's Encrypt.
## Files
```
local-ca/
└── default.nix # skyg.server.dns.local-ca.*
```
## Status & behaviour
- Creates `/etc/ssl/local-ca` and a `local-ca-setup` oneshot service.
- **The actual CA key/cert generation is currently scaffolded** — the openssl invocation in
`local-ca-setup` is commented out, and the `ca-certificates.crt` entry is a placeholder.
Treat this module as a structural stub to build on, not a working CA yet.
## Option Namespace
```
skyg.server.dns.local-ca.enable
skyg.server.dns.local-ca.{caCert,caKey,domain,organizationalUnit,organization,country,email,certificateLifetime}
```
## Conventions
- If you implement real key generation here, do **not** commit private keys; persist them
outside the Nix store and reference them by path (or manage with agenix).
@@ -0,0 +1,39 @@
# modules/nixos/server/dns/routing/
Local DNS resolver backed by **dnsmasq**. Serves static domain→IP mappings for the homelab
and forwards everything else upstream.
## Files
```
routing/
└── default.nix # skyg.server.dns.routing.*
```
## Behaviour
- Each `addresses` entry `{ domain, ip }` produces **both** an exact (`/domain/ip`) and a
wildcard (`/.domain/ip`) dnsmasq `address=` line.
- `addressesSecretName` points at an agenix secret (`secrets/<name>.age`) whose decrypted
contents are a dnsmasq fragment, included via `conf-file` — used for records that should
not live in the public repo.
- `upstreamServers` (default `1.1.1.1`, `1.0.0.1`) handle unresolved queries.
- `listenAddresses` (empty = all interfaces) and `openFirewall` (port 53 UDP/TCP) control
exposure.
## Option Namespace
```
skyg.server.dns.routing.enable
skyg.server.dns.routing.addresses # [{ domain, ip }]
skyg.server.dns.routing.addressesSecretName # agenix secret name, or null
skyg.server.dns.routing.upstreamServers
skyg.server.dns.routing.listenAddresses
skyg.server.dns.routing.openFirewall
```
## Conventions
- Put private/sensitive records in the agenix secret, not in `addresses`.
- The `age.secrets` reference resolves relative to the repo `secrets/` directory — manage
that file with `skyg secrets`, never by hand.
+32
View File
@@ -0,0 +1,32 @@
# modules/nixos/server/k3s/
Single-binary **K3s** cluster role. Lightweight Kubernetes used for the homelab cluster.
## Files
```
k3s/
└── default.nix # skyg.nixos.server.k3s.*
```
## Behaviour
- Enables `services.k3s` with `role` (`server` or `agent`) and an optional `environmentFile`
(`envPath`, e.g. for the join token).
- Extra flags: disables the bundled servicelb and helm-controller, and writes the kubeconfig
group-readable to the `users` group.
- Opens the standard control-plane/data-plane ports: 6443, 80, 443, 10250–10252, 8472
(flannel), 51820 (wireguard).
## Option Namespace
```
skyg.nixos.server.k3s.enable
skyg.nixos.server.k3s.role # "server" | "agent" (default "server")
skyg.nixos.server.k3s.envPath # path to environmentFile (e.g. token); "" to skip
```
## Conventions
- K3s and the full `k8s/` role are mutually exclusive — a host runs one or the other.
- Keep cluster join tokens out of the repo; point `envPath` at an agenix-managed file.
+37
View File
@@ -0,0 +1,37 @@
# modules/nixos/server/k8s/
Full upstream **Kubernetes** role (as opposed to the lighter `k3s/`). Splits responsibilities
into master and node modules under a shared option set.
## Files
```
k8s/
├── default.nix # skyg.nixos.server.k8s.* — shared options, firewall, services.kubernetes base
├── master.nix # Control-plane (apiserver/scheduler/controller/etcd) config
└── node.nix # Worker node config
```
## Behaviour
- `default.nix` adds the master hostname to `/etc/hosts` (`masterIP`/`masterHostName`), opens
the control-plane ports (apiserver `6443`, kubelet 10250/10257/10259, etcd 2379–2380),
installs `kubectl`/`kubernetes`, and sets `easyCerts` + DNS addon.
- A host declares its role via `isMaster` / `isNode`.
## Option Namespace
```
skyg.nixos.server.k8s.enable
skyg.nixos.server.k8s.isMaster
skyg.nixos.server.k8s.isNode
skyg.nixos.server.k8s.masterIP
skyg.nixos.server.k8s.masterHostName
skyg.nixos.server.k8s.masterAPIPort # default 6443
```
## Conventions
- Use either this full `k8s` role or `k3s` on a host, not both.
- `masterIP`/`masterHostName` must be set on every member so the cluster can resolve the
control plane.
+49
View File
@@ -0,0 +1,49 @@
# modules/nixos/server/services/
Self-hosted application services. `default.nix` imports each one; every service is an
independent `skyg.nixos.server.services.<name>.enable` flag. Most run as OCI containers via
`virtualisation.oci-containers` (so they honour the Docker/Podman runtime chosen in
`common/containers/`), often backed by NFS volumes.
## Files
```
services/
├── default.nix # imports the services below
├── ai-services.nix # skyg.nixos.server.services.ai — ollama + Wyoming (whisper/piper/wake)
├── audiobookshelf.nix # skyg.nixos.server.services.audiobookshelf — audiobook/podcast server
├── jellyfin.nix # skyg.nixos.server.services.jellyfin — media server (uid/gid 7777)
├── scrypted.nix # skyg.nixos.server.services.scrypted — NVR (host net, NFS NVR volume)
├── dockge.nix # skyg.nixos.server.services.dockge — compose stack manager (NFS volumes)
├── openclaw.nix # skyg.nixos.server.services.openclaw — AI gateway (NOT imported by default)
└── comfyui/ # skyg.nixos.server.services.comfyui — ComfyUI with ROCm/CUDA GPU support
```
## Notable details
- **`ai-services.nix`** runs ollama (GPU-passthrough) and openwakeword as containers and
enables NixOS-native Wyoming faster-whisper + piper. Opens 11434/10200/10300/10400.
- **`dockge.nix` / `scrypted.nix`** create NFS-backed docker volumes via
`system.activationScripts` and use `skyg.server.timers` for backups/auto-updates.
- **`openclaw.nix`** is a native systemd service (with agenix-token support and security
hardening). Note: it is **not** listed in `default.nix`'s imports, so it must be imported
explicitly if used.
## Option Namespace
```
skyg.nixos.server.services.ai.enable
skyg.nixos.server.services.audiobookshelf.{enable,package,configDir,dataDir}
skyg.nixos.server.services.jellyfin.enable
skyg.nixos.server.services.scrypted.enable
skyg.nixos.server.services.dockge.{enable,openFirewall,port,volumes}
skyg.nixos.server.services.openclaw.{enable,port,gatewayToken,...}
skyg.nixos.server.services.comfyui.{enable,mode,port,openFirewall}
```
## Conventions
- One file per service; gate everything behind `enable` (default `false`).
- Expose an `openFirewall` option instead of opening ports unconditionally.
- Secrets (tokens, credentials) come from agenix — never hardcode them.
- See `GUIDELINES.md` in `modules/nixos/server/` for the full service-authoring pattern.
@@ -0,0 +1,39 @@
# modules/nixos/server/services/comfyui/
ComfyUI (Stable Diffusion workflow UI) running in Docker with GPU acceleration. Supports both
**ROCm** (AMD) and **CUDA** (NVIDIA) via a `mode` switch, with shared options/assertions in
`shared.nix`.
## Files
```
comfyui/
├── default.nix # imports shared + rocm + rocm-docker + cuda
├── shared.nix # skyg.nixos.server.services.comfyui.* — options, firewall, assertions
├── rocm.nix # ROCm (AMD) path
├── rocm-docker.nix # ROCm container/image wiring
├── cuda.nix # CUDA (NVIDIA) path
├── rocm.Containerfile# ROCm image definition
└── init.sh # Container init script
```
## Behaviour
- `mode` selects `"rocm"` (default) or `"cuda"`. Web UI on `port` (default 8188),
`openFirewall` defaults to **true**.
- `shared.nix` asserts that Docker, `hardware.graphics`, and `hardware.enableAllFirmware` are
all enabled — ComfyUI needs the GPU passed through to the container.
## Option Namespace
```
skyg.nixos.server.services.comfyui.enable
skyg.nixos.server.services.comfyui.mode # "rocm" | "cuda"
skyg.nixos.server.services.comfyui.port # default 8188
skyg.nixos.server.services.comfyui.openFirewall # default true
```
## Conventions
- Pick the GPU `mode` matching the host hardware; the unused path stays inert.
- This module requires Docker (not Podman) and the relevant `hardware/*` GPU module enabled.