Local Development

Setting up the UniFi Dashboard locally allows you to customize the interface or debug connection issues with your UniFi controller. The project uses a Backend-for-Frontend (BFF) architecture: a small Node.js server proxies requests to the UniFi API to handle authentication and bypass CORS restrictions, while a vanilla JavaScript frontend renders the data.

Prerequisites

Before starting, ensure you have the following installed:

Node.js: Version 20.x is recommended (minimum v14.x).
UniFi API Access: A valid API Key and the URL for your UniFi Site Manager or local controller.

1. Installation

Clone the repository and install the necessary dependencies for the Express server:

git clone https://github.com/suddenelfilio/unifi-dashboard.git
cd unifi-dashboard
npm install

2. Configuration

The application relies on environment variables to communicate with the UniFi API. Create a .env file in the root directory by copying the provided example:

cp .env.example .env

Open .env and configure the following variables:

3. Running the Application

Start the local development server using the start script:

npm start

Once the server initializes, you should see a confirmation message in your terminal: ✓ Using API URL: https://... 🚀 UniFi Dashboard BFF running on http://localhost:3000

Open your browser and navigate to http://localhost:3000.

4. Development Workflow

The project is structured for simplicity:

Frontend Logic (/app.js): Handles data fetching from the local BFF, state management (refresh timers, site filtering), and DOM updates.
Styling (/style.css): Contains both Light and Dark theme definitions. Theme switching is handled via CSS variables.
Backend Proxy (/server.js): An Express server that attaches the X-API-KEY header to outgoing requests. If you modify the backend API routes, you must restart the server to see changes.

Troubleshooting

CORS Errors: Ensure you are accessing the dashboard through the Node.js server (e.g., localhost:3000) rather than opening index.html directly as a file. The frontend must route requests through the local /api proxy.
Missing API Key: If the server fails to start, verify that UNIFI_API_KEY is correctly set in your .env file. The server performs a validation check on startup and will exit if the key is missing.
Connection Refused: Ensure your UniFi controller is reachable from your development machine and that the UNIFI_API_URL includes the correct protocol (http:// or https://).