added manual secrets
This commit is contained in:
1 parent
672657c111
commit
d9cacefa0f
34 files changed
+1428
-10
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user