Files

T

marthsincemelee 8c49a0a326 docs(ntfy): add implementation plan

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-05 12:30:04 +02:00

10 KiB

Raw Blame History

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:

# 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):

    ./home-assistant
    ./ntfy

Step 3: Enable the profile on jupiter

In machines/jupiter/environments.nix, inside the my.profiles = { ... } block, add:

    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

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:

  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

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:

Deploy: sudo nixos-rebuild switch --flake '.#jupiter'

Create ntfy users:

ntfy user add homeassistant            # set a password
ntfy access homeassistant ha write-only
ntfy user add --role=admin admin

Add the publisher password to Home Assistant secrets:

# /var/lib/hass/secrets.yaml
ntfy_password: <the homeassistant user's password>

Restart Home Assistant, then test from an automation / Developer Tools:

service: rest_command.ntfy_send
data:
  message: "ntfy test"
  title: "Home Assistant"
  priority: high

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

10 KiB Raw Blame History Unescape Escape