Codakey
Play
← Back to netdata/netdata

How to Deploy & Use netdata/netdata

Netdata Deployment & Usage Guide

1. Prerequisites

System Requirements

  • OS: Linux (kernel 3.10+), macOS 10.12+, FreeBSD 11+, or Windows (via WSL2 or native builds)
  • Architecture: x86_64, ARMv7, ARM64 (AArch64), or 32-bit ARM
  • Resources: Minimum 512MB RAM, 1 CPU core (scales with monitored systems)
  • Network: Outbound HTTPS (443) for Netdata Cloud connectivity; inbound 19999 (optional, for local dashboard)

Build Dependencies (Source Installation)

# Debian/Ubuntu
sudo apt-get install git zlib1g-dev uuid-dev libuv1-dev liblz4-dev libjudy-dev libssl-dev libmnl-dev gcc make cmake

# RHEL/CentOS/Fedora
sudo dnf install git zlib-devel libuuid-devel libuv-devel lz4-devel Judy-devel openssl-devel libmnl-devel gcc make cmake

# macOS
brew install git zlib libuv lz4 judy openssl libmnl cmake

Runtime Dependencies

  • curl or wget (for kickstart script)
  • Docker 20.10+ (for containerized deployment)
  • Systemd (recommended for service management on Linux)

2. Installation

Method A: One-Line Kickstart (Recommended)

# Install and claim to Netdata Cloud immediately
wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --stable-channel --claim-token YOUR_TOKEN --claim-rooms YOUR_ROOM_ID --claim-url https://app.netdata.cloud

# Or install without claiming
wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --stable-channel

Method B: Docker

# Run with default configuration
docker run -d --name=netdata \
  -p 19999:19999 \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --cap-add SYS_PTRACE \
  --security-opt apparmor=unconfined \
  netdata/netdata:latest

# With persistent configuration
docker run -d --name=netdata \
  -p 19999:19999 \
  -v netdataconfig:/etc/netdata \
  -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /etc/passwd:/host/etc/passwd:ro \
  -v /etc/group:/host/etc/group:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  --cap-add SYS_PTRACE \
  --security-opt apparmor=unconfined \
  netdata/netdata:latest

Method C: Package Managers

# Debian/Ubuntu (native packages)
sudo apt-get install netdata

# RHEL/CentOS/Fedora
sudo dnf install netdata

# Arch Linux
sudo pacman -S netdata

# macOS (Homebrew)
brew install netdata

Method D: Build from Source

git clone https://github.com/netdata/netdata.git
cd netdata
git checkout v1.44.0  # Check latest stable tag

# Build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel $(nproc)

# Install (optional)
sudo cmake --install build

3. Configuration

Main Configuration File

Location varies by installation method:

  • Native packages: /etc/netdata/netdata.conf
  • Static builds: /opt/netdata/etc/netdata/netdata.conf
  • Source: /usr/local/etc/netdata/netdata.conf

Generate default configuration:

sudo netdatacli dumpconfig > /etc/netdata/netdata.conf

Key Configuration Sections

Data Retention (netdata.conf):

[db]
    mode = dbengine
    storage tiers = 3
    # Tier 0: per-second data
    dbengine multihost disk space MB = 512
    # Tier 1: per-minute data (hourly)
    dbengine tier 1 multihost disk space MB = 128
    # Tier 2: per-hour data (daily)
    dbengine tier 2 multihost disk space MB = 64

Netdata Cloud Claiming (Environment Variables):

NETDATA_CLAIM_TOKEN=your-claim-token
NETDATA_CLAIM_ROOMS=room-id-1,room-id-2
NETDATA_CLAIM_URL=https://app.netdata.cloud

Health Notifications (/etc/netdata/health_alarm_notify.conf):

# Email
SEND_EMAIL="YES"
EMAIL_TO="admin@example.com"

# Slack
SEND_SLACK="YES"
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
SLACK_CHANNEL="#alerts"

Security Hardening

[web]
    bind to = 127.0.0.1  # Localhost only, use reverse proxy for external access
    ssl key = /etc/netdata/ssl/key.pem
    ssl certificate = /etc/netdata/ssl/cert.pem

4. Build & Run

Development Build (Debug)

cmake -S . -B build-debug -DCMAKE_BUILD_TYPE=Debug -DENABLE_PLUGIN_DEBUG=On
cmake --build build-debug --parallel $(nproc)

# Run without installing
sudo ./build-debug/netdata -D -c ./system/netdata.conf

Production Build (Optimized)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DENABLE_LTO=On \
    -DENABLE_ML=On

cmake --build build --parallel $(nproc)
sudo cmake --install build

# Start service
sudo systemctl enable --now netdata

Verify Installation

# Check if running
curl http://localhost:19999/api/v3/info

# View logs
sudo journalctl -u netdata -f

# CLI status
sudo netdatacli status

5. Deployment

Docker Compose (Single Node)

version: '3'
services:
  netdata:
    image: netdata/netdata:latest
    container_name: netdata
    hostname: "server-name"
    pid: host
    network_mode: host
    restart: unless-stopped
    cap_add:
      - SYS_PTRACE
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    volumes:
      - netdataconfig:/etc/netdata
      - netdatalib:/var/lib/netdata
      - netdatacache:/var/cache/netdata
      - /etc/passwd:/host/etc/passwd:ro
      - /etc/group:/host/etc/group:ro
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - NETDATA_CLAIM_TOKEN=${NETDATA_CLAIM_TOKEN}
      - NETDATA_CLAIM_ROOMS=${NETDATA_CLAIM_ROOMS}
      - NETDATA_CLAIM_URL=https://app.netdata.cloud

volumes:
  netdataconfig:
  netdatalib:
  netdatacache:

Kubernetes (Helm)

# Add repo
helm repo add netdata https://netdata.github.io/helmchart/
helm repo update

# Install parent (centralized) and child (node) agents
helm install netdata netdata/netdata \
  --set parent.claiming.enabled=true \
  --set parent.claiming.token=YOUR_TOKEN \
  --set parent.claiming.rooms=YOUR_ROOM_ID \
  --set child.claiming.enabled=true \
  --set child.claiming.token=YOUR_TOKEN

Systemd Service (Bare Metal)

# /etc/systemd/system/netdata.service
[Unit]
Description=Real time performance monitoring
After=network.target

[Service]
Type=simple
User=netdata
Group=netdata
ExecStart=/usr/sbin/netdata -D
ExecStop=/bin/kill -SIGTERM $MAINPID
TimeoutStopSec=30
Restart=on-failure

[Install]
WantedBy=multi-user.target

Reverse Proxy (Nginx)

server {
    listen 80;
    server_name netdata.example.com;
    
    location / {
        proxy_pass http://127.0.0.1:19999;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

6. Troubleshooting

Installation Issues

"Permission denied" during kickstart

# Run with explicit sudo
sudo sh /tmp/netdata-kickstart.sh --stable-channel

Missing dependencies on build

# Install all build deps automatically (Debian/Ubuntu)
sudo apt-get install -y autoconf automake pkg-config curl cmake

# RHEL/Fedora
sudo dnf install -y autoconf automake pkgconfig curl cmake

Runtime Issues

Dashboard inaccessible (Port 19999)

# Check if listening
sudo ss -tulnp | grep 19999

# Check firewall
sudo ufw allow 19999/tcp  # Ubuntu/Debian
sudo firewall-cmd --add-port=19999/tcp --permanent  # RHEL/CentOS

# Verify config syntax
sudo netdata -t -c /etc/netdata/netdata.conf

High CPU/Memory Usage

# Check DB engine memory
grep "page cache size" /var/log/netdata/error.log

# Reduce retention in netdata.conf
[db]
    dbengine multihost disk space MB = 256  # Reduce from default 512

Cloud Connection Failed

# Test connectivity
curl -I https://app.netdata.cloud

# Reclaim node
sudo netdata-claim.sh -token=TOKEN -rooms=ROOM_ID -url=https://app.netdata.cloud -force

# Check claiming logs
sudo grep claiming /var/log/netdata/error.log

No Data in Charts

# Verify collectors are running
sudo netdatacli debug health

# Check specific plugin
sudo /usr/libexec/netdata/plugins.d/apps.plugin 1 debug

# Reset permissions
sudo chown -R netdata:netdata /var/lib/netdata /var/cache/netdata

Log Locations

  • Error logs: /var/log/netdata/error.log
  • Access logs: /var/log/netdata/access.log
  • Debug logs: /var/log/netdata/debug.log (when enabled)

Common Exit Codes

  • 1: Configuration error
  • 2: Fatal error during startup
  • 3: Cannot create PID file
  • 4: Cannot bind to port (permission denied or already in use)
← Project overviewView alternatives to netdata/netdata →