npm package: @gazzehamine/armada-watch-agent
Description: Monitoring agent for Armada Watch - EC2 instance monitoring with SSL, PM2, Nginx, Systemd, and Security monitoring
Author: Gazzeh Amine
Latest version: 1.5.3

# Armada Watch Agent

Lightweight monitoring agent for EC2 instances. Collects and sends system metrics to your Armada Watch monitoring server.

## Installation

### Via NPM (Recommended)

```bash
npm install -g @gazzehamine/armada-watch-agent
```

### Automated Setup (Easiest)

After installing the agent, run the setup wizard:

```bash
armada-watch-setup
```

This interactive script will:
- ✅ Verify Node.js and PM2 installation
- ✅ Configure the agent (.env file)
- ✅ Start the agent with PM2
- ✅ Optionally configure Nginx monitoring
- ✅ Optionally configure SSL certificate monitoring
- ✅ Optionally configure security monitoring
- ✅ Set up PM2 auto-start on boot

**Note:** For SSL monitoring to work, you need to restart PM2 daemon after setup:
```bash
pm2 kill
cd ~/armada-watch-agent
pm2 start armada-watch-agent --name armada-watch
pm2 save
```

## Manual Setup

If you prefer to configure manually:

## Quick Start

### 1. Set Environment Variables

Create a `.env` file:

```bash
SERVER_URL=http://your-monitoring-server:4000
INSTANCE_NAME=Production Web Server
REGION=us-east-1
COLLECTION_INTERVAL=10
```

Or set them directly:

```bash
export SERVER_URL=http://your-monitoring-server:4000
export INSTANCE_NAME="Production Web Server"
export REGION=us-east-1
export COLLECTION_INTERVAL=10
```

### 2. Run the Agent

```bash
# If installed via npm
armada-watch-agent

# Or with npx
npx @gazzehamine/armada-watch-agent

# If built from source
npm start
```

### 3. Run as a Service (Production)

**Using PM2:**

```bash
npm install -g pm2
pm2 start armada-watch-agent --name armada-watch
pm2 save
pm2 startup
```

**Using systemd:**

```bash
sudo tee /etc/systemd/system/armada-watch.service > /dev/null <<EOF
[Unit]
Description=Armada Watch Monitoring Agent
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME
Environment="SERVER_URL=http://your-server:4000"
Environment="INSTANCE_NAME=My Instance"
Environment="REGION=us-east-1"
ExecStart=$(which armada-watch-agent)
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable armada-watch
sudo systemctl start armada-watch
```

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SERVER_URL` | Yes | - | URL of your monitoring server |
| `INSTANCE_NAME` | No | hostname | Friendly name for this instance |
| `REGION` | No | `unknown` | AWS region (e.g., us-east-1) |
| `INSTANCE_ID` | No | hostname | EC2 instance ID (auto-detected on EC2) |
| `COLLECTION_INTERVAL` | No | `10` | Interval in seconds between metric collections |

## Collected Metrics

The agent collects:

- **CPU Usage** - Overall CPU utilization percentage
- **Memory Usage** - RAM usage percentage and amounts
- **Disk Usage** - Disk space utilization
- **Network Traffic** - Network RX/TX bytes
- **System Info** - Platform, architecture, CPU model
- **Top Processes** - Top 10 processes by CPU/Memory

## Requirements

- Node.js >= 18.0.0
- Network access to monitoring server on port 4000

## Troubleshooting

### Agent can't connect to server

```bash
# Test connectivity
curl http://your-server:4000/health

# Check agent logs (PM2)
pm2 logs armada-watch

# Check agent logs (systemd)
sudo journalctl -u armada-watch -f
```

### Permission errors

The agent needs permission to read system metrics. Run with appropriate user permissions.

## License

MIT