Configuration Guide

The UniFi Network Monitor is configured primarily through environment variables. These variables control how the Back-end for Front-end (BFF) proxy communicates with your UniFi Site Manager and how the application is served.

Environment Variables

To configure the dashboard, create a .env file in the root directory (based on .env.example) or pass these variables directly to your Docker container.

| Variable | Requirement | Description | | :--- | :--- | :--- | | UNIFI_API_KEY | Required | Your UniFi API Key used to authenticate requests. | | UNIFI_API_URL | Required | The full URL to your UniFi Network API integration endpoint. | | PORT | Optional | The port the dashboard server will run on (Default: 3000). |

Variable Details

UNIFI_API_KEY

This key allows the dashboard to fetch data from your UniFi Console. The server sends this key in the X-API-KEY header for all requests to the UniFi API.

• Example: abc123def456ghi789...

UNIFI_API_URL

This is the base endpoint for the UniFi Network API. It must include the protocol (https://) and the full path to the integration version.

• Example: https://your-console-ip.com/proxy/network/integration/v1

PORT

Defines the local port where the Express server will listen. If you are using Docker, this is the internal container port that you would map to a host port.

• Default: 3000

Configuration Methods

Local Development (.env)

For standard Node.js installations, use a .env file in the project root:

# .env configuration
UNIFI_API_KEY=your_secret_api_key_here
UNIFI_API_URL=https://192.168.1.1/proxy/network/integration/v1
PORT=3000

Docker Compose

When deploying via Docker, define the variables in the environment section of your docker-compose.yml:

services:
  unifi-dashboard:
    image: suddenelfilio/unifi-dashboard:latest
    ports:
      - "8080:3000"
    environment:
      - UNIFI_API_KEY=your_secret_api_key_here
      - UNIFI_API_URL=https://your-unifi-host.com/proxy/network/integration/v1
      - PORT=3000

Client-Side Persistence

While the core connection settings are handled via the environment variables above, individual user preferences are stored in the browser's localStorage. These settings persist across page refreshes and browser restarts:

• Theme Preference: Saves whether Dark Mode or Light Mode is active.
• Site Filters: Remembers which specific sites you have chosen to display or hide.
• Mute Status: Remembers if notification sounds are disabled.
• UI State: Stores the expanded/collapsed state of site cards.

Refresh Rates

The dashboard is pre-configured with a 15-second refresh interval. This is currently a hardcoded value in app.js to balance real-time monitoring with API rate-limiting considerations. Each refresh cycle triggers a parallel fetch for sites, devices, and clients across your UniFi infrastructure.