marthsincemelee
270 lines
10 KiB
Markdown
270 lines
10 KiB
Markdown
# 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. ✔
|