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

+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.