Security Best Practices

To ensure the integrity of your network monitoring and protect your UniFi credentials, follow these security guidelines when deploying the UniFi Dashboard.

Secret Management

The application requires a UniFi API key and Controller URL to function. These are sensitive credentials that grant read access to your network infrastructure.

Never commit .env files: Ensure your .env file is included in your .gitignore. This prevents sensitive keys from being pushed to version control.
Use Environment Variables in Production: In production environments (like Kubernetes or CI/CD pipelines), prefer setting environment variables directly rather than relying on a .env file.
Restrict API Key Scope: If your UniFi controller allows scoped API keys, ensure the key used for this dashboard has read-only permissions. The dashboard does not require write access to monitor your sites.

Securing the BFF (Backend-for-Frontend) Layer

The Node.js server acts as a proxy to bypass CORS restrictions and protect your API key from being exposed to the client's browser.

Implement a Reverse Proxy: The Express server does not include built-in SSL/TLS or authentication. Always deploy this dashboard behind a reverse proxy like Nginx, Caddy, or Traefik.
Enable HTTPS: Configure your reverse proxy to handle SSL termination. This ensures that the data sent from the BFF to your browser is encrypted.
Add Authentication: Since the dashboard is a monitoring tool with no built-in login mechanism, use your reverse proxy to add a layer of authentication (e.g., Basic Auth, Authelia, or Tailscale Auth) before allowing access to port 3000.

Container Security

If you are running the dashboard via Docker, the image is designed with security-first principles.

Non-Root Execution: The official Docker image is configured to run as a non-root user. Do not override the USER instruction in the Dockerfile unless absolutely necessary, as running as root increases the attack surface in the event of a container breakout.
Image Updates: Regularly pull the latest image to ensure you have the latest security patches for the Node.js runtime and Alpine Linux base.
```
docker pull suddenelfilio/unifi-dashboard:latest
```
Read-Only Filesystem: Where possible, run the container with a read-only root filesystem to prevent unauthorized modifications at runtime.

Network Isolation

Restrict Controller Access: If your UniFi Controller is hosted on-premise, configure your firewall to only allow incoming traffic to the Controller's API port from the specific IP address where the UniFi Dashboard is hosted.
Internal Network Deployment: It is highly recommended to keep this dashboard within a private network or accessible only via VPN/Tailscale. Avoid exposing the dashboard directly to the public internet.

Configuration Example (Docker Compose)

When deploying with Docker Compose, use a secure configuration that avoids hardcoding secrets in the YAML file:

services:
  unifi-dashboard:
    image: suddenelfilio/unifi-dashboard:latest
    ports:
      - "127.0.0.1:3000:3000" # Bind to localhost; use a reverse proxy for external access
    env_file: .env
    security_opt:
      - no-new-privileges:true
    restart: unless-stopped