# 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.

![Go](https://img.shields.io/badge/Go-1.23-blue?logo=go)
![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)
- 📈 **Real-time Monitoring** - Track CPU, RAM, and Disk usage with 15-second refresh 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 auto-refresh
- 🚀 **Minimal Dependencies** - Only Chi router and Templ templating engine (plus Go stdlib)
- ⚙️ **Auto-Generation** - Agent IDs automatically generated from hostname
- 💾 **In-Memory Storage** - Fast, zero-database setup (perfect for small to medium deployments)

## 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`

### 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 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

### Agent Detail Page

Click any agent hostname to see detailed statistics:

- Large CPU usage display with progress bar
- Memory and disk breakdowns
- Agent ID and detailed metadata
- Last exact timestamp
- Delete button for removing the agent

### 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)
- **API Endpoints**:
  - `POST /api/report` - Agent stats reporting
  - `GET /api/agents` - List all agents
  - `GET /api/agents/{id}` - Get specific agent stats

### 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
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Auto-Refresh**: Dashboard refreshes every 5 seconds
- **Color-coded Status**: Visual indicators for system health

## Project Structure

```
nerd-monitor/
├── cmd/
│   ├── agent/
│   │   └── main.go           # Agent executable
│   └── server/
│       └── main.go           # Server executable
├── internal/
│   ├── api/
│   │   └── api.go            # API handlers
│   ├── auth/
│   │   ├── middleware.go     # Auth middleware
│   │   └── errors.go         # Error definitions
│   ├── stats/
│   │   └── stats.go          # System stats collection
│   ├── store/
│   │   └── store.go          # In-memory agent storage
│   └── ui/
│       └── handlers.go       # Dashboard handlers
├── views/
│   ├── layout.templ          # Base layout template
│   ├── dashboard.templ       # Dashboard page
│   ├── agent_detail.templ    # Agent detail page
│   ├── login.templ           # Login page
│   ├── components.templ      # Reusable components
│   └── generate.go           # Templ code generation
├── 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)
- **Dashboard Refresh**: 5 seconds (configurable)
- **Agent Reporting**: 15 seconds (configurable)

## 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

### 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

## 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

### 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

### 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

### 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
```

### Running Tests

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

### Code Formatting

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

## Contributing

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

## Future Enhancements

- [ ] Database persistence (SQLite/PostgreSQL)
- [ ] Alerting system (email/Slack notifications)
- [ ] Historical data / graphing
- [ ] Agent grouping and tagging
- [ ] Custom metric collection
- [ ] TLS/HTTPS support
- [ ] Multi-tenancy
- [ ] API documentation (Swagger)

## 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**