Installation

v1.0

Agent Installation Guide

Complete guide to installing the Nodewarden monitoring agent on all supported platforms.

Last updated: December 5, 2024

8 min read

Agent Installation Guide

The Nodewarden agent is a lightweight monitoring client that collects system metrics, discovers services, and forwards data to your Nodewarden dashboard. This guide covers installation on all supported platforms.

Before You Begin

Prerequisites

Nodewarden Account: Sign up for free
System Access: Administrator/root privileges on target systems
Network Access: Outbound HTTPS (port 443) to *.nodewarden.com
Credentials: Your Customer ID and API Key from the dashboard

Getting Your Credentials

Log into your Nodewarden dashboard
Navigate to Settings → API Keys
Copy your Customer ID and API Key
Keep these secure - treat them like passwords

Installation Methods

Quick Install (Recommended)

The fastest way to install on Linux/macOS:

bash
curl -sSL https://get.nodewarden.com | bash -s -- \
  --customer-id YOUR_CUSTOMER_ID \
  --api-key YOUR_API_KEY

What this script does:

Detects your operating system and architecture
Downloads the appropriate package
Installs and configures the agent
Starts the service automatically
Validates the installation

Platform-Specific Instructions

Linux Distributions

Ubuntu/Debian

Using APT Repository (Recommended)

Add the Nodewarden repository:

bash
curl -fsSL https://packages.nodewarden.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/nodewarden-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/nodewarden-keyring.gpg] https://packages.nodewarden.com/deb stable main" | sudo tee /etc/apt/sources.list.d/nodewarden.list

Update package index:

bash
sudo apt update

Install the agent:

bash
sudo apt install nodewarden-agent

Configure the agent:

bash
sudo nodewarden-agent configure \
  --customer-id YOUR_CUSTOMER_ID \
  --api-key YOUR_API_KEY

Start the service:

bash
sudo systemctl enable --now nodewarden-agent

Using DEB Package

Download the package:

bash
wget https://packages.nodewarden.com/nodewarden-agent_latest_amd64.deb

Install the package:

bash
sudo dpkg -i nodewarden-agent_latest_amd64.deb
sudo apt-get install -f  # Fix any dependency issues

Configure and start:

bash
sudo nodewarden-agent configure --customer-id YOUR_CUSTOMER_ID --api-key YOUR_API_KEY
sudo systemctl enable --now nodewarden-agent

CentOS/RHEL/Amazon Linux

Using YUM Repository (Recommended)

Add the Nodewarden repository:

bash
sudo tee /etc/yum.repos.d/nodewarden.repo <<EOF
[nodewarden]
name=Nodewarden Repository
baseurl=https://packages.nodewarden.com/rpm
enabled=1
gpgcheck=1
gpgkey=https://packages.nodewarden.com/gpg
EOF

Install the agent:

bash
sudo yum install nodewarden-agent

Configure the agent:

bash
sudo nodewarden-agent configure \
  --customer-id YOUR_CUSTOMER_ID \
  --api-key YOUR_API_KEY

Start the service:

bash
sudo systemctl enable --now nodewarden-agent

Using RPM Package

Download the package:

bash
wget https://packages.nodewarden.com/nodewarden-agent-latest.x86_64.rpm

Install the package:

bash
sudo rpm -ivh nodewarden-agent-latest.x86_64.rpm

Configure and start:

bash
sudo nodewarden-agent configure --customer-id YOUR_CUSTOMER_ID --api-key YOUR_API_KEY
sudo systemctl enable --now nodewarden-agent

Windows

Using MSI Installer (Recommended)

Download the installer:
- Visit packages.nodewarden.com/windows
- Download nodewarden-agent-latest.msi
Run the installer:
- Right-click the MSI file → "Run as administrator"
- Follow the installation wizard
- Enter your Customer ID and API Key when prompted
Verify installation:

powershell
Get-Service NodewardenAgent

Using PowerShell Script

Open PowerShell as Administrator
Run the installation script:

powershell
Invoke-WebRequest -Uri https://get.nodewarden.com/install.ps1 -OutFile install.ps1
.\install.ps1 -CustomerID "YOUR_CUSTOMER_ID" -ApiKey "YOUR_API_KEY"

Manual Installation

Download the binary:

powershell
Invoke-WebRequest -Uri https://packages.nodewarden.com/nodewarden-agent-windows.zip -OutFile nodewarden-agent.zip

Extract to Program Files:

powershell
Expand-Archive -Path nodewarden-agent.zip -DestinationPath "C:\Program Files\Nodewarden"

Install as service:

powershell
cd "C:\Program Files\Nodewarden"
.\nodewarden-agent.exe install --customer-id YOUR_CUSTOMER_ID --api-key YOUR_API_KEY

Start the service:

powershell
Start-Service NodewardenAgent

macOS

Using Homebrew (Recommended)

Install via Homebrew:

bash
brew tap nodewarden/tap
brew install nodewarden-agent

Configure the agent:

bash
nodewarden-agent configure \
  --customer-id YOUR_CUSTOMER_ID \
  --api-key YOUR_API_KEY

Start the service:

bash
brew services start nodewarden-agent

Manual Installation

Download the binary:

bash
curl -L https://packages.nodewarden.com/nodewarden-agent-darwin.tar.gz | tar xz

Move to Applications:

bash
sudo mv nodewarden-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/nodewarden-agent

Create configuration:

bash
sudo mkdir -p /etc/nodewarden
sudo nodewarden-agent configure --customer-id YOUR_CUSTOMER_ID --api-key YOUR_API_KEY

Install launch daemon:

bash
sudo nodewarden-agent install-service
sudo launchctl load /Library/LaunchDaemons/com.nodewarden.agent.plist

Docker

Using Docker Compose (Recommended)

Create docker-compose.yml:

yaml
version: '3.8'

services:
  nodewarden-agent:
    image: nodewarden/agent:latest
    container_name: nodewarden-agent
    restart: unless-stopped
    environment:
      - NODEWARDEN_CUSTOMER_ID=YOUR_CUSTOMER_ID
      - NODEWARDEN_API_KEY=YOUR_API_KEY
      - NODEWARDEN_HOSTNAME=docker-host
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: host
    privileged: true

Start the container:

bash
docker-compose up -d

Using Docker Run

bash
docker run -d \
  --name nodewarden-agent \
  --restart unless-stopped \
  --network host \
  --privileged \
  -e NODEWARDEN_CUSTOMER_ID=YOUR_CUSTOMER_ID \
  -e NODEWARDEN_API_KEY=YOUR_API_KEY \
  -e NODEWARDEN_HOSTNAME=docker-host \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /:/rootfs:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  nodewarden/agent:latest

Kubernetes

Using Helm Chart (Recommended)

Add the Nodewarden Helm repository:

bash
helm repo add nodewarden https://charts.nodewarden.com
helm repo update

Create values file:

yaml
# values.yaml
config:
  customerID: "YOUR_CUSTOMER_ID"
  apiKey: "YOUR_API_KEY"

daemonset:
  enabled: true
  
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

Install the chart:

bash
helm install nodewarden-agent nodewarden/agent -f values.yaml

Using Kubectl

Create secret for credentials:

bash
kubectl create secret generic nodewarden-credentials \
  --from-literal=customer-id=YOUR_CUSTOMER_ID \
  --from-literal=api-key=YOUR_API_KEY

Apply the DaemonSet:

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nodewarden-agent
spec:
  selector:
    matchLabels:
      app: nodewarden-agent
  template:
    metadata:
      labels:
        app: nodewarden-agent
    spec:
      serviceAccount: nodewarden-agent
      containers:
      - name: agent
        image: nodewarden/agent:latest
        env:
        - name: NODEWARDEN_CUSTOMER_ID
          valueFrom:
            secretKeyRef:
              name: nodewarden-credentials
              key: customer-id
        - name: NODEWARDEN_API_KEY
          valueFrom:
            secretKeyRef:
              name: nodewarden-credentials
              key: api-key
        volumeMounts:
        - name: proc
          mountPath: /host/proc
          readOnly: true
        - name: sys
          mountPath: /host/sys
          readOnly: true
        resources:
          limits:
            cpu: 100m
            memory: 128Mi
          requests:
            cpu: 50m
            memory: 64Mi
      volumes:
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys
      hostNetwork: true
      hostPID: true
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: nodewarden-agent

Configuration

Basic Configuration

The agent configuration file is located at:

Linux: /etc/nodewarden/config.yml
Windows: C:\Program Files\Nodewarden\config.yml
macOS: /etc/nodewarden/config.yml

Example configuration:

yaml
# Nodewarden Agent Configuration
customer_id: "your-customer-id"
api_key: "your-api-key"

# Collection settings
collection:
  interval: 60s
  timeout: 30s
  
# System monitoring
system:
  enabled: true
  collect_processes: true
  collect_network: true
  collect_filesystem: true

# Service discovery
discovery:
  enabled: true
  scan_interval: 300s
  services:
    - mysql
    - postgresql
    - redis
    - nginx
    - apache
    - wordpress

# Logging
logging:
  level: info
  file: /var/log/nodewarden/agent.log
  max_size: 100MB
  max_files: 5

# Network settings
network:
  endpoint: https://api.nodewarden.com
  timeout: 30s
  retry_attempts: 3
  retry_delay: 5s

Environment Variables

The agent supports configuration via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | NODEWARDEN_CUSTOMER_ID | Your customer ID | Required | | NODEWARDEN_API_KEY | Your API key | Required | | NODEWARDEN_HOSTNAME | Custom hostname | System hostname | | NODEWARDEN_ENDPOINT | API endpoint | https://api.nodewarden.com | | NODEWARDEN_LOG_LEVEL | Log level | info | | NODEWARDEN_COLLECTION_INTERVAL | Collection interval | 60s |

Verification

Check Service Status

Linux/macOS:

bash
sudo systemctl status nodewarden-agent

Windows:

powershell
Get-Service NodewardenAgent

View Logs

Linux:

bash
sudo journalctl -u nodewarden-agent -f

macOS:

bash
tail -f /var/log/nodewarden/agent.log

Windows:

powershell
Get-EventLog -LogName Application -Source "Nodewarden Agent" -Newest 10

Test Connectivity

bash
nodewarden-agent test-connection

This command will:

Test network connectivity to Nodewarden servers
Validate your credentials
Send a test metric
Display connection status

Troubleshooting

Common Issues

Permission Denied

Problem: Agent can't read system metrics Solution: Ensure the agent is running with appropriate privileges:

bash
sudo systemctl restart nodewarden-agent

Network Connectivity

Problem: Agent can't connect to Nodewarden servers Solution: Check firewall rules and network connectivity:

bash
curl -v https://api.nodewarden.com/health

High CPU Usage

Problem: Agent consuming too much CPU Solution: Adjust collection interval:

yaml
collection:
  interval: 120s  # Increase from 60s

Memory Issues

Problem: Agent using too much memory Solution: Limit data collection:

yaml
system:
  collect_processes: false  # Disable if not needed
discovery:
  enabled: false  # Disable if not needed

Getting Help

If you encounter issues:

Check the logs first for error messages
Run diagnostics: nodewarden-agent diagnose
Contact support: support@nodewarden.com
Community: Join our Slack

Include this information when requesting help:

Operating system and version
Agent version: nodewarden-agent version
Configuration file (with credentials redacted)
Recent log entries
Error messages

Next Steps

Once your agent is installed and running:

Configure Alerts - Set up notifications for important events
Dashboard Overview - Learn about the web interface
Service Discovery - Understand automatic service detection
Custom Metrics - Add your own monitoring data

Need advanced configuration? See our Advanced Configuration Guide for proxy settings, custom collectors, and enterprise features.

Agent Installation Guide

Before You Begin

Prerequisites

Getting Your Credentials

Installation Methods

Quick Install (Recommended)

Platform-Specific Instructions

Linux Distributions

Ubuntu/Debian

Using APT Repository (Recommended)

Using DEB Package

CentOS/RHEL/Amazon Linux

Using YUM Repository (Recommended)

Using RPM Package

Windows

Using MSI Installer (Recommended)

Using PowerShell Script

Manual Installation

macOS

Using Homebrew (Recommended)

Manual Installation

Docker

Using Docker Compose (Recommended)

Using Docker Run

Kubernetes

Using Helm Chart (Recommended)

Using Kubectl

Configuration

Basic Configuration

Environment Variables

Verification

Check Service Status

View Logs

Test Connectivity

Troubleshooting

Common Issues

Permission Denied

Network Connectivity

High CPU Usage

Memory Issues

Getting Help

Next Steps

On this page

Was this page helpful?