nixos-vps/docs/superpowers/specs/2026-03-21-netdata-design.md

Netdata Module Design

Date: 2026-03-21 Status: Draft

Overview

Add Netdata real-time monitoring to the NixOS VPS, accessible only from the Headscale/Tailscale network.

Requirements

• Netdata monitoring service running on the VPS
• Accessible via nginx reverse proxy with automatic HTTPS
• Restricted to Tailscale network only (100.64.0.0/10) and localhost
• Direct access on Tailscale IP (port 19999) also available

Implementation

Module: modules/netdata.nix

Create a new module following the existing pattern.

Header comment block:

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

Options:

• enable - Enable Netdata monitoring
• domain - Domain for nginx reverse proxy (e.g., netdata.ashisgreat.xyz)
• port - Internal port (default: 19999), description: "Internal port for Netdata to listen on"

Configuration:

• Enable services.netdata with default settings
• Bind Netdata to 0.0.0.0 to allow direct Tailscale access (not just localhost)
• Register domain with myModules.nginx.domains using internalOnly = true
• Set contentSecurityPolicy = null - Netdata dashboard has its own CSP requirements
• No firewall changes needed (nginx handles external access, direct Tailscale access works via mesh network)

Usage in configuration.nix

myModules.netdata = {
  enable = true;
  domain = "netdata.ashisgreat.xyz";
};

Access Control

• Via domain: Only accessible from IPs in 100.64.0.0/10 (Tailscale) or 127.0.0.0/8 (localhost)
• Direct Tailscale: http://<tailscale-ip>:19999 (Tailscale mesh handles access control)

Backup Decision

Netdata metrics data is not backed up. Rationale:

• Metrics are ephemeral and regeneratable
• Historical data is downsampled over time (not critical)
• /var/lib/netdata excluded from backup paths

Secrets

No SOPS secrets required. Netdata operates without authentication at the service level - access control is enforced via nginx/Tailscale network restrictions.

Files Changed

File	Action
modules/netdata.nix	Create
modules/default.nix	Add import
configuration.nix	Enable module

Security

• No public internet access - blocked at nginx level
• No authentication required at Netdata level (network-level access control)
• Automatic HTTPS via Let's Encrypt