nerd-monitor/QUICKSTART.md

Nerd Monitor - Quick Start Guide

Docker Compose (Easiest)

The easiest way to get started is using Docker Compose:

Run Full Stack (Server + Agent)

docker-compose up

Access the dashboard at: http://localhost:8080

Run Server Only

docker-compose up server

Run Agent Only (with external server)

SERVER=your-server:8080 docker-compose up agent

Run Multiple Agents

# Start the server
docker-compose up -d server

# Run agents with custom IDs
docker-compose run --name agent1 -e AGENT_ID=machine1 agent
docker-compose run --name agent2 -e AGENT_ID=machine2 agent

Docker Compose Configuration

Edit docker-compose.yml to customize:

• Server credentials: USERNAME and PASSWORD
• Agent reporting interval: INTERVAL
• Agent custom ID: AGENT_ID

Native Binaries

Building

# Build for current OS
make build

# Build for all platforms (Linux, macOS, Windows)
make build-all

# Clean build artifacts
make clean

Running the Server

# Start server with default credentials (admin/admin)
./bin/nerd-monitor-server

# Start server on custom address/port
./bin/nerd-monitor-server -addr 0.0.0.0 -port 8080 -username myuser -password mypass

# Access the dashboard at: http://localhost:8080

Running Agents

Linux / macOS

# Default: connects to localhost:8080 every 15 seconds
./bin/nerd-monitor-agent

# Custom server
./bin/nerd-monitor-agent --server 10.0.20.80

# Custom server with port
./bin/nerd-monitor-agent --server 10.0.20.80:9090

# Custom reporting interval
./bin/nerd-monitor-agent --server myserver --interval 30s

Windows

On Windows, use the batch wrapper to run the agent in the background (it won't show a terminal window):

# Default: connects to localhost:8080 every 15 seconds
nerd-monitor-agent.bat

# Custom server
nerd-monitor-agent.bat --server 10.0.20.80

# Custom server with port
nerd-monitor-agent.bat --server 10.0.20.80:9090

# Custom interval
nerd-monitor-agent.bat --server myserver --interval 30s

Note: The batch file automatically hides the console window and runs the agent as a background process.

Dashboard Features

Agent Status Indicators

• Green "Online" - Agent reported stats within the last 2 minutes
• Red "Offline" - Agent hasn't reported for more than 2 minutes

Dashboard Overview

• Real-time agent status with online/offline indicators
• CPU usage percentage
• Memory (RAM) usage and total
• Disk usage and total
• Last seen timestamp
• All values are human-readable (B, KB, MB, GB, TB)

Agent Detail Page

Click on any hostname to see detailed stats for that agent:

• CPU usage with progress bar
• Memory usage with progress bar
• Disk usage with progress bar
• Agent ID and detailed information

Stale Agent Management

Agents that haven't reported for 6+ months show a warning. You can:

• See a list of all stale agents
• Bulk select and remove them
• Keep your dashboard clean

Auto-Generation Features

Agent ID

Agent IDs are automatically generated from the machine hostname (e.g., my-laptop or DLO-DEV-001)

Auto-Refresh Dashboard

The dashboard automatically refreshes every 10 seconds to show the latest stats

Connection Recovery

The agent automatically retries connections if the server is unavailable. It will keep attempting to report stats at the configured interval.

Default Credentials

• Username: admin
• Password: admin

Change these when starting the server:

./bin/nerd-monitor-server -username myuser -password mysecurepass

Or with Docker Compose, edit the USERNAME and PASSWORD environment variables in docker-compose.yml.

Architecture

• Server: Web UI, API endpoint for agent stats, in-memory storage
• Agent: Lightweight monitoring agent that reports CPU, RAM, and Disk usage
• No Database: All data stored in server memory (resets on restart)
• Minimal Dependencies: Only Chi (router) and Templ (templating) besides Go stdlib

Troubleshooting

Agent shows "Offline" in dashboard

• Check if the agent process is running
• Verify the server address is correct
• Check network connectivity between agent and server
• Review agent logs for connection errors

Windows agent terminal window appears then closes

• Use the nerd-monitor-agent.bat wrapper instead of the .exe directly
• The batch file handles running the agent in the background

Can't connect to server

• Verify server is running: http://localhost:8080
• Check firewall rules allow the agent port
• Ensure correct server address and port are specified

Docker Compose agents can't reach server

• Verify server is healthy: docker ps (server should show healthy status)
• Check both containers are on the same network: docker network inspect nerd-monitor
• Ensure SERVER environment variable is set to server:8080 (the service name)