HomeDash

A self-hosted dashboard built with Rust, Axum and a small HTML/CSS/JavaScript frontend. It brings infrastructure, DNS, media activity, application links, weather and headlines into one configurable view.

Repository

Current features

Area	Readouts and controls
Proxmox VE	CPU, memory, I/O wait, uptime, root storage, load, swap and running/total VM and LXC counts for three nodes
AdGuard Home	Request and blocking totals, response time, filter lists, top domains and recent DNS queries
UniFi	Device status and connected-client count through the Network integration API
Jellyfin	Library counts, active playback and transcoding count
qBittorrent	Transfer rates, queue progress, seeding count and available disk space
Weather	Open-Meteo conditions, illustrated weather symbols and the next five days; location search and metric/imperial units
Workspace	Grouped application links, icons, search, custom colors, sizing, layout and settings import/export
News	Headlines from BBC Technology and Ars Technica

Build and install

The supplied service targets Linux with systemd. Install Git, a current stable Rust toolchain with Cargo, and the platform's native linker/build tools. No Node.js build is needed.

git clone https://git.aaran.cloud/aaran/homedash.git
cd homedash
cargo build --release --locked

Cargo.lock pins dependency resolution. The binary remains named homelab-dashboard to match the service. static/index.html and default-settings.json are embedded at compile time; changing either requires rebuilding. CSS, JavaScript and icons in assets/ are read at runtime from the fixed path /opt/homelab-dashboard/assets. Copy them with the binary on every release.

For a new installation:

sudo useradd --system --home-dir /var/lib/homelab-dashboard \
  --shell /usr/sbin/nologin homelabdash
sudo install -d -m 755 /opt/homelab-dashboard/target/release \
  /opt/homelab-dashboard/assets
sudo install -m 755 target/release/homelab-dashboard \
  /opt/homelab-dashboard/target/release/homelab-dashboard
sudo cp -a assets/. /opt/homelab-dashboard/assets/
sudo install -m 600 .env.example /etc/homelab-dashboard.env
sudoedit /etc/homelab-dashboard.env
sudo install -m 644 homelab-dashboard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now homelab-dashboard

Skip account creation if the service user already exists. Replace all integration placeholders before starting. The service creates /var/lib/homelab-dashboard through StateDirectory and runs as homelabdash. Logs are available with journalctl -u homelab-dashboard.

The example binds to 127.0.0.1:4000 for a reverse proxy on the same host. Use a reachable interface when the proxy runs elsewhere, with access restricted to the intended network. HomeDash serves HTTP; configure HTTPS on the proxy. For an upgrade, preserve the environment and state files, stop the service, replace the release binary and matching assets, then start it again.

Integration configuration

Copy .env.example and supply your own addresses and credentials. The application reads process environment variables; it does not load a .env file itself. The systemd unit loads /etc/homelab-dashboard.env. Restart the service after environment changes.

Variables	Meaning
HOMELAB_DASH_BIND	Listener address and port; application fallback is 0.0.0.0:4000
HOMELAB_SETTINGS_PATH	Shared settings JSON; default /var/lib/homelab-dashboard/settings.json
HOMELAB_ADGUARD_URL, HOMELAB_ADGUARD_AUTH	AdGuard base URL and complete Authorization header value
HOMELAB_PVE_01_URL, HOMELAB_PVE_02_URL, HOMELAB_PVE_03_URL, HOMELAB_PVE_AUTH	Three Proxmox base URLs and a shared complete Authorization header value
HOMELAB_UNIFI_URL, HOMELAB_UNIFI_SITE, HOMELAB_UNIFI_API_KEY	UniFi console URL, integration API site ID and X-API-Key value
HOMELAB_JELLYFIN_URL, HOMELAB_JELLYFIN_KEY	Jellyfin base URL and API key; the application adds MediaBrowser Token="…"
HOMELAB_QBITTORRENT_URL, HOMELAB_QBITTORRENT_USER, HOMELAB_QBITTORRENT_PASSWORD	qBittorrent WebUI address and login; the collector manages its session cookie
RUST_LOG	Tracing filter, for example info,tower_http=warn

Proxmox authentication: use the exact header form PVEAPIToken=dashboard@pve!homedash=TOKEN_SECRET. HomeDash sends the value unchanged; it does not add a Bearer prefix. Give the dedicated token read access to the nodes, cluster resources and storage it must observe, including the token's own permissions when privilege separation is enabled.

AdGuard authentication: provide the complete header, usually Basic BASE64_OF_USERNAME_COLON_PASSWORD. Encode the UTF-8 username:password string without a trailing newline. HomeDash does not encode credentials or perform a separate AdGuard login. Base64 is reversible, so keep this value with the other secrets in the server environment.

Use base URLs without a trailing slash, particularly for media integrations. Empty Jellyfin keys or qBittorrent passwords leave their collectors unavailable. Other collectors still attempt requests when their credentials are empty. Adding an application link does not create a new statistics integration.

Shared settings and personal preferences

• Shared: weather location/units and the application catalog are saved by the UI to the server settings document. Updates use a revision number to detect conflicting saves. A missing settings file loads the embedded defaults; the first shared save writes the file.
• Personal: title, greeting/name, theme and hidden sections are stored in the homedash_profile_v1 browser cookie. They do not follow a user between browsers or devices. Clearing the cookie resets those preferences. These are preferences, not user accounts.
• Import/export: the UI exports the effective dashboard configuration, including application URLs and personal preferences. API credentials are not part of this document. Import previews changes before saving.

The settings directory must exist and be writable. With the supplied service, keep it under /var/lib/homelab-dashboard; moving it elsewhere also requires adjusting systemd's filesystem restrictions. weather-cache.json lives beside the settings file. Back up this state directory and the environment file separately.

Data flow and endpoints

Collectors run on the server and cache results so each open browser does not directly poll every integration.

Endpoint	Collection and browser behavior
GET /api/snapshot	Infrastructure/DNS collection every 10 seconds; browser reads every 5 seconds. AdGuard filter metadata is cached for 5 minutes.
GET /api/media	Jellyfin/qBittorrent collection and browser reads every 10 seconds. Failed refreshes retain prior data with an unavailable status.
GET /api/weather	Refresh after 10 minutes on success, retry after 30 seconds on failure, or refresh after location changes. Browser reads every minute.
GET /api/news	Feeds refresh every 30 minutes; browser reads every minute.
GET /api/settings	Shared configuration; browser checks every 15 seconds outside the settings editor.
PUT /api/settings	Validated, revision-checked shared settings update; requires JSON and X-Homelab-Settings: 1.
GET /api/locations?q=…	On-demand Open-Meteo location search.
GET /api/health	Performs live integration checks per request; it is not a cached application-only health check.

Intervals are nominal; requests and upstream failures can delay them. Browser data polling pauses while the tab is hidden and resumes when visible. The refresh button reads cached data; it does not force upstream collection. Snapshot, weather and news endpoints return HTTP 503 until their cache is ready.

History is held in memory, capped at 120 points and sampled roughly every 30 seconds. New points currently require both first Proxmox nodes and AdGuard to respond. Restarting clears history. Weather can restore a matching disk cache up to six hours old at startup; cached data may remain visible during provider failures.

Current boundaries

• Trusted network deployment: there is no built-in login or authorization. Anyone able to reach the dashboard can read statistics, DNS activity and service URLs, and can submit valid settings updates. The custom settings header and browser cross-site check are not authentication. A public source repository does not make the running dashboard suitable for public access.
• Upstream TLS: the main HTTP client accepts invalid certificates for Proxmox, AdGuard, UniFi, news and location search. Forecast and media clients use normal certificate validation. HTTPS on the dashboard's reverse proxy does not change this upstream behavior.
• Installation-specific integrations: node API paths are currently fixed to node-01, node-02 and node-03, with extra-storage as extra storage. Changing URLs alone does not change those names. Node names/count, news feeds and some quick links/media links remain in source; adapt them for another installation and rebuild or copy the relevant assets.
• Observations, not control: integrations display data. A healthy response does not prove every guest, DNS client or media playback path works. The media UI's Quick Sync label does not detect which transcoding hardware Jellyfin actually used.

Software icons retain their owners' rights; asset sources are listed in assets/SOURCES.txt.

Private deployment configuration

A fresh installation has no application shortcuts, personal greeting or weather location. Choose a location in Settings and enable the weather section. Integration URLs and credentials have no personal fallback. Set HOMELAB_PVE_01_NODE, HOMELAB_PVE_02_NODE, HOMELAB_PVE_03_NODE to your actual Proxmox node identifiers, and HOMELAB_PVE_03_STORAGE to the optional extra storage ID. Keep saved settings and actual environment files outside this repository.