# Nerd Monitor 📊

A lightweight, cross-platform system monitoring solution written in Go. Monitor CPU, memory, and disk usage across multiple machines with a beautiful web dashboard featuring instant real-time updates powered by Server-Sent Events and HTMX.

![Go](https://img.shields.io/badge/Go-1.23-blue?logo=go)
![Real-time](https://img.shields.io/badge/real--time-SSE%20%2B%20HTMX-orange?logo=lightning)
![License](https://img.shields.io/badge/license-MIT-green)
![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-important)

## Features

- 🖥️ **Multi-platform Support** - Deploy agents on Linux, macOS, and Windows (AMD64 & ARM64)
- ⚡ **Instant Real-time Updates** - Stats update immediately when agents report, not on fixed intervals
- 🟢 **Live Status Indicators** - See which machines are online/offline at a glance
- 🔒 **Secure Authentication** - Session-based admin authentication for the dashboard
- 🧹 **Stale Agent Management** - Automatically detect and remove agents inactive for 6+ months
- 📱 **Responsive Dashboard** - Beautiful, modern UI with seamless HTMX-powered updates
- 🚀 **Minimal Dependencies** - Only Chi router, Templ templating, and HTMX (plus Go stdlib)
- ⚙️ **Auto-Generation** - Agent IDs automatically generated from hostname
- 💾 **In-Memory Storage** - Fast, zero-database setup (perfect for small to medium deployments)
- 📡 **Server-Sent Events** - Real-time push notifications from server to web clients
- 📝 **Structured Logging** - Comprehensive slog-based logging throughout the application

## Quick Start

### Prerequisites

- Go 1.23+ (for building)
- Port 8080 available (configurable)

### Building

```bash
# Build for current OS
make build

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

# Clean build artifacts
make clean
```

Binaries are created in the `bin/` directory.

### Running the Server

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

# Custom configuration
./bin/nerd-monitor-server \
  -addr 0.0.0.0 \
  -port 8080 \
  -username admin \
  -password securepassword
```

Then access the dashboard at `http://localhost:8080`. The interface provides real-time updates - stats refresh instantly when agents report new data!

### Running Agents

#### Linux / macOS

```bash
# Connect to local server with default port
./bin/nerd-monitor-agent --server 10.0.20.80

# With custom port
./bin/nerd-monitor-agent --server 10.0.20.80:9090

# With custom reporting interval (default: 15s)
./bin/nerd-monitor-agent --server myserver:8080 --interval 30s
```

#### Windows

Use the batch wrapper to run agents as a background process (no visible terminal):

```batch
REM Run in background with custom server
nerd-monitor-agent.bat --server 10.0.20.80

REM With custom port
nerd-monitor-agent.bat --server 10.0.20.80:9090 --interval 30s
```

## Dashboard

### Overview Page

Shows all connected agents with instant real-time metrics:

- **Status Badge** - Green (Online) or Red (Offline)
  - Online: Last report within 15 seconds
  - Offline: No report for 15+ seconds
- **CPU Usage** - Percentage (0-100%)
- **Memory Usage** - Used / Total with visual progress bar
- **Disk Usage** - Used / Total with visual progress bar
- **Last Seen** - Human-readable timestamp
- **Live Updates** - Stats refresh immediately when agents report new data

### Agent Detail Page

Click any agent hostname to see detailed statistics with live updates:

- Large CPU usage display with progress bar (updates in real-time)
- Memory and disk breakdowns
- Agent ID and detailed metadata
- Last exact timestamp
- Delete button for removing the agent
- **Instant Updates** - CPU stats refresh immediately when agent reports

### Stale Agent Management

Agents inactive for 6+ months:
- Display warning banner on dashboard
- Show list of stale agents
- Bulk select and remove functionality
- Keep dashboard clean and organized

## Architecture

### Server (`cmd/server/`)

- **HTTP Router**: Chi v5 for efficient routing
- **Authentication**: Session-based auth with 24-hour expiry
- **Storage**: In-memory concurrent-safe store (sync.RWMutex)
- **Real-time Broadcasting**: Server-Sent Events (SSE) for instant UI updates
- **Structured Logging**: slog-based logging with debug/info levels
- **API Endpoints**:
  - `POST /api/report` - Agent stats reporting (triggers real-time broadcasts)
  - `GET /api/agents` - List all agents
  - `GET /api/agents/{id}` - Get specific agent stats
  - `GET /api/dashboard/table` - HTML fragment for HTMX dashboard updates
  - `GET /api/agents/{id}/stats` - HTML fragment for HTMX agent detail updates
  - `GET /api/events` - Server-Sent Events for real-time notifications

### Agent (`cmd/agent/`)

- **Stats Collection**: Uses gopsutil for cross-platform stats
- **Auto-ID Generation**: Hostname-based ID generation
- **Reporting**: Configurable interval (default 15 seconds)
- **Resilience**: Automatic retry on connection failure
- **Graceful Shutdown**: Handles SIGTERM and SIGINT

### Views (`views/`)

- **Templ Templates**: Type-safe HTML templating
- **HTMX Integration**: Smooth, instant updates without page refreshes
- **Server-Sent Events**: Real-time push notifications from server
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Color-coded Status**: Visual indicators for system health

## Project Structure

```
nerd-monitor/
├── cmd/
│   ├── agent/
│   │   └── main.go           # Agent executable with slog logging
│   └── server/
│       └── main.go           # Server executable with slog logging
├── internal/
│   ├── api/
│   │   └── api.go            # API handlers + real-time broadcaster
│   ├── auth/
│   │   ├── middleware.go     # Auth middleware with detailed logging
│   │   └── errors.go         # Error definitions
│   ├── stats/
│   │   └── stats.go          # System stats collection
│   ├── store/
│   │   └── store.go          # In-memory agent storage with logging
│   └── ui/
│       └── handlers.go       # Dashboard handlers + HTMX endpoints
├── views/
│   ├── layout.templ          # Base layout with HTMX + SSE
│   ├── dashboard.templ       # Dashboard with real-time updates
│   ├── agent_detail.templ    # Agent detail with live stats
│   ├── login.templ           # Login page
│   ├── components.templ      # Reusable components
│   └── *_templ.go            # Generated Templ code
├── Makefile                  # Build system
├── go.mod / go.sum           # Go dependencies
├── AGENTS.md                 # Agent guidelines
├── QUICKSTART.md             # Quick start guide
└── README.md                 # This file
```

## Code Style Guidelines

Following the guidelines in `AGENTS.md`:

- **Imports**: Standard library → third-party → internal (alphabetical)
- **Formatting**: gofmt standards
- **Naming**: CamelCase for exports, lowercase for unexported
- **Error Handling**: Explicit checks, contextual wrapping
- **Concurrency**: sync.RWMutex for shared state, always defer releases
- **HTTP**: Chi router with proper status codes and Content-Type headers

## Configuration

### Server Flags

```bash
./bin/nerd-monitor-server [OPTIONS]

Options:
  -addr string
      Server address (default "localhost")
  -port string
      Server port (default "8080")
  -username string
      Admin username (default "admin")
  -password string
      Admin password (default "admin")
```

### Agent Flags

```bash
./bin/nerd-monitor-agent [OPTIONS]

Options:
  -server string
      Server URL (required)
  -interval duration
      Reporting interval (default 15s)
  -id string
      Agent ID (auto-generated from hostname if empty)
```

## Default Credentials

- **Username**: `admin`
- **Password**: `admin`

⚠️ **Security**: Change these credentials in production!

## Performance

- **Agent Memory**: ~8-10 MB (depending on platform)
- **Server Memory**: Scales with connected agents (~1 MB per 1000 agents)
- **Network**: Minimal bandwidth (~1 KB per report + SSE connections)
- **Real-time Updates**: Instant UI updates when agents report stats
- **Agent Reporting**: 15 seconds (configurable)
- **SSE Connections**: Lightweight persistent connections for real-time notifications

## Building for Specific Platforms

```bash
# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o bin/nerd-monitor-agent-linux-amd64 ./cmd/agent

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/nerd-monitor-agent-darwin-arm64 ./cmd/agent

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o bin/nerd-monitor-agent-windows-amd64.exe ./cmd/agent
```

Or use the Makefile:

```bash
make build-all
```

## Dependencies

### Production

- `github.com/go-chi/chi/v5` - HTTP router
- `github.com/a-h/templ` - HTML templating
- `github.com/shirou/gopsutil/v3` - System statistics
- **HTMX** (CDN) - Frontend interactivity and real-time updates
- **Server-Sent Events** (Go stdlib) - Real-time push notifications

### Go Standard Library

- `encoding/json` - JSON marshaling
- `net/http` - HTTP server and client
- `sync` - Concurrent access (RWMutex)
- `time` - Timestamps and durations
- `os` - Hostname, signals, I/O
- `crypto/rand` - Token generation
- `log/slog` - Structured logging throughout application

## Troubleshooting

### Agent not appearing in dashboard

1. Verify server is running: `http://localhost:8080`
2. Check agent logs for connection errors
3. Ensure correct server address and port
4. Check firewall rules allow outbound connections
5. Check server logs for SSE broadcasting activity

### Stats not updating in real-time

1. Verify browser supports Server-Sent Events (SSE)
2. Check browser developer tools for JavaScript errors
3. Ensure `/api/events` endpoint is accessible (requires authentication)
4. Check server logs for SSE connection/disconnection messages
5. Verify HTMX library loaded correctly

### Agent shows "Offline" immediately

1. Check network connectivity between agent and server
2. Verify server address is reachable: `ping 10.0.20.80`
3. Check if server is listening on the correct port
4. Review server logs for errors
5. Note: Agents are marked offline if no report received in 15 seconds

### Can't login to dashboard

1. Verify you're using correct credentials
2. Try the default: `admin` / `admin`
3. If changed, restart server with original credentials to reconfigure
4. Check browser cookies are enabled
5. Clear browser cache if SSE connections seem stuck

### Windows agent window appears then closes

1. Use `nerd-monitor-agent.bat` instead of `.exe` directly
2. The batch wrapper handles background execution
3. Check task manager to verify agent process is running

## Development

### Regenerating Templates

When modifying `.templ` files:

```bash
make templ
# or
go run github.com/a-h/templ/cmd/templ@latest generate
```

### Viewing Logs

The application uses structured logging with `slog`. Set log level with:

```bash
# Debug logging (shows all activity)
export GOLOGLEVEL=debug

# Info logging (default, shows important events)
export GOLOGLEVEL=info
```

### Running Tests

```bash
go test ./...
```

### Code Formatting

```bash
gofmt -w ./cmd ./internal ./views
```

### Testing Real-time Features

To test SSE and HTMX functionality:

```bash
# Start server
./bin/nerd-monitor-server

# In another terminal, send test stats
curl -X POST "http://localhost:8080/api/report?id=test-agent" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "test", "cpuUsage": 25.5, "ramUsage": 1000000, "ramTotal": 8000000, "diskUsage": 50000000, "diskTotal": 100000000}'
```

## Contributing

Contributions are welcome! Please follow the code style guidelines in `AGENTS.md`.

## Recent Updates

- ✅ **Real-time Updates**: Instant UI updates via Server-Sent Events and HTMX
- ✅ **Structured Logging**: Comprehensive slog-based logging throughout
- ✅ **Enhanced Monitoring**: Better debugging and operational visibility

## Future Enhancements

- [ ] Database persistence (SQLite/PostgreSQL)
- [ ] Alerting system (email/Slack notifications)
- [ ] Historical data / graphing with time-series storage
- [ ] Agent grouping and tagging
- [ ] Custom metric collection
- [ ] TLS/HTTPS support
- [ ] Multi-tenancy
- [ ] API documentation (Swagger/OpenAPI)
- [ ] Webhook integrations
- [ ] Mobile app companion

## License

MIT License - See LICENSE file for details

## Support

- Check `QUICKSTART.md` for common setup issues
- Review `AGENTS.md` for development guidelines
- Open an issue for bugs or feature requests

---

**Made with ❤️ for system administrators and DevOps teams**