🚀 NetWatch - Self-Hosted Network Monitor

A beautiful, self-hosted network performance monitoring dashboard with real-time speedtest measurements, bufferbloat detection, internal network (Homenet) testing, and historical trend analysis. Built with Flask and featuring a modern glass-morphism UI.

✨ Features

📊 Internet Performance Monitoring

• Ookla Speedtest Integration - Automatic binary download and execution
• Bufferbloat Testing - iperf3-based latency under load measurements
• 8 Key Metrics - Download, Upload, Ping (Idle), Jitter, Loaded Latency (↓/↑), Download/Upload Latency
• Real-time Updates - Live dashboard with animated metrics and sparklines

🏠 Homenet - Internal Network Monitoring (NEW in v1.3.0)

• Built-in Speedtest Server - Python-based server on port 5201 for LAN testing
• Device Discovery - Automatic scanning of network devices via ARP/ping
• LAN & WiFi Device Tracking - Separate charts and stats by connection type
• Bufferbloat Analysis - Idle Ping vs Loaded Ping vs Gateway Ping chart
• Device Management - Name devices, view history, track performance over time
• Auto-Registration - Devices running tests are automatically added
• Gateway Ping - Monitor latency to your router
• Live Test Progress - Real-time waveform visualization during tests

📈 Data Visualization

• Interactive Charts - Time-series graphs with Chart.js
• Trend Analysis - 24h, 7d, 30d, and custom date ranges
• Global Timeline Slider - Synchronize all charts to specific time windows
• Historical Data Table - Searchable, sortable measurement history

⚙️ Advanced Scheduler Configuration

• 3 Scheduling Modes:
  • Simple - 24/7 monitoring with configurable interval (5-120 min)
  • Weekly - Select active weekdays with time windows
  • Advanced - Per-day custom schedules with multiple time slots
• Multiple Time Slots - Add multiple measurement windows per day (e.g., 4am-10am, then 10pm-midnight)
• Server-Side Storage - Configuration syncs across all devices
• Manual Triggers - On-demand speedtest and bufferbloat tests

💾 Data Management

• SQLite Storage - Lightweight, file-based database
• CSV Export - Filtered and complete dataset exports
• Raw JSON Logging - Complete measurement data preservation
• Delta Tracking - Automatic comparison with previous measurements

🎨 Modern UI

• Glass-morphism Design - Frosted glass effects inspired by shadcn/ui
• Responsive Layout - Mobile-friendly adaptive design
• Dark Theme - Easy on the eyes with gradient backgrounds
• Toast Notifications - Real-time feedback for user actions
• Animated Metrics - Count-up animations and progress bars

📸 Screenshots

Dashboard

Homenet - Internal Network Monitoring

Homenet Features:

• Device Overview (left): Discovered network devices with LAN/WiFi indicators
• Speed Charts (center): Per-device speed history with download/upload trends
• Bufferbloat Analysis (right): Idle Ping vs Loaded Ping vs Gateway Ping comparison

Scheduler Configuration

Scheduling Modes:

• Simple (left): Run measurements 24/7 with a fixed interval
• Weekly (center): Select specific weekdays and time windows
• Advanced (right): Configure multiple time slots per day for granular control

🚀 Quick Start

Supported Architectures

NetWatch automatically detects your system architecture and downloads the appropriate Ookla Speedtest CLI binary. The following architectures are supported:

Linux

• x86_64 (64-bit Intel/AMD) - Desktop and server systems
• i386 (32-bit Intel/AMD) - Legacy 32-bit systems
• aarch64 / arm64 (64-bit ARM) - Raspberry Pi 4/5, modern ARM servers
• armhf (32-bit ARM hard float) - Raspberry Pi 2/3, many ARM SBCs
• armel (32-bit ARM soft float) - Older ARM devices, Raspberry Pi 1

Windows

• x86_64 (64-bit)

macOS

• x86_64 (Intel Macs)
• aarch64 (Apple Silicon M1/M2/M3)

Check your architecture:

python3 -c "import platform; print(f'{platform.system().lower()}_{platform.machine().lower()}')"

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Internet connection (for Ookla binary download)
• Optional: iperf3 (for bufferbloat tests - not required for homenet tests)

Installation

🐧 Linux Installation

Option 1: Quick Setup Script (Recommended)

# Clone the repository
git clone https://github.com/c4g7-dev/netwatch.git
cd netwatch

# Run setup script
bash install-linux.sh

# Activate virtual environment
source .venv/bin/activate

# Start NetWatch
python main.py

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/c4g7-dev/netwatch.git
cd netwatch

# Install Python 3.10+ if not already installed
sudo apt update
sudo apt install python3 python3-venv python3-pip

# If only python3 is installed (no 'python' command), create symlink:
sudo ln -s /usr/bin/python3 /usr/bin/python

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start NetWatch (Ookla CLI downloads automatically on first run)
python main.py

📖 See systemd service example below for running as a background service

🪟 Windows Installation

# Clone the repository
git clone https://github.com/c4g7-dev/netwatch.git
cd netwatch

# Create virtual environment
python -m venv .venv

# Activate virtual environment
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the application
python main.py

🏃 Running NetWatch

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Start the server
python main.py

The dashboard will be available at: http://localhost:8000

systemd Service Example

Create /etc/systemd/system/netwatch.service:

[Unit]
Description=NetWatch - Network Performance Monitor
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/netwatch
Environment="PATH=/path/to/netwatch/.venv/bin"
ExecStart=/path/to/netwatch/.venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Replace YOUR_USERNAME and /path/to/netwatch with your actual values, then:

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable netwatch
sudo systemctl start netwatch

# Check status
systemctl status netwatch

# View logs
journalctl -u netwatch -f

🔒 Linux Firewall Configuration

# UFW (Ubuntu/Debian)
sudo ufw allow 8000/tcp

# firewalld (CentOS/RHEL/Fedora)
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
sudo iptables-save

📁 Project Structure

netwatch/
├── app/
│   ├── db/                    # Database models and session management
│   ├── measurements/          # Speedtest and bufferbloat runners
│   ├── web/                   # Flask application and routes
│   │   ├── static/
│   │   │   ├── css/          # Glass-morphism styles
│   │   │   └── js/           # Dashboard logic and charts
│   │   └── templates/        # HTML templates
│   ├── config.py             # Configuration loader
│   └── scheduler.py          # Automated measurement scheduling
├── bin/                      # Downloaded binaries (speedtest, iperf3)
├── data/                     # SQLite database and CSV exports
├── logs/                     # Application logs
├── config.yaml              # User configuration
├── installer.py             # Automated setup script
├── updater.py               # Binary update utility
├── main.py                  # Application entry point
└── requirements.txt         # Python dependencies

⚙️ Configuration

Edit config.yaml to customize NetWatch:

# Server Configuration
web:
  host: "0.0.0.0"
  port: 8000

# Measurement Settings
ookla:
  auto_download: true

bufferbloat:
  iperf_server: iperf3.example.net
  iperf_port: 5201

# Logging
logging:
  level: "INFO"

Note: Scheduling is now configured through the dashboard UI. Click the ⚙️ button next to the scheduler status to configure measurement intervals and time windows.

🔧 Advanced Usage

Alternative: Cron Jobs

Note: The built-in scheduler (configured via dashboard) is recommended. However, if you need cron:

# Edit crontab
crontab -e

# Run NetWatch server on boot
@reboot cd /path/to/netwatch && /path/to/netwatch/.venv/bin/python main.py >> /path/to/netwatch/logs/app.log 2>&1 &

Important: systemd (see above) is strongly recommended for production use - provides automatic restarts, better logging, and easier management.

Manual Test Triggers

Via Dashboard:

• Click "Speedtest" button for immediate speed measurement
• Click "Bufferbloat" button for latency-under-load test

Via API:

# Trigger speedtest
curl -X POST http://localhost:8000/api/manual/speedtest

# Trigger bufferbloat test
curl -X POST http://localhost:8000/api/manual/bufferbloat

Data Export

Via Dashboard:

• Click "Export CSV" to download filtered data based on current time range

Via API:

# Export all data
curl "http://localhost:8000/api/export/csv?scope=complete" -o measurements.csv

# Export filtered data
curl "http://localhost:8000/api/export/csv?start=2025-12-01T00:00:00Z&end=2025-12-02T23:59:59Z" -o measurements.csv

API Endpoints

Internet Monitoring

Endpoint	Method	Description
/	GET	Dashboard UI
/api/status	GET	System status and configuration
/api/summary/latest	GET	Latest measurement with delta
/api/measurements	GET	Historical measurements (supports filtering)
/api/export/csv	GET	Export measurements as CSV
/api/manual/speedtest	POST	Trigger manual speedtest
/api/manual/bufferbloat	POST	Trigger manual bufferbloat test
/api/scheduler/config	GET	Get current scheduler configuration
/api/scheduler/config	POST	Save scheduler configuration

Homenet (Internal Network)

Endpoint	Method	Description
/api/internal/summary	GET	Internal network stats summary
/api/internal/measurements	GET	Internal measurement history
/api/internal/devices	GET	List discovered devices
/api/internal/devices/scan	POST	Trigger device discovery scan
/api/internal/devices/<id>	GET	Get device details with history
/api/internal/devices/<id>	PUT	Update device (name, etc.)
/api/internal/speedtest/stream	GET	SSE stream for live speedtest
/api/internal/server/status	GET	Internal speedtest server status
/api/internal/server/start	POST	Start internal speedtest server
/api/internal/server/stop	POST	Stop internal speedtest server
/api/internal/export/csv	GET	Export internal measurements as CSV

🔄 Updating

If running as systemd service:

cd /path/to/netwatch
sudo systemctl stop netwatch
git pull origin master
source .venv/bin/activate
pip install -r requirements.txt --upgrade
sudo systemctl start netwatch

If running manually:

cd netwatch
git pull origin master
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt --upgrade
# Restart: python main.py

Update Ookla Binary

python updater.py --component speedtest

🗑️ Uninstallation

If running as systemd service:

# Stop and disable service
sudo systemctl stop netwatch
sudo systemctl disable netwatch

# Remove service file
sudo rm /etc/systemd/system/netwatch.service
sudo systemctl daemon-reload

# Remove application directory
rm -rf /path/to/netwatch

Windows / Manual Installation:

Simply delete the NetWatch directory after stopping any running processes.

🛠️ Troubleshooting

Speedtest Fails with "error code none" or Architecture Issues

This typically means your system architecture is not detected or configured properly.

1. Check your architecture:

uname -m
python3 -c "import platform; print(platform.machine())"

2. Verify configuration: Check that config.yaml has a download URL for your platform:

# Your platform key should be one of: linux_x86_64, linux_i386, linux_aarch64, linux_armhf, linux_armel
python3 -c "from app.config import load_config; c = load_config('config.yaml'); print(c.ookla_platform_key)"

3. Manual installation option: If auto-download fails, install the Ookla binary manually:

# Download the appropriate binary from https://www.speedtest.net/apps/cli
# Example for ARM 32-bit hard float (Raspberry Pi 2/3):
wget https://install.speedtest.net/app/cli/ookla-speedtest-1.2.0-linux-armhf.tgz
tar -xzf ookla-speedtest-1.2.0-linux-armhf.tgz
mv speedtest bin/
chmod +x bin/speedtest

# Optionally disable auto_download in config.yaml:
# ookla:
#   auto_download: false

4. Architecture-specific notes:

• Raspberry Pi 1, Zero, Zero W (armv6): Use armel architecture

  • Detected as: linux_armel

• Raspberry Pi 2, 3, 3B+ (armv7): Use armhf architecture

  • Detected as: linux_armhf (hard float)

• Raspberry Pi 4, 5 (64-bit): Can use either aarch64 (64-bit OS) or armhf (32-bit OS)

  • 64-bit OS: linux_aarch64
  • 32-bit OS: linux_armhf

5. Fallback option: NetWatch automatically falls back to speedtest-cli Python package if Ookla binary fails:

pip install speedtest-cli

iperf3 Not Found

If iperf3 is not available on your system:

# Ubuntu/Debian
sudo apt install iperf3

# CentOS/RHEL/Fedora
sudo dnf install iperf3
  
# Arch Linux
sudo pacman -S iperf3
  
# Windows
# Download from https://iperf.fr/iperf-download.php
# Place iperf3.exe in bin/ folder
  
# macOS
brew install iperf3

Database Locked Errors

• Issue: SQLite database locked
• Solution: Ensure only one instance of NetWatch is running

Port Already in Use

• Issue: Port 8000 is occupied
• Solution: Change port in config.yaml or stop conflicting service

  # Linux - Find process using port 8000
  sudo lsof -i :8000
  sudo netstat -tulpn | grep :8000
  
  # Windows
  netstat -ano | findstr :8000

Permission Denied (Linux)

• Issue: Cannot access files or bind to port
• Solution:

  # Check file ownership
  sudo chown -R netwatch:netwatch /opt/netwatch
  
  # If binding to port < 1024, use setcap
  sudo setcap 'cap_net_bind_service=+ep' /opt/netwatch/.venv/bin/python3

Service Won't Start (Linux)

• Issue: systemd service fails to start
• Solution:

  # Check service status
  systemctl status netwatch
  
  # View detailed logs
  journalctl -u netwatch -n 100 --no-pager
  
  # Test manual start
  sudo -u netwatch /opt/netwatch/.venv/bin/python /opt/netwatch/main.py

  macOS

  brew install iperf3

Database Locked Errors

• Issue: SQLite database locked
• Solution: Ensure only one instance of NetWatch is running

Port Already in Use

• Issue: Port 8000 is occupied
• Solution: Change port in config.yaml or stop conflicting service

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Ookla Speedtest CLI - Network performance testing
• Flask - Web framework
• Chart.js - Data visualization
• shadcn/ui - UI design inspiration

📊 Roadmap

• Internal network (Homenet) monitoring
• Docker support with docker-compose
• Prometheus metrics export
• Grafana dashboard templates
• Multi-server monitoring
• Email/webhook alerts for degraded performance
• Mobile app (React Native)
• Historical data comparison (month-over-month)
• ISP outage detection and logging
• Bandwidth quota tracking

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for network monitoring enthusiasts

⭐ Star this repository if you find it useful!