Refresh RackPeek and UniFi network inventory

docs/operations/UNIFI_NETWORK_ACCESS.md

@@ -0,0 +1,106 @@
+# UniFi network operator access for Doris
+
+## Goal
+
+Give Doris safe, durable read access to the UniFi Network controller at `https://10.5.0.1` so she can:
+
+- verify gateway / switch / AP inventory
+- refresh RackPeek network device data
+- check client/device state during troubleshooting
+- avoid using your full owner account for routine reads
+
+## Preferred access model
+
+Use a **dedicated local Doris account** on UniFi OS with the **least privilege that still allows Network inventory reads**.
+
+Target shape:
+
+- Account name: `doris` or `doris-unifi`
+- Scope: **Network application only**
+- Permission: **view-only / read-only** if UniFi exposes that role cleanly
+- Local account: yes
+- Cloud account sharing: no
+
+If UniFi's UI forces a broader role for API readability, use the narrowest app-scoped permission available and document the final role here.
+
+## Secrets placement
+
+Do **not** commit credentials to git.
+
+When the Doris UniFi account exists, store the live credential in:
+
+- PD live env: `/mnt/docker-ssd/docker/compose/automation/.env`
+- synced encrypted backup: `/mnt/docker-ssd/docker/secrets/env/automation.env`
+
+Expected vars:
+
+```bash
+UNIFI_BASE_URL=https://10.5.0.1
+UNIFI_USERNAME=doris
+UNIFI_PASSWORD=REPLACE_ME
+UNIFI_SITE=default
+UNIFI_VERIFY_TLS=false
+```
+
+After editing the live `.env` on PD, run the normal secrets sync:
+
+```bash
+export PATH="/mnt/docker-ssd/bin:$PATH"
+bash /mnt/docker-ssd/docker/compose/scripts/sync-envs-to-secrets.sh
+```
+
+## Doris helper
+
+Repo helper:
+
+- `automation/bin/unifi_network.py`
+
+Default behavior:
+
+- loads `automation/.env`
+- logs into UniFi OS with cookie auth
+- queries Network app endpoints through `/proxy/network/api/s/<site>/...`
+- prints a JSON inventory summary without exposing the password
+
+Examples:
+
+```bash
+cd /mnt/docker-ssd/docker/compose
+python3 automation/bin/unifi_network.py
+python3 automation/bin/unifi_network.py --raw
+```
+
+## Validation checklist
+
+1. Confirm `https://10.5.0.1` is reachable from Doris's host.
+2. Create the dedicated UniFi operator account.
+3. Add the `UNIFI_*` vars to live `automation/.env` on PD.
+4. Sync secrets repo.
+5. Run:
+
+```bash
+cd /mnt/docker-ssd/docker/compose
+python3 automation/bin/unifi_network.py
+```
+
+Success means Doris can read:
+
+- device inventory
+- controller health summary
+- connected client list
+
+## Future integration
+
+Once access is verified, use the helper as an input for:
+
+- RackPeek network device refreshes
+- dashboard network summaries
+- targeted checks like "what AP is this client on" or "is switch X offline"
+
+## Current status
+
+- UniFi OS front door verified reachable at `https://10.5.0.1`
+- unauthenticated API requests correctly return `401 Unauthorized`
+- Doris helper scaffold exists in the repo
+- dedicated Doris account validated end-to-end against the `default` site from N.O.M.A.D.
+- current verified read scope is sufficient to read device inventory, controller health, and connected clients