nixos-vps/docs/superpowers/plans/2026-03-21-netdata-module.md

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

# 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

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:

# 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

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

  # === 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

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