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)
```bash
docker-compose up
```

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

### Run Server Only
```bash
docker-compose up server
```

### Run Agent Only (with external server)
```bash
SERVER=your-server:8080 docker-compose up agent
```

### Run Multiple Agents
```bash
# 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

```bash
# Build for current OS
make build

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

# Clean build artifacts
make clean
```

## Running the Server

```bash
# 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
```bash
# 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):

```batch
# 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:
```bash
./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)