🖥️ WebStatusPi

Ultra-lightweight web monitoring for Raspberry Pi
Track uptime, response times, and get instant alerts — all from a $35 computer

---

✨ Why WebStatusPi?

Feature	Benefit
🪶 Ultra-lightweight	Runs on Raspberry Pi 1B+ (512MB RAM)
📊 Real-time Dashboard	CRT-style cyberpunk interface
🔌 JSON API	Integrate with anything
💾 Persistent Storage	SQLite keeps your history safe
⚡ Zero Config	Works out of the box

---

🚀 Quick Start

One-Line Install (Recommended)

Run this on your Raspberry Pi:

curl -sSL https://raw.githubusercontent.com/jmlweb/webstatuspi/main/install.sh | bash

The interactive installer will:

• Install dependencies and create a virtual environment
• Guide you through URL configuration
• Optionally set up auto-start on boot

That's it! Open http://<your-pi-ip>:8080 in your browser.

📦 Manual Installation

# Clone and install
git clone https://github.com/jmlweb/webstatuspi.git
cd webstatuspi
python3 -m venv venv
source venv/bin/activate
pip install .

# Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your URLs

# Run
webstatuspi

⚙️ Installer Options

# Interactive installation
./install.sh

# Non-interactive with defaults
./install.sh --non-interactive

# System-wide installation (with systemd service)
sudo ./install.sh --install-dir /opt/webstatuspi

# Update existing installation
./install.sh --update

# Uninstall
./install.sh --uninstall

---

📺 Dashboard

Overview Real-time status cards with latency and 24h uptime metrics.

Detail View Click any card to see full check history with timestamps.

Features:

• 🔄 Auto-refresh every 10 seconds
• 🟢🔴 Color-coded status indicators
• 📈 Response time graphs
• 🕹️ Retro CRT aesthetic with scanlines

---

🔧 API Reference

Endpoints

Method	Endpoint	Description
GET	/	Web dashboard
GET	/status	All URLs status
GET	/status/{name}	Specific URL status
GET	/health	Health check

Example Response

curl http://localhost:8080/status

{
  "urls": [
    {
      "name": "MY_SITE",
      "url": "https://example.com",
      "success_rate": 99.5,
      "last_status": "success",
      "last_status_code": 200
    }
  ],
  "summary": {
    "total_urls": 1,
    "overall_success_rate": 99.5
  }
}

---

🔄 Auto-Start on Boot

Install as a systemd service:

# Preview what will be installed
webstatuspi install-service --dry-run

# Install and start
sudo webstatuspi install-service --enable --start

📋 Service management commands

sudo systemctl status webstatuspi   # Check status
sudo journalctl -u webstatuspi -f   # View live logs
sudo systemctl restart webstatuspi  # Restart
sudo systemctl stop webstatuspi     # Stop

---

⚙️ Configuration

Full Example

monitor:
  interval: 60              # seconds between checks

urls:
  - name: "PROD_API"        # max 10 characters
    url: "https://api.example.com"
    timeout: 10

  - name: "STAGING"
    url: "https://staging.example.com"
    timeout: 5

server:
  port: 8080
  host: 0.0.0.0             # listen on all interfaces

database:
  path: "./data/monitoring.db"
  retention_days: 7         # auto-cleanup old data

Performance Tips

For Raspberry Pi 1B+:

Setting	Recommendation
URLs	5-10 max
Interval	30+ seconds
Timeout	10s or less

---

🛠️ Development

# Setup
python3 -m venv venv
source venv/bin/activate
pip install .[dev]

# Run tests
pytest tests/ -v

Project Structure

webstatuspi/
├── webstatuspi/        # Core package
│   ├── __init__.py     # CLI entry point
│   ├── api.py          # HTTP server
│   ├── database.py     # SQLite operations
│   └── monitor.py      # URL checker
├── tests/              # Test suite
└── docs/               # Documentation

---

🔮 Roadmap

• 0.96" OLED display support
• Physical button navigation
• Buzzer alerts on failures
• Status LEDs (green/red)

---

🐛 Troubleshooting

API not accessible from other devices

1. Check firewall: sudo ufw allow 8080
2. Verify config has host: 0.0.0.0
3. Check Pi IP: ip addr show

High CPU usage

• Increase polling interval to 60+ seconds
• Reduce number of monitored URLs
• Check for slow/timing out URLs

Connection timeouts

• Increase timeout value in config
• Test network: ping google.com
• Test URL manually: curl -I <url>

See Troubleshooting Guide for more.

---

📚 Documentation

Document	Description
Architecture	System design & database schema
Hardware	GPIO pins & OLED setup
Contributing	How to contribute
Development Rules	Code style & conventions

---

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ for Raspberry Pi enthusiasts
Lightweight. Reliable. Open Source.