Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 marthsincemelee
|
136b8b43c0 | ||
|
marthsincemelee
|
d8bceae6e8 | ||
|
marthsincemelee
|
8c49a0a326 | ||
|
marthsincemelee
|
2788c9641f |
@@ -0,0 +1,269 @@
|
||||
# ntfy Notification Module Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add a `my.profiles.ntfy` NixOS module that runs an auth-required self-hosted ntfy server on jupiter, exposes a homepage tile, and wires a Home Assistant `rest_command` for publishing notifications.
|
||||
|
||||
**Architecture:** A single profile module under `modules/environments/ntfy/`, following the repo's `my.profiles.<name>` pattern. It configures `services.ntfy-sh` with `auth-default-access = deny-all`, opens the firewall, registers a homepage tile, and — when the home-assistant profile is enabled — merges a `rest_command.ntfy_send` into `services.home-assistant.config`. No secrets touch the Nix store; credentials are provisioned manually by the operator, and the only secret lives in HA's `secrets.yaml`.
|
||||
|
||||
**Tech Stack:** Nix (flake-parts NixOS config), nixpkgs `services.ntfy-sh`, `services.home-assistant`, nixfmt-rfc-style.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Follow the profile pattern exactly: `let cfg = config.my.profiles.<name>; in { options.my.profiles.<name>.enable = lib.mkEnableOption "..."; config = lib.mkIf cfg.enable { ... }; }`.
|
||||
- Namespace is `my.profiles.ntfy`.
|
||||
- Homepage self-registration uses `my.homepage.services` (list of `{ group; name; description; href; icon; }`).
|
||||
- `hostName` is bound from `config.networking.hostName`, matching sibling modules.
|
||||
- All `.nix` files must be formatted with `nixfmt-rfc-style`.
|
||||
- No secret values may appear in any `.nix` file (nothing enters the Nix store). The only secret is `ntfy_password` in `/var/lib/hass/secrets.yaml`, provisioned by hand.
|
||||
- Evaluation check used throughout (runs on darwin without a Linux builder):
|
||||
`nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
|
||||
- Do NOT run `nixos-rebuild` or SSH to jupiter; deploy + provisioning are operator steps the user runs on the host.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create the ntfy server module (server + homepage tile)
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/environments/ntfy/default.nix`
|
||||
- Modify: `modules/environments/default.nix` (add `./ntfy` to `imports`)
|
||||
- Modify: `machines/jupiter/environments.nix` (enable the profile)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `config.networking.hostName`; `services.ntfy-sh` (nixpkgs); `my.homepage.services` (repo homepage module).
|
||||
- Produces: option `my.profiles.ntfy.enable` (bool), `my.profiles.ntfy.port` (port, default 2586), `my.profiles.ntfy.topic` (str, default "ha"), `my.profiles.ntfy.haIntegration.enable` (bool, default true). Later tasks rely on `cfg.port`, `cfg.topic`, and `cfg.haIntegration.enable`.
|
||||
|
||||
- [ ] **Step 1: Create the module file**
|
||||
|
||||
Create `modules/environments/ntfy/default.nix`:
|
||||
|
||||
```nix
|
||||
# self-hosted push notification server (ntfy)
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
...
|
||||
}:
|
||||
let
|
||||
cfg = config.my.profiles.ntfy;
|
||||
hostName = config.networking.hostName;
|
||||
in
|
||||
{
|
||||
options.my.profiles.ntfy = with lib; {
|
||||
enable = mkEnableOption "ntfy notification server";
|
||||
|
||||
port = mkOption {
|
||||
type = types.port;
|
||||
default = 2586;
|
||||
description = "HTTP port ntfy listens on.";
|
||||
};
|
||||
|
||||
topic = mkOption {
|
||||
type = types.str;
|
||||
default = "ha";
|
||||
description = "Topic Home Assistant publishes notifications to.";
|
||||
};
|
||||
|
||||
haIntegration.enable = mkOption {
|
||||
type = types.bool;
|
||||
default = true;
|
||||
description = "Wire a Home Assistant rest_command that publishes to ntfy.";
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
services.ntfy-sh = {
|
||||
enable = true;
|
||||
settings = {
|
||||
base-url = "http://${hostName}:${toString cfg.port}";
|
||||
listen-http = ":${toString cfg.port}";
|
||||
auth-file = "/var/lib/ntfy-sh/user.db";
|
||||
auth-default-access = "deny-all";
|
||||
};
|
||||
};
|
||||
|
||||
networking.firewall.allowedTCPPorts = [ cfg.port ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Services";
|
||||
name = "ntfy";
|
||||
description = "Push notifications";
|
||||
href = "http://${hostName}:${toString cfg.port}";
|
||||
icon = "ntfy.svg";
|
||||
}
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Register the module in the environments import list**
|
||||
|
||||
In `modules/environments/default.nix`, add `./ntfy` to the `imports` list (place it near the other service modules, e.g. after `./home-assistant`):
|
||||
|
||||
```nix
|
||||
./home-assistant
|
||||
./ntfy
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Enable the profile on jupiter**
|
||||
|
||||
In `machines/jupiter/environments.nix`, inside the `my.profiles = { ... }` block, add:
|
||||
|
||||
```nix
|
||||
ntfy.enable = true;
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Format the new file**
|
||||
|
||||
Run: `nixfmt-rfc-style modules/environments/ntfy/default.nix`
|
||||
Expected: exits 0, no diff on re-run.
|
||||
|
||||
- [ ] **Step 5: Evaluate the configuration**
|
||||
|
||||
Run: `nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
|
||||
Expected: prints a `/nix/store/...-nixos-system-jupiter-*.drv` path with no evaluation errors. (This forces full module-system evaluation, catching option/type mistakes, without building a Linux derivation.)
|
||||
|
||||
- [ ] **Step 6: Confirm the ntfy settings evaluate as expected**
|
||||
|
||||
Run: `nix eval --json '.#nixosConfigurations.jupiter.config.services.ntfy-sh.settings'`
|
||||
Expected JSON includes `"auth-default-access":"deny-all"`, `"listen-http":":2586"`, and `"base-url":"http://jupiter:2586"`.
|
||||
|
||||
- [ ] **Step 7: Commit**
|
||||
|
||||
```bash
|
||||
git add modules/environments/ntfy/default.nix modules/environments/default.nix machines/jupiter/environments.nix
|
||||
git commit -m "feat(ntfy): add self-hosted notification server module
|
||||
|
||||
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Wire the Home Assistant rest_command
|
||||
|
||||
**Files:**
|
||||
- Modify: `modules/environments/ntfy/default.nix` (add HA integration block)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `cfg.port`, `cfg.topic`, `cfg.haIntegration.enable` (Task 1); `config.my.profiles.home-assistant.enable`; `services.home-assistant.config` (nixpkgs / repo home-assistant module).
|
||||
- Produces: `services.home-assistant.config.rest_command.ntfy_send`, callable from HA automations as `service: rest_command.ntfy_send`.
|
||||
|
||||
- [ ] **Step 1: Add the HA integration block to the module**
|
||||
|
||||
The module currently has a single `config = lib.mkIf cfg.enable { ... };`. Change it to merge two conditional configs with `lib.mkMerge` so the HA wiring is gated independently. Replace the `config = lib.mkIf cfg.enable { ... };` assignment with:
|
||||
|
||||
```nix
|
||||
config = lib.mkMerge [
|
||||
(lib.mkIf cfg.enable {
|
||||
services.ntfy-sh = {
|
||||
enable = true;
|
||||
settings = {
|
||||
base-url = "http://${hostName}:${toString cfg.port}";
|
||||
listen-http = ":${toString cfg.port}";
|
||||
auth-file = "/var/lib/ntfy-sh/user.db";
|
||||
auth-default-access = "deny-all";
|
||||
};
|
||||
};
|
||||
|
||||
networking.firewall.allowedTCPPorts = [ cfg.port ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Services";
|
||||
name = "ntfy";
|
||||
description = "Push notifications";
|
||||
href = "http://${hostName}:${toString cfg.port}";
|
||||
icon = "ntfy.svg";
|
||||
}
|
||||
];
|
||||
})
|
||||
|
||||
(lib.mkIf (cfg.enable && cfg.haIntegration.enable && config.my.profiles.home-assistant.enable) {
|
||||
services.home-assistant.config.rest_command.ntfy_send = {
|
||||
url = "http://${hostName}:${toString cfg.port}/${cfg.topic}";
|
||||
method = "POST";
|
||||
payload = "{{ message }}";
|
||||
content_type = "text/plain";
|
||||
username = "homeassistant";
|
||||
password = "!secret ntfy_password";
|
||||
headers = {
|
||||
Title = "{{ title | default('Home Assistant') }}";
|
||||
Priority = "{{ priority | default('default') }}";
|
||||
};
|
||||
};
|
||||
})
|
||||
];
|
||||
```
|
||||
|
||||
(The first `mkIf cfg.enable` block is identical to Task 1's config body — it is repeated here because the whole `config` assignment is being replaced with the `mkMerge` form.)
|
||||
|
||||
- [ ] **Step 2: Format the file**
|
||||
|
||||
Run: `nixfmt-rfc-style modules/environments/ntfy/default.nix`
|
||||
Expected: exits 0, no diff on re-run.
|
||||
|
||||
- [ ] **Step 3: Evaluate the configuration**
|
||||
|
||||
Run: `nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
|
||||
Expected: prints a `.drv` path, no evaluation errors (confirms the `rest_command` merges cleanly into the HA config the home-assistant module already defines).
|
||||
|
||||
- [ ] **Step 4: Confirm the rest_command evaluated into HA config**
|
||||
|
||||
Run: `nix eval --json '.#nixosConfigurations.jupiter.config.services.home-assistant.config.rest_command.ntfy_send'`
|
||||
Expected JSON includes `"url":"http://jupiter:2586/ha"`, `"username":"homeassistant"`, and `"password":"!secret ntfy_password"`.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add modules/environments/ntfy/default.nix
|
||||
git commit -m "feat(ntfy): wire Home Assistant rest_command publisher
|
||||
|
||||
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Operator steps (run by the user on jupiter — not part of the agent's task loop)
|
||||
|
||||
These require the host and manual credentials, so they are performed by the user after the branch is merged/deployed:
|
||||
|
||||
1. Deploy: `sudo nixos-rebuild switch --flake '.#jupiter'`
|
||||
2. Create ntfy users:
|
||||
```bash
|
||||
ntfy user add homeassistant # set a password
|
||||
ntfy access homeassistant ha write-only
|
||||
ntfy user add --role=admin admin
|
||||
```
|
||||
3. Add the publisher password to Home Assistant secrets:
|
||||
```yaml
|
||||
# /var/lib/hass/secrets.yaml
|
||||
ntfy_password: <the homeassistant user's password>
|
||||
```
|
||||
4. Restart Home Assistant, then test from an automation / Developer Tools:
|
||||
```yaml
|
||||
service: rest_command.ntfy_send
|
||||
data:
|
||||
message: "ntfy test"
|
||||
title: "Home Assistant"
|
||||
priority: high
|
||||
```
|
||||
5. Subscribe from the ntfy app as `admin` to receive the message.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**Spec coverage:**
|
||||
- Module structure + options → Task 1. ✔
|
||||
- Server config (deny-all, port, firewall) → Task 1 (steps 1, 6). ✔
|
||||
- Homepage tile → Task 1. ✔
|
||||
- Registration in `default.nix` + enable on jupiter → Task 1 (steps 2–3). ✔
|
||||
- HA `rest_command` wiring, gated on HA profile, `!secret` password → Task 2. ✔
|
||||
- Manual provisioning runbook → Operator steps section. ✔
|
||||
- Verification (eval/build + nixfmt) → per-task steps. ✔
|
||||
- Out-of-scope items (no seeding, no sops, no reverse proxy) → honored; no tasks added for them. ✔
|
||||
|
||||
**Placeholder scan:** No TBD/TODO/"handle edge cases". The one "similar to Task 1" note is accompanied by the full repeated code, per the no-placeholders rule. ✔
|
||||
|
||||
**Type consistency:** `cfg.port`/`cfg.topic`/`cfg.haIntegration.enable` defined in Task 1 and used identically in Task 2. `rest_command.ntfy_send` name consistent across Task 2 and operator steps. Homepage tile shape matches sibling modules. ✔
|
||||
@@ -1,154 +0,0 @@
|
||||
# Jellyfin Hardware Transcoding (jupiter) Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Give jupiter's Jellyfin service access to the Intel iGPU's VAAPI render node so Quick Sync hardware transcoding can be enabled, instead of every transcode falling back to CPU.
|
||||
|
||||
**Architecture:** One NixOS module change (`modules/environments/jellyfin/default.nix`) grants the `jellyfin` systemd service supplementary access to the `video`/`render` groups and installs `libva-utils` for verification. This is declarative and build-verifiable from the Mac. Enabling Quick Sync inside Jellyfin's own dashboard, and the on-machine verification, is a manual step run by the user on jupiter after deploy — the NixOS module has no option for it and this environment's convention is that the assistant never SSHes into jupiter directly (see `docs/superpowers/specs/2026-07-26-jellyfin-hw-transcoding.md`).
|
||||
|
||||
**Tech Stack:** NixOS (flake-parts), nixpkgs `services.jellyfin` module, VAAPI/`intel-media-driver`, `libva-utils`.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- No SSH from the assistant into jupiter — all on-machine commands are given to the user to run and paste back.
|
||||
- Follow the existing profile pattern in `modules/environments/jellyfin/default.nix` (`config = lib.mkIf cfg.enable { ... }`); don't introduce a new toggle option — hardcode the hardware-acceleration wiring on, per the approved spec.
|
||||
- Verify locally via `nix eval` / `nix build` before asking the user to deploy.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Grant Jellyfin access to the iGPU and verify the build
|
||||
|
||||
**Files:**
|
||||
- Modify: `modules/environments/jellyfin/default.nix`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [ "video" "render" ];` — verified via `nix eval` in Step 2.
|
||||
|
||||
- [ ] **Step 1: Add the device-access config and `libva-utils` package**
|
||||
|
||||
Read the current file first (`modules/environments/jellyfin/default.nix`), then edit the `config = lib.mkIf cfg.enable { ... }` block so it reads:
|
||||
|
||||
```nix
|
||||
config = lib.mkIf cfg.enable {
|
||||
services.jellyfin = {
|
||||
enable = true;
|
||||
openFirewall = true;
|
||||
};
|
||||
|
||||
environment.systemPackages = [ pkgs.libva-utils ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Media";
|
||||
name = "Jellyfin";
|
||||
description = "Media server";
|
||||
href = "http://${hostName}:${toString port}";
|
||||
icon = "jellyfin.png";
|
||||
}
|
||||
];
|
||||
|
||||
systemd.services.jellyfin = {
|
||||
after = [ "network-online.target" ];
|
||||
serviceConfig.SupplementaryGroups = [
|
||||
"video"
|
||||
"render"
|
||||
];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Note the two existing `systemd.services.jellyfin` keys (`after`) and the new `serviceConfig.SupplementaryGroups` now live in the same attrset — don't create a second `systemd.services.jellyfin = { ... }` block, it would overwrite the first.
|
||||
|
||||
- [ ] **Step 2: Verify the rendered config with `nix eval`**
|
||||
|
||||
Run (from the repo root on the Mac):
|
||||
|
||||
```bash
|
||||
nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
|
||||
--extra-experimental-features 'nix-command flakes'
|
||||
```
|
||||
|
||||
Expected output: `[ "video" "render" ]`
|
||||
|
||||
- [ ] **Step 3: Verify the machine still builds**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel' \
|
||||
--extra-experimental-features 'nix-command flakes' --no-link
|
||||
```
|
||||
|
||||
Expected: build succeeds with no errors (may take a while; watch for any evaluation error mentioning `jellyfin` or `libva-utils`).
|
||||
|
||||
- [ ] **Step 4: Format and commit**
|
||||
|
||||
```bash
|
||||
nixfmt-rfc-style modules/environments/jellyfin/default.nix
|
||||
git add modules/environments/jellyfin/default.nix
|
||||
git commit -m "feat(jellyfin): grant iGPU access for Quick Sync hardware transcoding"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Deploy on jupiter and enable Quick Sync (user-executed)
|
||||
|
||||
**Files:** none (on-machine deploy + Jellyfin dashboard UI)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: the `SupplementaryGroups` change from Task 1, already merged into the flake.
|
||||
|
||||
These steps run **on jupiter**, by the user — paste the output back so we can confirm each one before moving to the next.
|
||||
|
||||
- [ ] **Step 1: Deploy**
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake '.#jupiter'
|
||||
```
|
||||
|
||||
Expected: switch succeeds, no errors mentioning `jellyfin`.
|
||||
|
||||
- [ ] **Step 2: Confirm the service picked up the new groups**
|
||||
|
||||
```bash
|
||||
systemctl show jellyfin -p SupplementaryGroups
|
||||
systemctl status jellyfin --no-pager
|
||||
```
|
||||
|
||||
Expected: `SupplementaryGroups=video render` (order may vary) and the service is `active (running)`.
|
||||
|
||||
- [ ] **Step 3: Confirm VAAPI driver loads**
|
||||
|
||||
```bash
|
||||
vainfo
|
||||
```
|
||||
|
||||
Expected: output starts with something like `vainfo: VA-API version: 1.x` and `Driver version: Intel iHD driver`, followed by a list of supported VAProfiles/VAEntrypoints (e.g. `VAProfileH264Main : VAEntrypointVLD`, `VAEntrypointEncSlice`).
|
||||
|
||||
If this instead prints a permissions or "no VA display" error, paste it back — that means the group grant isn't reaching the process and Task 1 needs a follow-up fix (e.g. the jellyfin service may be more sandboxed than expected, requiring an explicit `DeviceAllow=char-drm rw` in `serviceConfig` as well).
|
||||
|
||||
- [ ] **Step 4: Enable Quick Sync in the Jellyfin dashboard**
|
||||
|
||||
In the Jellyfin web UI:
|
||||
1. **Dashboard → Playback**.
|
||||
2. Hardware acceleration: **Intel QuickSync (QSV)**.
|
||||
3. VA-API device: `/dev/dri/renderD128`.
|
||||
4. Enable hardware decoding for the codecs your library uses (H264 at minimum).
|
||||
5. If the library has HDR content, enable tone-mapping.
|
||||
6. Save.
|
||||
|
||||
- [ ] **Step 5: Functional check**
|
||||
|
||||
Play a file that requires transcoding (or force a lower quality in the client's playback settings to trigger one), then:
|
||||
|
||||
```bash
|
||||
journalctl -u jellyfin -n 50 --no-pager
|
||||
```
|
||||
|
||||
Look for a line referencing `qsv` or `vaapi` in the transcode command. Separately, watch CPU usage (`htop`) during playback — it should stay low on the core doing the transcode, rather than pegging at 100%, since the iGPU is now doing the encode/decode work.
|
||||
|
||||
## Self-Review Notes
|
||||
|
||||
- Spec coverage: NixOS change (Task 1) ✓, manual dashboard step (Task 2 Step 4) ✓, verification via `vainfo`/build (Task 1 Step 2-3, Task 2 Step 3) ✓, functional check (Task 2 Step 5) ✓. Toggle option explicitly excluded per approved spec — not present, correctly.
|
||||
- No placeholders — every step has literal commands/code.
|
||||
- `SupplementaryGroups` key/value matches exactly between Task 1 (produced) and Task 2 (consumed/checked).
|
||||
@@ -0,0 +1,176 @@
|
||||
# ntfy self-hosted notification module — design
|
||||
|
||||
Date: 2026-07-05
|
||||
Target machine: jupiter
|
||||
|
||||
## Purpose
|
||||
|
||||
Add a NixOS profile module that runs and configures a self-hosted
|
||||
[ntfy](https://ntfy.sh) notification server on jupiter, with authentication
|
||||
required, a homepage dashboard tile, and out-of-the-box plumbing so Home
|
||||
Assistant automations can publish push notifications.
|
||||
|
||||
## Scope decisions (from brainstorming)
|
||||
|
||||
- **Service:** ntfy (self-hosted server), not Apprise/Gotify/HA-only.
|
||||
- **Access control:** authentication required (`auth-default-access = deny-all`).
|
||||
- **Home Assistant:** the module wires an HA `rest_command` so automations can
|
||||
send notifications out of the box.
|
||||
- **Credentials:** fully manual. The module runs the server and wires the HA
|
||||
plumbing, but does **not** seed users or store any secret. The operator
|
||||
provisions ntfy users/passwords by hand, and the only secret lives in Home
|
||||
Assistant's `secrets.yaml` — never in the world-readable Nix store.
|
||||
|
||||
## Module structure
|
||||
|
||||
New module at `modules/environments/ntfy/default.nix` following the repo's
|
||||
standard profile pattern (`my.profiles.<name>` with `options` +
|
||||
`config = lib.mkIf cfg.enable { ... }`).
|
||||
|
||||
Registration:
|
||||
1. Add `./ntfy` to the `imports` list in `modules/environments/default.nix`.
|
||||
2. Enable via `my.profiles.ntfy.enable = true;` in
|
||||
`machines/jupiter/environments.nix`.
|
||||
|
||||
### Options
|
||||
|
||||
```nix
|
||||
options.my.profiles.ntfy = with lib; {
|
||||
enable = mkEnableOption "ntfy notification server";
|
||||
|
||||
port = mkOption {
|
||||
type = types.port;
|
||||
default = 2586;
|
||||
description = "HTTP port ntfy listens on.";
|
||||
};
|
||||
|
||||
topic = mkOption {
|
||||
type = types.str;
|
||||
default = "ha";
|
||||
description = "Topic Home Assistant publishes notifications to.";
|
||||
};
|
||||
|
||||
haIntegration.enable = mkOption {
|
||||
type = types.bool;
|
||||
default = true;
|
||||
description = "Wire a Home Assistant rest_command that publishes to ntfy.";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Server configuration
|
||||
|
||||
```nix
|
||||
config = lib.mkIf cfg.enable {
|
||||
services.ntfy-sh = {
|
||||
enable = true;
|
||||
settings = {
|
||||
base-url = "http://${hostName}:${toString cfg.port}";
|
||||
listen-http = ":${toString cfg.port}";
|
||||
auth-file = "/var/lib/ntfy-sh/user.db";
|
||||
auth-default-access = "deny-all";
|
||||
};
|
||||
};
|
||||
|
||||
networking.firewall.allowedTCPPorts = [ cfg.port ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Services";
|
||||
name = "ntfy";
|
||||
description = "Push notifications";
|
||||
href = "http://${hostName}:${toString cfg.port}";
|
||||
icon = "ntfy.svg";
|
||||
}
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
`hostName` is bound from `config.networking.hostName`, matching the pattern in
|
||||
the home-assistant and paperless modules.
|
||||
|
||||
## Home Assistant wiring
|
||||
|
||||
Applied only when ntfy, the HA integration flag, and the home-assistant profile
|
||||
are all enabled:
|
||||
|
||||
```nix
|
||||
lib.mkIf (cfg.enable && cfg.haIntegration.enable
|
||||
&& config.my.profiles.home-assistant.enable) {
|
||||
services.home-assistant.config.rest_command.ntfy_send = {
|
||||
url = "http://${hostName}:${toString cfg.port}/${cfg.topic}";
|
||||
method = "POST";
|
||||
payload = "{{ message }}";
|
||||
content_type = "text/plain";
|
||||
username = "homeassistant";
|
||||
password = "!secret ntfy_password";
|
||||
headers = {
|
||||
Title = "{{ title | default('Home Assistant') }}";
|
||||
Priority = "{{ priority | default('default') }}";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `services.home-assistant.config` is an attrset that NixOS merges, so adding
|
||||
`rest_command.ntfy_send` from this module composes with the config the
|
||||
home-assistant module already defines.
|
||||
- `password = "!secret ntfy_password"` is a whole-value `!secret` reference. The
|
||||
upstream home-assistant module unquotes such values when rendering the config
|
||||
(the same mechanism the repo already relies on for `!include`), so the secret
|
||||
resolves from `/var/lib/hass/secrets.yaml` at runtime and never enters the
|
||||
Nix store. See `reference_nixos_ha_yaml_includes`.
|
||||
- `rest_command` is chosen over the `notify` REST platform because ntfy's
|
||||
per-topic URL path plus header-based metadata map cleanly onto rest_command,
|
||||
whereas the notify platform's fixed JSON payload fights ntfy's format.
|
||||
|
||||
## Manual provisioning (operator runbook)
|
||||
|
||||
Because credentials are fully manual, after the first `nixos-rebuild switch`
|
||||
run these once on jupiter:
|
||||
|
||||
```bash
|
||||
# Dedicated publisher for Home Assistant, scoped to the ha topic
|
||||
ntfy user add homeassistant # prompts for a password
|
||||
ntfy access homeassistant ha write-only
|
||||
|
||||
# Admin account for the app / web UI
|
||||
ntfy user add --role=admin admin
|
||||
```
|
||||
|
||||
Then add the homeassistant password to Home Assistant's secrets:
|
||||
|
||||
```yaml
|
||||
# /var/lib/hass/secrets.yaml
|
||||
ntfy_password: <the homeassistant user's password>
|
||||
```
|
||||
|
||||
Restart Home Assistant. Automations can then publish with:
|
||||
|
||||
```yaml
|
||||
service: rest_command.ntfy_send
|
||||
data:
|
||||
message: "Garage door left open"
|
||||
title: "Alert"
|
||||
priority: high
|
||||
```
|
||||
|
||||
Subscribers (phone/desktop ntfy app) log in as `admin` (or another user granted
|
||||
read access) to receive messages.
|
||||
|
||||
## Testing / verification
|
||||
|
||||
- Build check: `nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'`
|
||||
must succeed with the module enabled.
|
||||
- `nixfmt-rfc-style` clean on the new file.
|
||||
- Post-deploy manual verification (documented, not automated): create the users
|
||||
above, publish a test message from HA, confirm it reaches a subscribed client.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- No automated user/token seeding (explicitly deferred to manual provisioning).
|
||||
- No sops-nix setup (repo has dangling `config.sops.secrets` references, but
|
||||
wiring up sops is a separate change and not required here).
|
||||
- No reverse-proxy / TLS termination (`behind-proxy` left default; LAN-only via
|
||||
firewall).
|
||||
@@ -1,108 +0,0 @@
|
||||
# Intel Quick Sync hardware transcoding for Jellyfin on jupiter
|
||||
|
||||
## Problem
|
||||
|
||||
Jellyfin streams stutter on jupiter whenever a client needs a transcode
|
||||
(unsupported codec/container, bitrate cap, or a client that can't
|
||||
direct-play). Transcoding currently runs entirely on CPU.
|
||||
|
||||
jupiter's Intel iGPU is already usable at the OS level:
|
||||
|
||||
- `hardware.graphics.enable = true` with `intel-media-driver` (the `iHD`
|
||||
VAAPI driver) is configured in
|
||||
`machines/jupiter/hardware-configuration.nix:20-27`.
|
||||
- The commented-out `i915.force_probe = "9a49"` kernel param there
|
||||
corresponds to a Quick-Sync-capable Intel UHD iGPU, confirming the
|
||||
hardware supports it.
|
||||
|
||||
But `modules/environments/jellyfin/default.nix` never grants the
|
||||
`jellyfin` systemd service access to `/dev/dri`, so Jellyfin has no path
|
||||
to the GPU and silently falls back to software transcoding.
|
||||
|
||||
## Goal
|
||||
|
||||
Give the Jellyfin service access to the iGPU's VAAPI render node, so
|
||||
Quick Sync can be enabled in Jellyfin's own dashboard and transcodes are
|
||||
offloaded from the CPU.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Remote/external access or reverse-proxy tuning.
|
||||
- General CPU/RAM headroom review of jupiter.
|
||||
- A toggle option (`my.profiles.jellyfin.hardwareAcceleration.enable`) —
|
||||
jupiter only has the one iGPU, so this is hardcoded on rather than
|
||||
made configurable.
|
||||
|
||||
## Design
|
||||
|
||||
### NixOS change (declarative)
|
||||
|
||||
In `modules/environments/jellyfin/default.nix`, inside the existing
|
||||
`config = lib.mkIf cfg.enable { ... }` block, grant the systemd service
|
||||
supplementary access to the `video` and `render` groups (the groups that
|
||||
own `/dev/dri/card*` and `/dev/dri/renderD*`):
|
||||
|
||||
```nix
|
||||
systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [
|
||||
"video"
|
||||
"render"
|
||||
];
|
||||
```
|
||||
|
||||
This is additive to the existing `systemd.services.jellyfin.after = [
|
||||
"network-online.target" ];` block already in the file — both apply to
|
||||
the same service.
|
||||
|
||||
Also add `libva-utils` to `environment.systemPackages` (or scoped to
|
||||
this module) so `vainfo` is available on jupiter to verify the driver
|
||||
loads correctly.
|
||||
|
||||
### Manual step (not declarative)
|
||||
|
||||
Jellyfin stores its transcoding/hardware-acceleration choice in its own
|
||||
internal `encoding.xml`, which the NixOS module does not expose as an
|
||||
option. After deploying the Nix change, one-time manual configuration in
|
||||
the Jellyfin dashboard is required:
|
||||
|
||||
1. **Dashboard → Playback**.
|
||||
2. Hardware acceleration: **Intel QuickSync (QSV)**.
|
||||
3. VA-API device: `/dev/dri/renderD128`.
|
||||
4. Enable hardware decoding for the codecs your library actually uses
|
||||
(H264 at minimum; HEVC/VP9 depending on iGPU generation).
|
||||
5. If any HDR content exists in the library, enable tone-mapping — this
|
||||
is one of the more CPU-expensive operations Quick Sync can offload.
|
||||
|
||||
## Verification
|
||||
|
||||
Build-time (from the Mac, no SSH needed):
|
||||
|
||||
```
|
||||
nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
|
||||
--extra-experimental-features 'nix-command flakes'
|
||||
```
|
||||
|
||||
Expect `[ "video" "render" ]`.
|
||||
|
||||
On jupiter after `sudo nixos-rebuild switch --flake '.#jupiter'`:
|
||||
|
||||
```
|
||||
systemctl status jellyfin
|
||||
journalctl -u jellyfin -n 50 --no-pager
|
||||
vainfo
|
||||
```
|
||||
|
||||
`vainfo` should list the `iHD` driver and print supported VAEntrypoints
|
||||
(VLD decode / encode profiles for H264/HEVC).
|
||||
|
||||
Functional check: play a file on a client that forces transcoding (or
|
||||
force it manually via Jellyfin's playback quality setting), then in
|
||||
Jellyfin's dashboard **Activity/Now Playing** panel confirm the
|
||||
transcode reason and check that CPU usage on jupiter (`htop`) stays low
|
||||
during playback rather than pegging a core — Quick Sync offload should
|
||||
show up as low CPU, some GPU (`intel_gpu_top`) activity instead.
|
||||
|
||||
## Open items
|
||||
|
||||
- Exact supported codec list depends on the iGPU generation (device ID
|
||||
`9a49`) — confirm via `vainfo` output once run, and enable only the
|
||||
hardware decode paths it actually reports.
|
||||
Generated
+33
-30
@@ -21,11 +21,11 @@
|
||||
"nixpkgs-lib": "nixpkgs-lib"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1782949081,
|
||||
"narHash": "sha256-vp6Y/Grm98ESt6ceOkWiHWyZRDV3J1RID4w+6NWK9yA=",
|
||||
"lastModified": 1778716662,
|
||||
"narHash": "sha256-m1Yf0wZ8j1OHjTc2UwHwyQRSnNeSgLJOd7q5Y45hzi4=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "17c9d6cdfc60c64f4ee8d306f9bc0b4ccb51481e",
|
||||
"rev": "f7c1a2d347e4c52d5fb8d10cb4d94b5884e546fb",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -42,11 +42,11 @@
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1782949081,
|
||||
"narHash": "sha256-vp6Y/Grm98ESt6ceOkWiHWyZRDV3J1RID4w+6NWK9yA=",
|
||||
"lastModified": 1778716662,
|
||||
"narHash": "sha256-m1Yf0wZ8j1OHjTc2UwHwyQRSnNeSgLJOd7q5Y45hzi4=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "17c9d6cdfc60c64f4ee8d306f9bc0b4ccb51481e",
|
||||
"rev": "f7c1a2d347e4c52d5fb8d10cb4d94b5884e546fb",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -60,17 +60,20 @@
|
||||
"flake-compat": [
|
||||
"nix"
|
||||
],
|
||||
"gitignore": [
|
||||
"nix"
|
||||
],
|
||||
"nixpkgs": [
|
||||
"nix",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1783008725,
|
||||
"narHash": "sha256-jGiy6+sxjNWXSjp25uoJuNfyH9zBK1PEDY0lVoL4ibQ=",
|
||||
"lastModified": 1781733627,
|
||||
"narHash": "sha256-U3yTuGBnmXvXoQI3qkpfEDsn9RovQPAjN7ndRco+3u0=",
|
||||
"owner": "cachix",
|
||||
"repo": "git-hooks.nix",
|
||||
"rev": "bca82caa46d5ec0f5d422c61fb1e30bc51313cbe",
|
||||
"rev": "3bbec39bc90eadfa031e6f3b77272f3f60803e39",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -89,11 +92,11 @@
|
||||
"nixpkgs-regression": "nixpkgs-regression"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1784375420,
|
||||
"narHash": "sha256-dt1zVj4MRpmffhsgQk+3tx1m/pFTXbtVWrn5KZ1y+8Q=",
|
||||
"lastModified": 1782337899,
|
||||
"narHash": "sha256-Imevyelg3r2N5iDonnGdOKGRiB56m3HgVFAljTB3CLU=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nix",
|
||||
"rev": "bebd2f851a304e9fb2e143ce0cbeff577c6a37ac",
|
||||
"rev": "3887a906b178836818a62e8eba666ad652e8a388",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -143,11 +146,11 @@
|
||||
"nixpkgs": "nixpkgs_2"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1784310968,
|
||||
"narHash": "sha256-rkSPTePrKqs4dg+i7ZFCq93+HrClac6oSwXX927SVjA=",
|
||||
"lastModified": 1782379505,
|
||||
"narHash": "sha256-zPvPiU+a7pqtH47xrtZLNRABJKpOjfZQclDbcvNtH+I=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixos-hardware",
|
||||
"rev": "779c32a00155994c86cde8213a8dd4df139d4355",
|
||||
"rev": "603d3afd1b6145bd66e97ae38a34d91c95df70cf",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -158,11 +161,11 @@
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1783148766,
|
||||
"narHash": "sha256-H9+N+GFtsbVC8ZniHliChM7ndizxtqVZs6bnGOLM3WQ=",
|
||||
"rev": "a50de1b7d8a586adc18d2395c19de7d6058e6030",
|
||||
"lastModified": 1780902259,
|
||||
"narHash": "sha256-YMnBf9lk/LYgvqfmSSJuOGigtRs5Lsy26pJHVlR9yMY=",
|
||||
"rev": "bd0ff2d3eac24699c3664d5966b9ef36f388e2ca",
|
||||
"type": "tarball",
|
||||
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.4193.a50de1b7d8a5/nixexprs.tar.xz"
|
||||
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.1550.bd0ff2d3eac2/nixexprs.tar.xz"
|
||||
},
|
||||
"original": {
|
||||
"type": "tarball",
|
||||
@@ -187,11 +190,11 @@
|
||||
},
|
||||
"nixpkgs-lib": {
|
||||
"locked": {
|
||||
"lastModified": 1782614948,
|
||||
"narHash": "sha256-ePjCwr1sNm9NYUqywL7QfK3JnlS015msC+eBu2zKlp8=",
|
||||
"lastModified": 1777168982,
|
||||
"narHash": "sha256-GOkGPcboWE9BmGCRMLX3worL4EMnsnG8MyKmXNeYuhQ=",
|
||||
"owner": "nix-community",
|
||||
"repo": "nixpkgs.lib",
|
||||
"rev": "db3f255737b94216eb71cce308e2912cf6bc2d7c",
|
||||
"rev": "f5901329dade4a6ea039af1433fb087bd9c1fe14",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
@@ -218,11 +221,11 @@
|
||||
},
|
||||
"nixpkgs-unstable": {
|
||||
"locked": {
|
||||
"lastModified": 1784497964,
|
||||
"narHash": "sha256-WhdsTtaih3DgTPP/PX023b36UNQyMzEoi6GkPyGx0y4=",
|
||||
"rev": "241313f4e8e508cb9b13278c2b0fa25b9ca27163",
|
||||
"lastModified": 1782467914,
|
||||
"narHash": "sha256-inDx/w70OSJoJPqtKh0BrzAsbZZhpya7YgS43jHnhwg=",
|
||||
"rev": "e73de5be04e0eff4190a1432b946d469c794e7b4",
|
||||
"type": "tarball",
|
||||
"url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1037713.241313f4e8e5/nixexprs.tar.xz"
|
||||
"url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1022855.e73de5be04e0/nixexprs.tar.xz"
|
||||
},
|
||||
"original": {
|
||||
"id": "nixpkgs",
|
||||
@@ -245,11 +248,11 @@
|
||||
},
|
||||
"nixpkgs_3": {
|
||||
"locked": {
|
||||
"lastModified": 1784432872,
|
||||
"narHash": "sha256-IX7j5TvSD7hYC9NZ8mgmq7pZ97mYyl24Qs4Tz4uyvO4=",
|
||||
"rev": "fd1462031fdee08f65fd0b4c6b64e22239a77870",
|
||||
"lastModified": 1782375420,
|
||||
"narHash": "sha256-f+/IH5ng5P91VHrhcNxqpW2RYDySD68V1fcX00COQy4=",
|
||||
"rev": "4062d36ebeae843c750011eef6b61ec9a9dbc9a9",
|
||||
"type": "tarball",
|
||||
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5591.fd1462031fde/nixexprs.tar.xz"
|
||||
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.3250.4062d36ebeae/nixexprs.tar.xz"
|
||||
},
|
||||
"original": {
|
||||
"id": "nixpkgs",
|
||||
|
||||
@@ -23,6 +23,7 @@ in
|
||||
jellyseerr.enable = true;
|
||||
development.enable = true;
|
||||
home-assistant.enable = true;
|
||||
ntfy.enable = true;
|
||||
|
||||
homepage.enable = true;
|
||||
paperless = {
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
./claude-code
|
||||
./development
|
||||
./home-assistant
|
||||
./ntfy
|
||||
./hyprland
|
||||
./zsh
|
||||
./paperless
|
||||
|
||||
@@ -22,8 +22,6 @@ in
|
||||
openFirewall = true;
|
||||
};
|
||||
|
||||
environment.systemPackages = [ pkgs.libva-utils ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Media";
|
||||
@@ -36,10 +34,6 @@ in
|
||||
|
||||
systemd.services.jellyfin = {
|
||||
after = [ "network-online.target" ];
|
||||
serviceConfig.SupplementaryGroups = [
|
||||
"video"
|
||||
"render"
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# self-hosted push notification server (ntfy)
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
...
|
||||
}:
|
||||
let
|
||||
cfg = config.my.profiles.ntfy;
|
||||
hostName = config.networking.hostName;
|
||||
in
|
||||
{
|
||||
options.my.profiles.ntfy = with lib; {
|
||||
enable = mkEnableOption "ntfy notification server";
|
||||
|
||||
port = mkOption {
|
||||
type = types.port;
|
||||
default = 2586;
|
||||
description = "HTTP port ntfy listens on.";
|
||||
};
|
||||
|
||||
topic = mkOption {
|
||||
type = types.str;
|
||||
default = "ha";
|
||||
description = "Topic Home Assistant publishes notifications to.";
|
||||
};
|
||||
|
||||
haIntegration.enable = mkOption {
|
||||
type = types.bool;
|
||||
default = true;
|
||||
description = "Wire a Home Assistant rest_command that publishes to ntfy.";
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkMerge [
|
||||
(lib.mkIf cfg.enable {
|
||||
services.ntfy-sh = {
|
||||
enable = true;
|
||||
settings = {
|
||||
base-url = "http://${hostName}:${toString cfg.port}";
|
||||
listen-http = ":${toString cfg.port}";
|
||||
auth-file = "/var/lib/ntfy-sh/user.db";
|
||||
auth-default-access = "deny-all";
|
||||
};
|
||||
};
|
||||
|
||||
networking.firewall.allowedTCPPorts = [ cfg.port ];
|
||||
|
||||
my.homepage.services = [
|
||||
{
|
||||
group = "Services";
|
||||
name = "ntfy";
|
||||
description = "Push notifications";
|
||||
href = "http://${hostName}:${toString cfg.port}";
|
||||
icon = "ntfy.svg";
|
||||
}
|
||||
];
|
||||
})
|
||||
|
||||
(lib.mkIf (cfg.enable && cfg.haIntegration.enable && config.my.profiles.home-assistant.enable) {
|
||||
services.home-assistant.config.rest_command.ntfy_send = {
|
||||
url = "http://${hostName}:${toString cfg.port}/${cfg.topic}";
|
||||
method = "POST";
|
||||
payload = "{{ message }}";
|
||||
content_type = "text/plain";
|
||||
username = "homeassistant";
|
||||
password = "!secret ntfy_password";
|
||||
headers = {
|
||||
Title = "{{ title | default('Home Assistant') }}";
|
||||
Priority = "{{ priority | default('default') }}";
|
||||
};
|
||||
};
|
||||
})
|
||||
];
|
||||
}
|
||||
Reference in New Issue
Block a user