first commit

README.md

@@ -0,0 +1,92 @@
+## Network Commander - UniFi Diagnostics
+
+**Network Commander** is a small UniFi controller helper that exposes useful diagnostics over HTTP and is designed to run as a container.
+
+It connects to a UniFi Network Controller (or UniFi OS / UDM) and summarizes:
+
+- **Latency**: average ping to one or more targets
+- **VLANs**: number of configured VLAN networks
+- **Clients**: how many clients are currently connected
+- **Throughput (approx)**: aggregate traffic counters from clients
+- **Site health**: basic status from the controller
+
+You deploy this as a Docker container and point it at your existing UniFi controller.
+
+---
+
+### Configuration
+
+The service is configured entirely via environment variables:
+
+- **`UNIFI_CONTROLLER_URL`**: Base URL to your controller, e.g. `https://unifi.example.com:8443`
+- **`UNIFI_USERNAME`**: Controller username (local admin account is recommended)
+- **`UNIFI_PASSWORD`**: Controller password
+- **`UNIFI_SITE`**: Site name / ID, defaults to `default`
+- **`UNIFI_IS_UDM_PRO`**: `true` if using UniFi OS / UDM / Dream Machine, else `false`
+- **`UNIFI_VERIFY_SSL`**: `true` to validate SSL certs, `false` to skip verification
+- **`PING_TARGETS`**: Comma‑separated hosts to ping for latency, e.g. `1.1.1.1,8.8.8.8`
+
+All credentials should be supplied via environment variables or container secrets, never committed to Git.
+
+---
+
+### Running locally
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export UNIFI_CONTROLLER_URL="https://unifi.example.com:8443"
+export UNIFI_USERNAME="your_user"
+export UNIFI_PASSWORD="your_password"
+export UNIFI_SITE="default"
+export UNIFI_IS_UDM_PRO="false"
+export UNIFI_VERIFY_SSL="true"
+export PING_TARGETS="1.1.1.1,8.8.8.8"
+
+uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload
+```
+
+Once running, hit:
+
+- `GET /health` – controller connectivity + basic site info
+- `GET /diagnostics/summary` – high‑level metrics (latency, VLANs, clients, throughput)
+- `GET /diagnostics/clients` – list of connected clients
+- `GET /diagnostics/vlans` – list of VLAN/network definitions
+
+---
+
+### Docker usage
+
+Build the image:
+
+```bash
+docker build -t network-commander .
+```
+
+Run the container:
+
+```bash
+docker run --rm -p 8080:8080 \
+  -e UNIFI_CONTROLLER_URL="https://unifi.example.com:8443" \
+  -e UNIFI_USERNAME="your_user" \
+  -e UNIFI_PASSWORD="your_password" \
+  -e UNIFI_SITE="default" \
+  -e UNIFI_IS_UDM_PRO="false" \
+  -e UNIFI_VERIFY_SSL="true" \
+  -e PING_TARGETS="1.1.1.1,8.8.8.8" \
+  network-commander
+```
+
+You can then browse to `http://localhost:8080/docs` for the interactive Swagger UI.
+
+---
+
+### Notes / ideas for future expansion
+
+- **Historical trends** by periodically sampling and storing stats
+- **Prometheus metrics** endpoint for easy scraping
+- **Alerting hooks** (webhooks, Slack, etc.) for threshold breaches
+- **Multi‑site support** exposed in the API
+