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

+1 -1
View File
@@ -1 +1 @@
/nix/store/vg0s32j9yp65ayzxsc1mwh90y4icgf4y-pre-commit-config.json
/nix/store/w0az8z0nd9vkl5pzbaqp83b88394y4pr-pre-commit-config.json
+4 -1
View File
@@ -42,6 +42,9 @@ Host files (`hosts/<hostname>.nix`) do not use `imports`. All modules are compos
the `makeNixOs` call in `flake.nix` via `modules/main.nix`. Adding imports to a host file
breaks the composition model.
### ❌ NEVER modify `GUIDELINES.md` unless explicitly requested by the user, you must live and die by these and hold yourself accountable to them!
---
## Safe Operations
@@ -51,7 +54,7 @@ These are always safe to perform without asking:
- Reading any `.nix`, `.md`, or config file
- Editing host files (`hosts/<hostname>.nix`) to add/remove packages or options
- Editing module files in `modules/`
- Creating or updating documentation in `docs/` or `ABOUTME.md` / `GUIDELINES.md`
- `ABOUTME.md` should be seen as the 'living memory' of a folder, it should contain general information about what's in the folder and capture decisions made at the time of development the features.
- Adding new packages to `pkgs/`
- Editing configs in `configs/`
+171
View File
@@ -0,0 +1,171 @@
# OpenClaw Integration Setup
✅ **Integration Complete!**
I've successfully added OpenClaw to your nixos-setup with a simple NixOS systemd service. **No Home Manager required** - it's a pure system service.
## Changes Made
### 1. Updated `flake.nix`
- Added `nix-openclaw` as a new input from `github:openclaw/nix-openclaw`
- Configured it to follow your existing `nixpkgs` and `home-manager` versions
- Added `nix-openclaw` to the outputs destructuring
- Passed `nix-openclaw` through to specialArgs for access in modules
### 2. Created `modules/nixos/server/services/openclaw.nix`
A complete NixOS module that provides:
- `skyg.nixos.server.services.openclaw.enable` - enable/disable the service
- `skyg.nixos.server.services.openclaw.port` - gateway port (default: 18789)
- `skyg.nixos.server.services.openclaw.gatewayToken` - authentication token
- `skyg.nixos.server.services.openclaw.user` - service user (default: openclaw)
- `skyg.nixos.server.services.openclaw.logLevel` - log level (debug/info/warn/error)
- `skyg.nixos.server.services.openclaw.package` - custom OpenClaw package
Features:
- ✅ Automatic user/group creation
- ✅ Systemd service management (auto-restart on failure)
- ✅ Security hardening (strict filesystem protection, no new privileges, private tmp)
- ✅ Automatic firewall port opening
- ✅ Journal logging integration
### 3. Updated `modules/nixos/server/services/default.nix`
- Added `./openclaw.nix` to the services imports so it's available system-wide
## How to Use
### 1. Enable on a Host
In your host configuration (e.g., `hosts/hl-minipc3.nix`):
```nix
skyg.nixos.server.services.openclaw = {
enable = true;
port = 18789;
gatewayToken = "your-secret-gateway-token";
logLevel = "info";
};
```
### 2. Manage Configuration
Configuration happens via:
- **Environment variables**: Set via the service `environment` config
- **Config file** (optional): Point to `/etc/openclaw/openclaw.json` via the `configFile` option
- **Default behavior**: Service auto-creates `/var/lib/openclaw` as its working directory
### 3. Apply Changes
```bash
# Rebuild the system
sudo nixos-rebuild switch
# Or if using home-manager:
home-manager switch --flake .#
```
### 4. Verify It's Running
```bash
# Check service status
systemctl status openclaw-gateway
# View logs
journalctl -u openclaw-gateway -f
# Test gateway locally
curl http://localhost:18789/health
```
## Simple Example Configuration
```nix
# In hosts/hl-minipc3.nix or similar
skyg.nixos.server.services.openclaw = {
enable = true;
port = 18789;
gatewayToken = "mySecretToken123";
};
```
That's it! The service will:
- Run as the `openclaw` user
- Listen on port 18789
- Auto-restart if it crashes
- Log to systemd journal
- Protect filesystem access (strict sandbox)
## Multiple Instances
If you want multiple OpenClaw gateways on the same host with different ports:
```nix
# You'd need to duplicate the service with different names
# This is currently not supported by the module but could be extended
# Just ask if you need this!
```
## Debugging
View real-time logs:
```bash
journalctl -u openclaw-gateway -f
```
Check service details:
```bash
systemctl cat openclaw-gateway
```
View environment variables:
```bash
systemctl show -p Environment openclaw-gateway
```
## Architecture
```
flake.nix (nix-openclaw input)
↓
modules/lib.nix (specialArgs)
↓
modules/nixos/server/services/openclaw.nix
↓
systemd.services.openclaw-gateway
↓
/var/lib/openclaw (working directory)
```
## Next Steps
1. Choose a host where you want OpenClaw (e.g., `hl-minipc3`, `hl-bigbox1`)
2. Add the `skyg.nixos.server.services.openclaw` config to that host
3. Set your `gatewayToken` (generate a secure token)
4. Run `nixos-rebuild switch`
5. Monitor with `journalctl -u openclaw-gateway -f`
## Resources
- [nix-openclaw GitHub](https://github.com/openclaw/nix-openclaw)
- [OpenClaw Documentation](https://docs.openclaw.ai/)
- [NixOS Systemd Services](https://nixos.org/manual/nixos/stable/#sec-systemd-services)
## Troubleshooting
**Service won't start:**
```bash
journalctl -u openclaw-gateway -n 50
```
**Port already in use:**
Change the port in your config:
```nix
skyg.nixos.server.services.openclaw.port = 18790;
```
**Package not found:**
The module defaults to `pkgs.openclaw`. If this doesn't exist in nixpkgs yet, use the nix-openclaw flake output:
```nix
skyg.nixos.server.services.openclaw.package = nix-openclaw.packages.${system}.openclaw;
```
(You'd need to pass it through specialArgs or adjust the module)
+12
View File
@@ -94,6 +94,18 @@ skyg rollback
skyg hm switch
```
## Managing Secrets
Secrets are encrypted using [agenix](https://github.com/ryantm/agenix) and stored in `secrets/`.
### Adding a Host to Secrets
1. **Get the host's SSH public key**: `cat /etc/ssh/ssh_host_ed25519_key.pub`
2. **Add to `secrets.nix`**: Create a variable with the key and add it to each secret's `publicKeys` list
3. **Re-key**: Run `skyg secrets rekey` to re-encrypt the `.age` files
For more details, see `secrets/ABOUTME.md`.
## Host Profiles
Available profiles include:
Generated
+128 -8
View File
@@ -334,6 +334,24 @@
"type": "github"
}
},
"flake-utils": {
"inputs": {
"systems": "systems_3"
},
"locked": {
"lastModified": 1731533236,
"narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
"owner": "numtide",
"repo": "flake-utils",
"rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
"type": "github"
},
"original": {
"owner": "numtide",
"repo": "flake-utils",
"type": "github"
}
},
"fromYaml": {
"flake": false,
"locked": {
@@ -815,10 +833,54 @@
"type": "github"
}
},
"nixos-hardware": {
"nix-openclaw": {
"inputs": {
"flake-utils": "flake-utils",
"home-manager": [
"home-manager"
],
"nix-openclaw-tools": "nix-openclaw-tools",
"nixpkgs": [
"nixpkgs"
],
"qmd": "qmd"
},
"locked": {
"lastModified": 1782272238,
"narHash": "sha256-S14YkgSz+/z60qhtd/hDsxv2mNPzgoshUlgHLBYWc68=",
"owner": "openclaw",
"repo": "nix-openclaw",
"rev": "6f232e89add5e3ed03f316c224357e73f51d006a",
"type": "github"
},
"original": {
"owner": "openclaw",
"repo": "nix-openclaw",
"type": "github"
}
},
"nix-openclaw-tools": {
"inputs": {
"nixpkgs": "nixpkgs_6"
},
"locked": {
"lastModified": 1778060041,
"narHash": "sha256-tXWkN1VnwFG8XlRqW/e7VwbKnUfyU9tB7YDm9QHJXTY=",
"owner": "openclaw",
"repo": "nix-openclaw-tools",
"rev": "4c1cee3c7eaf68f9de0f756be1484534f5bb5f34",
"type": "github"
},
"original": {
"owner": "openclaw",
"repo": "nix-openclaw-tools",
"type": "github"
}
},
"nixos-hardware": {
"inputs": {
"nixpkgs": "nixpkgs_7"
},
"locked": {
"lastModified": 1780310866,
"narHash": "sha256-fPBRVf6A5xlACYcOI59shGrjURuvwu0lRsDoSCEXt/I=",
@@ -957,6 +1019,22 @@
}
},
"nixpkgs_6": {
"locked": {
"lastModified": 1767364772,
"narHash": "sha256-fFUnEYMla8b7UKjijLnMe+oVFOz6HjijGGNS1l7dYaQ=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "16c7794d0a28b5a37904d55bcca36003b9109aaa",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixpkgs-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs_7": {
"locked": {
"lastModified": 1767892417,
"narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=",
@@ -969,7 +1047,7 @@
"url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
}
},
"nixpkgs_7": {
"nixpkgs_8": {
"locked": {
"lastModified": 1780203844,
"narHash": "sha256-K5sT4jTpGs15ADhviMKNBH38REpPf5Q6mM1+N6cArVE=",
@@ -1010,7 +1088,7 @@
"noctalia",
"nixpkgs"
],
"systems": "systems_3",
"systems": "systems_4",
"treefmt-nix": "treefmt-nix"
},
"locked": {
@@ -1161,6 +1239,32 @@
"type": "github"
}
},
"qmd": {
"inputs": {
"flake-utils": [
"nix-openclaw",
"flake-utils"
],
"nixpkgs": [
"nix-openclaw",
"nixpkgs"
]
},
"locked": {
"lastModified": 1775429264,
"narHash": "sha256-bqIVaNRTa8H5vrw3RwsD7QdtTa0xNvRuEVzlzE1hIBQ=",
"owner": "tobi",
"repo": "qmd",
"rev": "65cd1b3fd02891d1ee0eefa751620918664fa321",
"type": "github"
},
"original": {
"owner": "tobi",
"ref": "v2.1.0",
"repo": "qmd",
"type": "github"
}
},
"quickshell": {
"inputs": {
"nixpkgs": [
@@ -1195,12 +1299,13 @@
"nix-darwin": "nix-darwin",
"nix-flatpak": "nix-flatpak",
"nix-index-database": "nix-index-database",
"nix-openclaw": "nix-openclaw",
"nixos-hardware": "nixos-hardware",
"nixpkgs": "nixpkgs_7",
"nixpkgs": "nixpkgs_8",
"nixpkgs-unstable": "nixpkgs-unstable",
"noctalia": "noctalia",
"stylix": "stylix",
"systems": "systems_5"
"systems": "systems_6"
}
},
"stylix": {
@@ -1216,7 +1321,7 @@
"nixpkgs"
],
"nur": "nur",
"systems": "systems_4",
"systems": "systems_5",
"tinted-kitty": "tinted-kitty",
"tinted-schemes": "tinted-schemes",
"tinted-tmux": "tinted-tmux",
@@ -1268,6 +1373,21 @@
}
},
"systems_3": {
"locked": {
"lastModified": 1681028828,
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
"owner": "nix-systems",
"repo": "default",
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
"type": "github"
},
"original": {
"owner": "nix-systems",
"repo": "default",
"type": "github"
}
},
"systems_4": {
"locked": {
"lastModified": 1689347949,
"narHash": "sha256-12tWmuL2zgBgZkdoB6qXZsgJEH9LR3oUgpaQq2RbI80=",
@@ -1282,7 +1402,7 @@
"type": "github"
}
},
"systems_4": {
"systems_5": {
"locked": {
"lastModified": 1681028828,
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
@@ -1297,7 +1417,7 @@
"type": "github"
}
},
"systems_5": {
"systems_6": {
"locked": {
"lastModified": 1681028828,
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+8
View File
@@ -50,6 +50,12 @@
hyprlauncher.url = "github:hyprwm/hyprlauncher";
# Secrets management
agenix.url = "github:ryantm/agenix";
# OpenClaw AI gateway with Nix packaging
nix-openclaw = {
url = "github:openclaw/nix-openclaw";
inputs.nixpkgs.follows = "nixpkgs";
inputs.home-manager.follows = "home-manager";
};
};
outputs =
@@ -70,6 +76,7 @@
, nix-index-database
, agenix
, hermes-agent
, nix-openclaw
}:
let
# Libs
@@ -101,6 +108,7 @@
noctalia
nix-index-database
hermes-agent
nix-openclaw
;
};
}
+43
View File
@@ -0,0 +1,43 @@
# modules/core/
Cross-platform base configuration imported by **every** host (NixOS and macOS) via
`modules/main.nix`. This is where the primary user, Nix binary caches, distributed builds,
and a couple of nixpkgs overlays/workarounds live.
## Files
```
core/
├── default.nix # Entry point: imports the files below + overlays + remote builder
├── user.nix # skyg.user.* — the human user + Home Manager wiring
├── nix-substituters.nix # skyg.core.substituters.* — binary caches & trusted keys
└── macos.nix # skyg.user.macos.enableOverride — macOS-only HM tweaks
```
## What lives here
- **Overlays** (`default.nix`): exposes `pkgs.grok-cli` (from `pkgs/grok-cli`) and patches
`python3Packages.pipx` to skip its flaky install check on nixpkgs 26.05.
- **Distributed builds** (`default.nix`): registers `bigbox1.lab.internal` as a remote
`x86_64-linux` build machine and enables `builders-use-substitutes`.
- **User** (`user.nix`): defines `skyg.user.{name,fullName,email}` plus
`skyg.home-manager.{version,extraImports}`. When `skyg.user.enable` is set it wires up
Home Manager for both `root` and the named user using the functions in `modules/home`.
- **Substituters** (`nix-substituters.nix`): the standing list of caches (local `minipc1`
cache, cache.nixos.org, cachix caches for cuda/cosmic/ai/noctalia, flox, devenv) and the
trusted public keys. Extra entries can be appended per-host via `skyg.core.substituters.{urls,keys}`.
## Option Namespace
```
skyg.user.* → user.nix (+ macos.nix for the macOS override)
skyg.home-manager.* → user.nix
skyg.core.substituters.* → nix-substituters.nix
```
## Conventions
- `skyg.user.enable` triggers Home Manager setup and asserts that `name`, `fullName`, and
`email` are non-empty.
- Cache URLs/keys here are global defaults; add host-specific caches through the
`skyg.core.substituters.{urls,keys}` options rather than editing this file.
+46
View File
@@ -0,0 +1,46 @@
# modules/home/
The Home Manager layer. **Unlike the rest of the repo, these files are not NixOS modules** —
they are plain functions that return Home Manager attribute sets. `core/user.nix` imports
this directory and calls the exported builders to populate `home-manager.users.<name>`.
## Files
```
home/
├── default.nix # Exports makeRootUser and makeCommonUser; composes the modules below
├── programs.nix # programs.* — shell + CLI tooling (zsh, nushell, neovim, starship, …)
├── services.nix # services.* — gpg-agent with SSH support
├── git.nix # makeCommonGitConfigs — git/delta config + includes from gitconfigs/
├── fonts.nix # fontconfig default font families
└── gitconfigs/ # Raw .gitconfig fragments included by every user (aliases, …)
```
## Entry points
`default.nix` exports two builder functions, both consumed by `core/user.nix`:
- `makeRootUser { hostName }` — minimal root profile (jq, kubectl, btop, …) with a
`root@<hostName>` git identity.
- `makeCommonUser { name, fullName, email, extraGitConfigs ? [] }` — the full human profile:
dev packages, the shared shell/program config, and the user's git identity.
Both apply the shared `homeModule` (state version + shell aliases like `cat→bat`,
`ls→eza`, `du→dust`, `df→duf`), `programsModule`, `servicesModule`, and `fontsModule`.
## Notable details
- **Shells**: zsh is the login shell, with autosuggestions, syntax highlighting, and a
`notify-send` hook for long-running commands. Nushell, starship, carapace, zellij, and
tmux are all configured here.
- **Git** (`git.nix`): `makeCommonGitConfigs` auto-includes every file under `gitconfigs/`
plus any per-user `extraGitConfigs`. Uses delta for diffs.
- The standalone (non-NixOS) Home Manager path in `modules/lib.nix`
(`makeHomeManagerUsers`) also calls `makeCommonUser`.
## Conventions
- These are **functions, not modules** — there is no `options`/`config`/`lib.mkIf` here.
Keep that pattern; the NixOS module system is applied one level up in `core/user.nix`.
- Add new shared CLI programs to `programs.nix`, services to `services.nix`, and global
packages to the relevant `home.packages` list in `default.nix`.
+47
View File
@@ -0,0 +1,47 @@
# Guidelines — modules/home/
Conventions specific to the Home Manager layer. Read alongside the repo-root `GUIDELINES.md`.
---
## ⚠️ These are functions, not NixOS modules
The biggest gotcha in this directory: the files here are **plain Nix functions that return
attribute sets**, not `{ config, lib, ... }` modules. There is no `options`, no `config`
block, and no `lib.mkIf`.
- `default.nix` exports `makeRootUser` and `makeCommonUser`.
- `programs.nix`, `services.nix`, `git.nix`, `fonts.nix` each export a value/function that
`default.nix` composes.
- The NixOS/HM module system is applied **one level up**, in `modules/core/user.nix`, which
feeds the result into `home-manager.users.<name>`.
Do **not** convert these into module-style files or add `skyg.*` options here — that belongs
in `core/user.nix`.
## Where to add things
| You want to add… | Put it in |
|---|---|
| A shared CLI program (`programs.<x>`) | `programs.nix` |
| A user service (`services.<x>`) | `services.nix` |
| A package for all users | `home.packages` in `default.nix` (`makeCommonUser`) |
| A package for root only | `home.packages` in `makeRootUser` |
| A git alias / git config fragment | a new file in `gitconfigs/` (auto-included) |
| A default font family | `fonts.nix` |
## Things to keep consistent
- **Identity flows in, not hardcoded.** `makeCommonUser` receives `name`/`fullName`/`email`
from `skyg.user.*`. Don't hardcode a username or email here.
- **Root vs human user.** Keep root's profile minimal (admin/cluster tooling); put the full
toolchain in `makeCommonUser`.
- **`makeCommonUser` is reused** by both the NixOS path (`core/user.nix`) and the standalone
Home Manager path (`modules/lib.nix → makeHomeManagerUsers`). Changes affect both.
- **State version** comes from `skyg.home-manager.version`; don't pin a literal here.
## Validation
You cannot meaningfully build HM output without a full switch (which is forbidden — see root
`GUIDELINES.md`). Limit yourself to `nix-instantiate --parse` for syntax. The user validates
by running their switch command.
+20
View File
@@ -0,0 +1,20 @@
# modules/home/gitconfigs/
Raw git config fragments that are auto-included into every user's `~/.gitconfig`.
`modules/home/git.nix` reads every **non-directory** file in this folder and adds it as a
`git.includes` path, so any file dropped here is picked up automatically — no wiring needed.
## Files
```
gitconfigs/
└── alias.conf # [alias] block: pp, up, ca, cap, undo-commit, sync, clean-branches, …
```
## Conventions
- Each file is a standalone git config fragment (e.g. an `[alias]` section). Drop a new
`.conf` file here and it is included on the next switch.
- Keep these provider-agnostic and identity-free; user name/email come from
`skyg.user.{fullName,email}` via `makeCommonGitConfigs`.
+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.
+37
View File
@@ -0,0 +1,37 @@
# modules/openwrt/
Config generator + deploy tooling for the homelab's **OpenWrt** router. This is *not* a NixOS
module — it's a Nix function that builds a Rust generator and wraps it in an
`openwrt-deploy` shell script. OpenWrt is managed out-of-band (the router isn't a NixOS host),
so this provides a declarative, reviewable way to push `dnsmasq.conf` and `/etc/ethers`.
## Structure
```
openwrt/
├── default.nix # Builds the Rust generator + the openwrt-deploy script
└── generator/ # Rust crate (openwrt-gen) that turns a JSON config into OpenWrt files
```
## How it works
1. The router config lives as an **agenix secret** (e.g. `secrets/glmain.json.age`).
2. `openwrt-deploy` reads the decrypted JSON from stdin, runs `openwrt-gen dnsmasq` and
`openwrt-gen ethers` to render the two target files.
3. It SSHes to the router, shows a **colorized diff** against the current files, and prompts
for confirmation before writing.
4. `dnsmasq.conf` is validated with `dnsmasq --test` on the router and **automatically
reverted** if the new config is invalid.
```
age -d secrets/glmain.json.age | openwrt-deploy
```
`router.ip` / `router.user` are taken from the `config` passed into `default.nix`.
## Conventions
- The router config is a **secret** — decrypt it on the fly; never commit the plaintext JSON.
- Deploys are interactive and reviewed by a human; the script intentionally requires
confirmation and self-reverts on a bad dnsmasq config.
- `generator/target/` is gitignored Rust build output — ignore it.
+44
View File
@@ -0,0 +1,44 @@
# modules/openwrt/generator/
`openwrt-gen` — a small Rust CLI that converts a single JSON network description into OpenWrt
config files. Built by `../default.nix` with `rustPlatform.buildRustPackage` and invoked by
the `openwrt-deploy` script.
## Layout
```
generator/
├── Cargo.toml # crate metadata; deps: serde, serde_json
├── Cargo.lock # pinned for the Nix build (cargoLock.lockFile)
├── src/
│ ├── main.rs # CLI entry: reads JSON from stdin, dispatches on argv[1]
│ ├── config.rs # serde Deserialize structs for the input JSON (+ unit tests)
│ ├── network.rs # process_network — expands per-network device lists
│ └── generators/
│ ├── mod.rs # re-exports dnsmasq + ethers
│ ├── dnsmasq.rs # renders dnsmasq.conf (server= + address= lines)
│ └── ethers.rs # renders /etc/ethers (MAC → name/IP)
└── target/ # gitignored Cargo build output — ignore it
```
## Usage
```
openwrt-gen dnsmasq < config.json # prints dnsmasq.conf
openwrt-gen ethers < config.json # prints /etc/ethers
```
## Input shape (`config.rs`)
- `generalMappings`: `[{ ip, domains[] }]` — shared domain→IP records.
- `networks`: `{ <network>: [ { mac, name, id?, domains?, justMac? } ] }` — per-network hosts.
- `dnsResolvers`: `[{ ip, port?, name? }]` — upstream `server=` entries for dnsmasq.
## Conventions
- This crate has **no I/O of its own** beyond stdin/stdout — config decryption and SSH
delivery are the deploy script's job. Keep it a pure JSON → text transformer.
- `config.rs` carries unit tests; run `cargo test` here when changing the parser. Building
the Nix package is fine (it doesn't touch a live system), but is not required — the user
validates deploys via `openwrt-deploy`.
- Keep `Cargo.lock` committed and in sync (the Nix build pins to it).
+12
View File
@@ -4,6 +4,7 @@ let
minipc2 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDqi2WT0pa8m+kZNN2Rrg1F01zwTvkCwD3wjSOBNvSjz root@nixos";
minipc3 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEbvoe/UvhpRSWVXMCyj/qzuR7WnJdNF7CYRmmJE3yYu root@minisf1";
terra1 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHBKI8gqd7DDubShle4D3JGq61BP1NBKCZ81V3C9uyym root@nixos";
fwdesk = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHbBcdMpNPaELUzHRIoRkTUQde+mBQ87Ra2R+974FuUy root@hl-fwdesk";
in
{
"secrets/dns-addresses.conf.age".publicKeys = [
@@ -12,8 +13,19 @@ in
minipc2
minipc3
terra1
fwdesk
];
# Decrypted at deploy time by the user running `skyg openwrt`
"secrets/glmain.json.age".publicKeys = [ ari ];
# OpenClaw gateway authentication token
"secrets/openclaw-token.age".publicKeys = [
ari
minipc1
minipc2
minipc3
terra1
fwdesk
];
}