Metadata-Version: 2.4
Name: ironops
Version: 1.0.0
Summary: DevOps CLI tool for remote server health monitoring over SSH
Author: Aziz Khemiri
License: MIT
Project-URL: Homepage, https://github.com/AzizKhemiri/IronOps
Project-URL: Repository, https://github.com/AzizKhemiri/IronOps
Project-URL: Issues, https://github.com/AzizKhemiri/IronOps/issues
Keywords: devops,ssh,monitoring,cli,server,health
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.4.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# IronOps — DevOps CLI tool for remote server health monitoring
<div align="center">
  <img src="images/IronOps.png" width="700" alt="IronOps Logo">
</div>

### DevOps Project

> A Python-based tool to check the health of multiple remote Linux servers over SSH — automatically collecting CPU, RAM, disk, and service metrics, then generating reports and sending alerts.

---

## Table of Contents
- [What This Project Does](#-what-this-project-does)
- [How It Works (Architecture)](#-how-it-works-architecture)
- [Tools & Technologies](#-tools--technologies)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [Example Output](#-example-output)
- [Scheduling with Cron](#-scheduling-with-cron)
- [Project Structure](#-project-structure)

---

## What This Project Does

This tool connects to a list of remote Linux servers via **SSH**, runs health checks on each one, and:

- Collects: **CPU usage**, **RAM usage**, **disk space**, **uptime**, **running services**
- Generates a **JSON, readable report** for each run
- Sends **email/Slack alerts** when a server exceeds thresholds (e.g., disk > 90%)
- Can run **automatically on a schedule** using cron

---

## How It Works (Architecture) 
<div align="center">
  <img src="images/IronOps-Architecture.png" width="700" alt="Architecture Diagram">
</div>
---

## Tools & Technologies

| Tool | Why we use it | Learn more |
|------|--------------|-----------|
| **Python 3** | Main language | [python.org](https://python.org) |
| **paramiko** | Python SSH library to connect to servers | [paramiko.org](https://paramiko.org) |
| **PyYAML** | Read the servers config file (YAML format) | [pyyaml.org](https://pyyaml.org) |
| **smtplib** | Built-in Python email sender for alerts | Python standard library |
| **cron** | Linux scheduler to run the script automatically | `man cron` |
| **JSON** | Report format | Built-in Python |

### Why SSH?
SSH (Secure Shell) is the industry-standard way to remotely access Linux servers. You connect using:
- **Password** 
- **SSH Key Pair**

Our project supports **both methods**.

---

## Installation

### Step 1 — Install Python 3

```bash
# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip -y

# macOS (using Homebrew)
brew install python3
```

### Step 2 — Clone this project

```bash
git clone https://github.com/yourname/server-health-monitor.git
cd server-health-monitor
```

### Step 3 — Install Python dependencies

```bash
pip3 install -r requirements.txt
```

This installs:
- `paramiko` — SSH connections
- `pyyaml` — reading YAML config files

### Step 4 — Set up your SSH access

**Using SSH keys (recommended for prod):**
```bash
# Generate an SSH key pair (if you don't have one already)
ssh-keygen -t rsa -b 4096 -C "health-monitor"

# Copy your public key to each remote server
ssh-copy-id user@your-server-ip

# Test it works
ssh user@your-server-ip "echo connected successfully"
```

### Step 5 — Configure your servers

Edit `config/servers.yaml` — see the [Configuration](#-configuration) section below.

### Step 6 — Run this commande to track you server

```bash
python3 health_monitor.py
```

---

## Configuration

Edit `config/servers.yaml` to add your servers (e.g):

```yaml
# List of servers to monitor
servers:
  - name: "web-server-01"
    host: "192.168.1.10"
    port: 22
    user: "ubuntu"
    auth: "key"                        # "key" 
    key_path: "~/.ssh/id_rsa"          # path to your private key
```

---

## Usage

### Basic run (check all servers once)
```bash
python3 health_monitor.py
```

### Check a single specific server
```bash
python3 health_monitor.py --server web-server-01
```

### Show verbose output
```bash
python3 health_monitor.py --verbose
```

### Save report to a custom location
```bash
python3 health_monitor.py --output /tmp/my-report.json
```

---

## Example Terminak Output

**python3 health_monitor.py --my-mac**
<div align="center">
  <img src="images/4-mac-demo.png" width="700" alt="Mac demo">
</div>

**python3 health_monitor.py**
<div align="center">
  <img src="images/1-demo.png" width="700" alt="Full health check demo">
</div>

**monitor.log**
<div align="center">
  <img src="images/3-demo.png" width="700" alt="Monitor log output">
</div>

**Demo fake data (test)**
<div align="center">
  <img src="images/2-demo.png" width="700" alt="Demo with fake data">
</div>

**JSON report (reports/health_20241115_143201.json):**
```json
{
  "run_id": 1,
  "timestamp": "2024-11-15T14:32:01Z",
  "summary": {
    "total": 3,
    "healthy": 2,
    "warning": 1,
    "critical": 0,
    "unreachable": 1
  },
  "servers": [
    {
      "name": "web-server-01",
      "host": "192.168.1.10",
      "status": "warning",
      "metrics": {
        "cpu_percent": 23.4,
        "ram_percent": 61.2,
        "disk_percent": 78.5,
        "uptime": "14 days, 3 hours"
      }
    }
  ]
}
```

---

## Scheduling with Cron

To run the health check automatically every 15 minutes:

```bash
# Open the cron editor
crontab -e

# Add this line (e.g: runs every 15 minutes)
*/15 * * * * /usr/bin/python3 /path/to/server-health-monitor/health_monitor.py >> /var/log/health_monitor.log 2>&1
```

Cron schedule format: `minute  hour  day  month  weekday`
```
*/15 * * * *   → every 15 minutes
0 * * * *      → every hour
0 8 * * *      → every day at 8am
0 8 * * 1      → every Monday at 8am
```

---

## Project Structure

```
IronOps/
│
├── health_monitor.py       # Main entry point (run this)
├── requirements.txt        # Python dependencies
├── README.md               # This file
│
├── config/
│   └── servers.yaml        # Your server list + settings
│
├── modules/
│   ├── ssh_client.py       # Handles SSH connections
│   ├── health_check.py     # Runs metric commands on servers to check
│   ├── reporter.py         # Formats and saves reports
│   └── alerter.py          # Sends email/Slack alerts
│
├── reports/                # Auto-generated JSON reports
│   └── health_YYYYMMDD_HHMMSS.json
│
└── logs/                   # Run logs
    └── monitor.log
```

---
