NetProbe
Docker app from bmartino1's Repository
NetProbe 2.1 - Internet Quality Monitoring Dashboard Monitor network connectivity, packet loss, latency, jitter, DNS response times, connection quality, and bandwidth.
Requirements
Persist /config. On a first install, open the HTTPS WebUI to create an administrator account and complete monitoring setup. A self-signed TLS certificate is generated by default.
The official Ookla CLI is NOT bundled. Users must review and acknowledge Ookla's terms and install it separately through administrator Settings. Selecting the Ookla backend alone does not install the executable.
PostgreSQL is optional and requires an independently deployed, reachable server. Database selection and credentials can be saved under Settings; switching does not migrate existing SQLite history.
Overview
NetProbe 2.1 - Internet Quality Monitoring Dashboard
Monitor network connectivity, packet loss, latency, jitter, DNS response times, connection quality, and bandwidth.
- HTTPS dashboard with administrator and guest read-only access.
- First-run administrator creation and monitoring wizard.
- Scheduled Ping, DNS, and Speedtest tests, historical graphs, and manual diagnostics.
- SQLite by default; optional external PostgreSQL through Settings.
- Saved WebUI settings take precedence over initial Docker environment seeds.
Data, administrator credentials, certificates, and SQLite history persist at /config.
Official Ookla CLI is optional proprietary software, not bundled in this image. Review and acknowledge Ookla terms and install through the administrator WebUI before using its backend.
Documentation: https://github.com/bmartino1/NetProbe_Python
Readme
View on GitHubNetProbe 2.1
Self-hosted network quality monitoring with a browser dashboard, live diagnostics, historical charts, and optional Speedtest.
NetProbe monitors connectivity with scheduled Ping/ICMP, DNS lookup timing, packet loss, latency, jitter, and an overall connection quality score. It can also measure upload/download speeds using Python speedtest-cli or the separately installed official Ookla Speedtest CLI. Results are available in a responsive HTTPS WebUI with guest read-only access and administrator controls.
Features
- First-run WebUI setup: create an administrator account, sign in, then select monitoring targets and defaults. Scheduled probes stay paused until monitoring setup is completed.
- Read-only guest dashboard: Overview, Metrics, Speedtest, History, Customize Display, and Current Configuration without administrator privileges.
- Administrator tools: run manual Ping/DNS diagnostics, inspect live logs, edit monitoring settings, select a database, manage the password policy, and restart the application worker.
- History and customization: trend charts for quality, packet loss, latency, jitter, DNS, and bandwidth; show or hide summary cards and charts locally in each browser.
- Speedtest backends: Python
speedtest-cliincluded by default. Optional official Ookla CLI requires explicit terms acknowledgement and an administrator-triggered runtime install; the proprietary binary is not bundled. - SQLite or PostgreSQL: SQLite works out of the box. An alternative Compose file starts PostgreSQL 16 and NetProbe together; external PostgreSQL is also supported.
- Single NetProbe configuration mount: persist application settings, credentials, TLS certificates, and SQLite data at
/config. - HTTPS interface: Nginx reverse proxy in front of Flask/Gunicorn with a self-signed fallback certificate for trusted local use.
Screenshots
First-run setup and sign-in
Initial monitoring configuration
Guest dashboard
Administrator diagnostics
Administrator settings
Monitoring pages — guest and administrator
Quick start — SQLite (recommended)
The repository provides compose.yaml for a local SQLite deployment. No .env file is required.
git clone https://github.com/bmartino1/NetProbe_Python.git
cd NetProbe_Python
docker compose -f compose.yaml up -d --build
docker compose -f compose.yaml ps
Open https://YOUR_SERVER_IP:8443/setup and follow the two setup stages:
- Create your administrator username and password (factory minimum: 8 characters).
- Sign in and configure sites, router IP, Ping count, DNS tests, scoring thresholds, and Speedtest options.
The monitoring engine does not begin scheduled probes until the configuration wizard completes. Visit https://YOUR_SERVER_IP:8443/ afterward to use the dashboard. The default certificate is self-signed, so browsers may warn until you install a certificate they trust.
By default, Compose exposes HTTPS on host port 8443 and an HTTP redirect on host port 8080. Both can be changed through NETPROBE_HTTPS_PORT and NETPROBE_HTTP_PORT in an untracked .env file.
To check startup and health:
docker compose -f compose.yaml ps
docker compose -f compose.yaml logs --tail=100 netprobe
Docker Hub image
The published NetProbe 2.1 image can run without building from source:
docker run -d \
--name netprobe \
--restart unless-stopped \
--init \
--cap-add NET_RAW \
-p 8080:80 -p 8443:8443 \
-v netprobe_config:/config \
bmmbmm01/netprobe:latest
bmmbmm01/netprobe:latest tracks the current Docker Hub release. For reproducible deployments, pin bmmbmm01/netprobe:2.1.0. A persistent /config mount is strongly recommended; omitting it loses settings and measurement history when the container is recreated.
WebUI access
| Area | Guest (read-only) | Administrator |
|---|---|---|
| Overview and connection quality | Yes | Yes |
| Ping/DNS Metrics | Yes | Yes |
| Speedtest results and history | Yes | Yes |
| Monitoring history and charts | Yes | Yes |
| Customize display | Yes | Yes |
| Current configuration | Yes | Yes |
| Run manual diagnostics / Speedtest | No | Yes |
| Live Logs & Diagnostics | No | Yes |
| Change settings, database profile, password policy | No | Yes |
Display customization is stored in the current browser and does not change collection settings or delete historical measurements. For unattended installs with known-good settings, NETPROBE_AUTOSTART_CONFIGURED=true explicitly permits starting monitoring before completing the wizard; leave it disabled for interactive first-run setup.
Speedtest backends
Python speedtest-cli is included and requires no separate license acknowledgement in the WebUI. Official Ookla CLI is optional: the administrator selects it during setup or in Settings, reviews Ookla EULA, Terms, and Privacy Policy, and explicitly acknowledges the terms before installation. Acknowledgement accepts I ACCEPT, i accept, or i_accept.
The official executable is installed into the running container, not distributed in the NetProbe Docker image. The acknowledgement persists in /config, but a container/image recreation can remove the executable; use Settings to reinstall it after such a change. Speedtest selection and scheduling can be managed through the WebUI. Bandwidth tests may consume substantial data and temporarily saturate your connection.
PostgreSQL (optional)
The provided file is intentionally named compose-postgress.yaml. It starts a separate PostgreSQL 16 container on a private Compose network and retains data in the netprobe_pgdata volume. Do not run it alongside compose.yaml or combine the files: they use the same NetProbe service, name, and ports.
Create a private .env file with a strong database password, then deploy:
cd NetProbe_Python
umask 077
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env
docker compose -f compose-postgress.yaml config --quiet
docker compose -f compose-postgress.yaml up -d --build
docker compose -f compose-postgress.yaml ps
In Settings → Database connection, review the active database, test the saved PostgreSQL connection, then validate and save the PostgreSQL profile if switching from an existing SQLite setup. An application worker restart is required to activate a saved database-engine change. A running PostgreSQL container does not by itself mean that NetProbe has switched away from an existing saved SQLite profile.
Switching database engines does not migrate historical records. Keep the /config volume (including data/netprobe.sqlite) when switching backends; PostgreSQL has its own persistent database volume. Back up both volumes before migration or significant upgrades. PostgreSQL port 5432 is not exposed publicly by the included Compose file.
For an existing SQLite install, stop the active stack before starting the PostgreSQL stack:
docker compose -f compose.yaml down
# Never use `down -v` if you want to preserve SQLite settings/history.
Configuration and persistence
| Setting / path | Meaning |
|---|---|
/config/settings.json |
Authoritative saved monitoring settings |
/config/database.json |
Database selection and private PostgreSQL profile |
/config/security-policy.json |
Administrator password minimum after editing in Settings |
/config/data/netprobe.sqlite |
SQLite monitoring data, retained if PostgreSQL is selected |
/config/data/ookla-eula-accepted.txt |
Official Ookla terms acknowledgement |
/config/tls/ |
HTTPS certificate and key |
/config/setup.complete |
First-run monitoring completion marker |
/config/ |
Other private application/authentication files |
Docker/Compose environment variables can seed initial settings, but saved WebUI settings take precedence afterward. The Settings page can show genuine differences between explicit Docker-provided values and saved WebUI values. Modifying Docker environment variables alone will not overwrite the existing saved monitoring configuration.
Optional deployment variables include:
| Variable | Default | Use |
|---|---|---|
NETPROBE_HTTP_PORT |
8080 |
Host HTTP redirect port (Compose) |
NETPROBE_HTTPS_PORT |
8443 |
Host HTTPS port (Compose) |
NETPROBE_MIN_PASSWORD_LENGTH |
8 |
Initial password minimum; can be set as low as 6 |
NETPROBE_AUTOSTART_CONFIGURED |
false |
Allow monitoring before wizard completion when explicitly provisioned |
DB_ENGINE |
sqlite |
Initial database engine seed; saved profile can take precedence |
POSTGRES_PASSWORD |
Required for PostgreSQL Compose | PostgreSQL server credential; keep out of Git |
The minimum password length can subsequently be set from Settings → Administrator password policy, using a 6–32-character slider. Existing administrator passwords remain valid when the minimum is changed.
Updating an existing installation
Update the image/source while keeping your persistent data:
git pull --ff-only origin main
docker compose -f compose.yaml build --pull
docker compose -f compose.yaml up -d --no-build
docker compose -f compose.yaml ps
Back up /config first. Do not use docker compose down -v, docker volume rm, or indiscriminate Docker prune commands during an ordinary update. If you use PostgreSQL, use its respective Compose file for updates and back up the PostgreSQL volume too.
API reference
NetProbe's dashboard uses JSON endpoints under /api/. Read-only endpoints are available to guests through the WebUI session. Administrator sessions are required for operations that run tests, modify settings, or access live application logs. A separately configured read-only API bearer token can be used for external dashboard integrations (for example, Grafana); protect it as a secret.
Read-only monitoring endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/score/recent?limit=N |
Recent aggregate Ping/DNS measurements and quality scores |
| GET | /api/score/latest |
Latest aggregate measurement, or data: null before first sample |
| GET | /api/metrics/targets |
Latest live Ping targets and DNS resolver timings (not historical per-target data) |
| GET | /api/config |
Effective read-only configuration, targets, thresholds and backend availability |
| GET | /api/speedtest/history?limit=N |
Stored bandwidth test results |
| GET | /api/speedtest/latest |
Most recent Speedtest result |
| GET | /api/manual/history |
Stored manual Ping/DNS diagnostic history (read-only) |
A recent aggregate score row contains ts, iso, avg_latency_ms, avg_jitter_ms, avg_loss_pct, avg_dns_latency_ms and score (0–100). When available, dns_per_server maps resolver IP addresses to latency in milliseconds.
Example (from a machine that trusts your NetProbe HTTPS certificate):
curl https://YOUR_SERVER_IP:8443/api/score/latest
curl 'https://YOUR_SERVER_IP:8443/api/score/recent?limit=10'
curl https://YOUR_SERVER_IP:8443/api/metrics/targets
curl https://YOUR_SERVER_IP:8443/api/speedtest/latest
These examples assume an authenticated browser session or an appropriately configured read-only API credential where required. The default self-signed certificate must be trusted by the client (or explicitly bypassed for local testing). Response objects may be empty until monitoring has recorded data.
Administrator-only endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET / PUT | /api/settings |
View and save monitoring configuration |
| GET | /api/manual/targets |
Configured/manual test target options |
| POST | /api/manual/run |
Run one Ping or DNS diagnostic |
| POST | /api/speedtest/run |
Run an on-demand bandwidth test |
| GET | /api/logs/live?since=0&limit=250 |
Poll live application log lines |
| GET / PUT | /api/admin/database |
View and save database selection/profile |
| GET | /api/admin/postgres/check |
Test saved PostgreSQL connection |
| GET | /api/admin/speedtest/check |
Check Speedtest backend readiness |
| GET / POST | /api/admin/ookla |
Inspect/install optional Ookla CLI after acknowledgement |
| GET / PUT | /api/admin/password-policy |
Read or change administrator password minimum |
| POST | /api/admin/password |
Change administrator password |
| POST | /api/admin/restart-worker |
Restart the application worker to activate appropriate changes |
For example, the manual Ping diagnostic accepts a JSON body with kind: "ping", target and optional count (1–5); DNS diagnostics use kind: "dns" and a resolver IP. Speedtest requests can specify backend, server_id, secure (Python backend) and force_auto. These are authenticated actions, not public anonymous APIs.
For external integrations, configure NETPROBE_READONLY_API_TOKEN in your deployment and send Authorization: Bearer YOUR_TOKEN on supported read-only GET requests. Never commit API tokens or administrator credentials to Git.
Troubleshooting
- Health or startup:
docker compose -f compose.yaml psanddocker compose -f compose.yaml logs --tail=150 netprobe. - No measurements immediately after first boot: finish the monitoring wizard; probes intentionally wait for the
/config/setup.completemarker. - Self-signed certificate warning: expected for the bundled fallback certificate on a trusted local network.
- False or low quality score: review target availability and packet loss (some internet hosts may reject ICMP). Confirm the router address and DNS servers in Settings.
- Ookla missing after update: the binary lives in the writable container layer and may require reinstallation; the acceptance file can remain in
/config. - PostgreSQL connection error: verify the PostgreSQL container is healthy, database credentials match, and the selected engine is activated after the application worker restart.
- Environment mismatch warning: saved WebUI values are authoritative; review actual Docker-provided overrides and remove obsolete Compose/Unraid seeds if desired.
Security and licenses
Keep unclaimed /setup accessible only on a trusted network. Do not publish the admin interface directly to the internet without additional access controls, trusted TLS, and appropriate reverse-proxy/network protections. Back up authentication material and database credentials securely. The NetProbe image does not need a Docker socket mount.
Official Ookla CLI is proprietary third-party software with its own terms, installed separately only after administrator acknowledgement. See LICENSE and the repository's docs/ directory for the project license, architecture, troubleshooting, and third-party dependency notices.
Project: GitHub · Image: Docker Hub
Categories
Download Statistics
Total Downloads Over Time
Related apps
Explore more like this
Explore allLinks
Details
bmmbmm01/netprobe:latestRuntime arguments
- Web UI
https://[IP]:[PORT:8443]/- Network
bridge- Shell
bash- Privileged
- false
- Extra Params
--cap-add=NET_RAW
Template configuration
NetProbe HTTPS WebUI. Maps Unraid host port 8443 to container port 8443; does not use Unraid host port 443.
- Target
- 8443
- Default
- 8443
- Value
- 8443
Persistent monitoring settings, SQLite data, administrator credentials, HTTPS certificates and optional Ookla acknowledgement. Back up before changing mappings.
- Target
- /config
- Default
- /mnt/user/appdata/netprobe
- Value
- /mnt/user/appdata/netprobe
Initial application timezone, such as America/Chicago. Saved WebUI configuration takes precedence afterward.
- Default
- UTC
- Value
- UTC
First-boot backend preference: ookla or python. Ookla must be installed through administrator Settings after acknowledging its terms.
- Target
- SPEEDTEST_BACKEND
- Default
- ookla
- Value
- ookla
Optional: enter I_ACCEPT only AFTER personally reviewing and agreeing to Ookla's EULA, Terms and Privacy Policy. Leaving this blank requires acknowledgement in the WebUI. Does not install Ookla.
- Target
- SPEEDTEST_OOKLA_ACCEPT_LICENSE
- Value
- I_ACCEPT
Initial setting for scheduled bandwidth testing. The Ookla binary must be installed before Ookla tests can run.
- Default
- true
- Value
- true
Optional HTTP redirect. Unraid host port 8080 maps to container port 80, without binding Unraid host port 80.
- Target
- 80
- Default
- 8080
- Value
- 8080
Initial administrator password minimum. Default 8; minimum 6. Later editable through the WebUI.
- Target
- NETPROBE_MIN_PASSWORD_LENGTH
- Default
- 8
- Value
- 8
Initial database engine: sqlite or postgres. An existing saved database profile may take precedence.
- Default
- sqlite
- Value
- sqlite
Optional external PostgreSQL host or reachable IP. Do not set for SQLite-only installations.
External PostgreSQL server TCP port.
- Default
- 5432
- Value
- 5432
External PostgreSQL database name.
- Default
- netprobe
- Value
- netprobe
External PostgreSQL database user.
- Default
- netprobe
- Value
- netprobe
External PostgreSQL password. Do not use a shared or public default.