Internet Monitor

A Python backend that continuously monitors your home internet connection, runs periodic speed tests, detects outages, and serves a live web dashboard.

What it does

• Speed tests on a configurable schedule (default every 5 minutes) using speedtest-cli — records download, upload, and ping.
• Connectivity probing — every 10 seconds (configurable) lightweight TCP probes hit public DNS resolvers to decide whether you're online. Probes are tried in order and the first success means "online", so a single dead address is harmless; an outage is only declared once at least two addresses fail (failure_threshold). Successful checks are not logged — only failures are.
• Outage detection — when the connection drops it logs the outage (including which hosts were unreachable) and keeps polling every 10 seconds until the connection returns, then records the recovery time and total duration.
• Web dashboard — current status, latest download/upload/ping, an interactive history graph (1h / 6h / 24h / 7d / all), and a table of past outages.
• SQLite storage — all results persist in monitor.db; an outage that was ongoing when the process stopped is recovered on restart.

Setup

python -m venv .venv
source .venv/bin/activate            # fish: source .venv/bin/activate.fish
pip install -r requirements.txt

Run

python -m internet_monitor

Then open the dashboard at http://127.0.0.1:8000.

Options:

python -m internet_monitor --config config.yaml --host 0.0.0.0 --port 8080

Use --host 0.0.0.0 (or set it in config.yaml) to reach the dashboard from other devices on your network.

Docker

docker compose up -d --build

The dashboard is then on http://localhost:8000. The SQLite database persists on the monitor-data volume, so speed-test history and the outage log survive restarts and image updates. See docker-compose.yml and the Dockerfile.

For the full CI/CD path — build in Forgejo Actions, push to the Forgejo container registry, and have Portainer pull the updated image — see DEPLOYMENT.md and .forgejo/workflows/build-deploy.yml.

Configuration

Edit config.yaml:

Key	Default	Meaning
speed_test_interval	300	Seconds between full speed tests
check_interval	10	Seconds between connectivity probes while online
outage_check_interval	10	Seconds between probes while offline
connectivity_timeout	3	Per-probe socket timeout (seconds)
connectivity_hosts	DNS servers	host:port targets, tried in order
failure_threshold	2	How many hosts must fail before declaring an outage
run_speed_test_on_start	true	Run one speed test immediately at launch
database_path	data/monitor.db	SQLite database file
host / port	127.0.0.1:8000	Dashboard bind address

API

Endpoint	Description
GET /api/status	Current online/outage state + latest test
GET /api/history?hours=	Speed-test history (hours=0 for all)
GET /api/outages?limit=	Recorded outages, most recent first

Layout

internet_monitor/
  config.py            # YAML config loader
  database.py          # SQLite persistence
  speedtest_runner.py  # single speed-test execution
  monitor.py           # background engine (scheduling + outage logic)
  app.py               # FastAPI app + JSON API
  __main__.py          # CLI entry point
static/index.html      # dashboard (Chart.js)
config.yaml            # configuration