docs: add Netdata module implementation plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 16:11:32 +00:00 · 2026-03-21 16:11:32 +00:00 · bb7f24ac4b
commit bb7f24ac4b
parent d6a4dbeb45
1 changed files with 200 additions and 0 deletions
--- a/docs/superpowers/plans/2026-03-21-netdata-module.md
+++ b/docs/superpowers/plans/2026-03-21-netdata-module.md
@ -0,0 +1,200 @@
+# Netdata 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 Netdata real-time monitoring module, accessible only from Tailscale network.
+
+**Architecture:** Create a NixOS module following existing patterns. Netdata binds to 0.0.0.0 for direct Tailscale access; nginx reverse proxy with `internalOnly` restricts domain access to Tailscale IPs.
+
+**Tech Stack:** NixOS module system, services.netdata, nginx reverse proxy
+
+---
+
+## Task 1: Create Netdata Module
+
+**Files:**
+- Create: `modules/netdata.nix`
+
+- [ ] **Step 1: Create the module file with options**
+
+```nix
+# Netdata Module
+# Provides: Real-time system monitoring dashboard
+#
+# Usage:
+#   myModules.netdata = {
+#     enable = true;
+#     domain = "netdata.example.com";
+#   };
+#
+# Access is restricted to Tailscale network only via nginx internalOnly.
+
+{
+  config,
+  lib,
+  ...
+}:
+
+let
+  cfg = config.myModules.netdata;
+in
+{
+  options.myModules.netdata = {
+    enable = lib.mkEnableOption "Netdata real-time monitoring";
+
+    domain = lib.mkOption {
+      type = lib.types.str;
+      example = "netdata.example.com";
+      description = "Public domain name for Netdata dashboard";
+    };
+
+    port = lib.mkOption {
+      type = lib.types.port;
+      default = 19999;
+      description = "Internal port for Netdata to listen on";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    services.netdata = {
+      enable = true;
+      config = {
+        global = {
+          "bind to" = "0.0.0.0:${toString cfg.port}";
+        };
+      };
+    };
+
+    # Nginx reverse proxy - restricted to Tailscale network
+    myModules.nginx.domains.${cfg.domain} = {
+      port = cfg.port;
+      internalOnly = true;
+      contentSecurityPolicy = null;
+    };
+  };
+}
+```
+
+- [ ] **Step 2: Verify file syntax**
+
+Run: `nix-instantiate --parse modules/netdata.nix`
+Expected: No parse errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add modules/netdata.nix
+git commit -m "feat(modules): add Netdata monitoring module
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Register Module in Default Imports
+
+**Files:**
+- Modify: `modules/default.nix`
+
+- [ ] **Step 1: Add netdata.nix to imports**
+
+Add `./netdata.nix` to the imports list in `modules/default.nix`:
+
+```nix
+# Module exports
+{
+  imports = [
+    ./system.nix
+    ./podman.nix
+    ./nginx.nix
+    ./searxng.nix
+    ./openclaw-podman.nix
+    ./vaultwarden.nix
+    ./crowdsec.nix
+    ./backup.nix
+    ./adguard.nix
+    ./forgejo.nix
+    ./headscale.nix
+    ./open-webui.nix
+    ./netdata.nix
+  ];
+}
+```
+
+- [ ] **Step 2: Verify module is importable**
+
+Run: `nix-instantiate --parse modules/default.nix`
+Expected: No parse errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add modules/default.nix
+git commit -m "feat(modules): register netdata module in default imports
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: Enable Module in configuration.nix
+
+**Files:**
+- Modify: `configuration.nix`
+
+- [ ] **Step 1: Add Netdata configuration block**
+
+Add the following to `configuration.nix` after the Headscale section (around line 221):
+
+```nix
+  # === Netdata (System Monitoring) ===
+  myModules.netdata = {
+    enable = true;
+    domain = "netdata.ashisgreat.xyz";
+  };
+```
+
+- [ ] **Step 2: Verify configuration syntax**
+
+Run: `nix-instantiate --parse configuration.nix`
+Expected: No parse errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add configuration.nix
+git commit -m "feat(config): enable Netdata monitoring
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: Build and Verify
+
+**Files:**
+- None (verification only)
+
+- [ ] **Step 1: Dry-run build to verify configuration**
+
+Run: `nixos-rebuild build --flake .#nixos`
+Expected: Build succeeds without errors
+
+- [ ] **Step 2: Verify Netdata service configuration**
+
+Run: `nix eval .#nixos.config.services.netdata.enable`
+Expected: `true`
+
+- [ ] **Step 3: Verify nginx domain configuration**
+
+Run: `nix eval .#nixos.config.myModules.nginx.domains --json | grep -A5 netdata`
+Expected: Shows netdata.ashisgreat.xyz with internalOnly: true
+
+---
+
+## Deployment Notes
+
+After completing the plan:
+1. Deploy with: `sudo nixos-rebuild switch --flake .#nixos`
+2. Access at: `https://netdata.ashisgreat.xyz` (only from Tailscale-connected devices)
+3. Direct access: `http://<tailscale-ip>:19999`