Table of Contents
Module Setup
Use these pages to collect the URLs and credentials needed by the dashboard admin settings.
Open the dashboard admin page:
http://YOUR-DASHBOARD-HOST:3000/admin
Create the first admin user if this is a fresh install. After login, each module card shows the exact fields the dashboard can store. Paste URLs exactly as the dashboard container can reach them, including https:// or http:// and any custom port.
Secret fields are saved server-side in the Docker data volume. Current releases store dashboard state in /data/dashboard.db. Older JSON files are imported automatically on first startup after upgrade. After a secret is saved, the admin form shows Saved secret instead of sending the existing token back to the browser.
Connection Matrix
| Module | Status | Connection method |
|---|---|---|
| Uptime Kuma | Live | Public status page URL or JSON endpoint. The dashboard tries status-page and heartbeat endpoints to resolve nice names, links, current status lights, and recent heartbeat history. |
| Proxmox | Live | Proxmox API token header. Reads cluster resources, node tasks, backup storage contents, and recent backup task logs. |
| Plex | Live | Plex token saved manually or through the admin Sign in with Plex flow. Reads libraries, sessions, recently added, and library counts. |
| Seerr Requests | Live | x-api-key header to Overseerr/Jellyseerr for stats, search, and request creation. |
| UniFi Network | Live | UniFi Cloud Site Manager API or local Network Integration API using an API key. Shows WAN address, device/client counts, device type breakdowns, and offline device warnings when available. |
| Storage Health | Live | TrueNAS API key, ASUSTOR SNMP, and UniFi NAS SNMP. Reads system information, pool/volume capacity, disk state, alerts, temperatures, recent jobs, and standard SNMP storage rows where exposed. |
| Kavita | Live | Kavita Auth Key via x-api-key; reads auth-key expiry, libraries, server stats, and library item counts. |
| Grimmory | Live | Grimmory Komga-compatible API using basic auth credentials. |
| Navidrome | Live | Subsonic-compatible API using Navidrome username/password with token/salt authentication. |
| Notifications | Optional | Primary/secondary webhooks, destination type, warning/offline toggles, and Proxmox threshold alert rules. |
Module Pages
- Uptime Kuma: status page endpoint setup.
- Proxmox: API token, permission, and backup discovery setup.
- Plex: Plex URL, token, and sign-in setup.
- Seerr Requests: Overseerr/Jellyseerr API key setup.
- UniFi Network: UniFi Cloud and local API setup.
- Storage Health: TrueNAS API setup and storage card behavior.
- Kavita: Kavita Auth Key setup.
- Grimmory: Grimmory Komga-compatible API setup.
- Navidrome: Navidrome Subsonic API setup.
- Notifications: optional webhook alert setup.
- Lab View: wall-board display behavior.
- White Labeling: dashboard name, header copy, logo URL, and documentation links.
- Security Hardening: login protection, settings backup, and deployment notes.
- Documentation Screenshots: screenshot checklist and redaction rules for adding real setup images.
Admin Helpers
Each integration settings card includes a Wiki setup link and, for live modules, a Test saved connection button. Connection tests use the saved configuration, so save changes before testing.
The admin Integration Health panel and dashboard diagnostics view show the latest poll time, last successful poll when available, response time, last error, detail-row count, and module-specific guidance. Integration Health lazy-loads live diagnostics when opened or refreshed so other admin pages can load saved settings without waiting on every integration poll. Failed polls call out the likely credential, TLS, timeout, DNS, or reachability area to check and add a module playbook line for the saved service. Slow or unstable trends explain the latest response, average response, slow sample count, current threshold, and the module-specific latency areas to inspect.
The dashboard diagnostics view uses persisted diagnostic samples to flag slow or unstable integrations. Response warnings default to 75% of INTEGRATION_FETCH_TIMEOUT_MS; tune the threshold from Integration Health or set DASHBOARD_DIAGNOSTIC_WARNING_MS as the environment fallback. Keep the threshold near the slowest response time you consider normal, and only raise it when the service is expected to be slow.
The recovery section includes two exports:
Export settingsdownloads a redacted copy for troubleshooting.Export full backupdownloads the full settings record from the database, including secrets. Store it somewhere encrypted and private.
Reachability Rules
The dashboard backend, not your browser, calls these services. If the dashboard runs in Docker, test from the Docker host or from inside the container network.
Good URL examples:
https://proxmox.example.lan:8006
http://plex:32400
https://uptime.example.lan/status/homelab
https://api.ui.com
Avoid browser-only names such as localhost unless the service is inside the same container. From inside the dashboard container, localhost means the dashboard container itself.
Troubleshooting
If a module stays in Needs config:
- Confirm every required field on that module has a value.
- Save settings.
- Refresh the dashboard.
If a configured live module shows a warning:
- Confirm the dashboard container can resolve the service hostname.
- Confirm the dashboard container can reach the service port.
- Confirm the token has the permissions listed on the module page.
- Check logs:
docker logs homelab-dashboard
For private HTTPS services with self-signed certificates, prefer putting the dashboard and service behind a trusted internal reverse proxy. Proxmox also has an Allow self-signed TLS setting for internal Proxmox connections.