# Navidrome Dashboard
A lightweight, self-hosted multi-user dashboard for Navidrome.  
**Aggregates play counts, filters duplicates, sorts your top tracks, and serves a clean, mobile-responsive HTML page via Nginx.**

## Features
- All-Time Stats: Aggregates total play counts and tracks the most recent timestamp for every song played.
- Multi-User Support: Automatically detects all registered Navidrome users and creates individual cards for each.
- Smart Sorting: Ordered by total plays (descending), then last played date, then alphabetically by artist name.
- Fully Responsive: Adapts cleanly to wide desktop screens and stacks vertically on mobile devices.
- Zero Heavy Dependencies: Runs entirely via standard Python libraries and a lightweight Nginx container.

## Setup & Instructions

### 1. Repository Structure
Ensure you have your project directory set up with your files:

your-dashboard-folder/<br>
├── dashboard.py<br>
├── listener.py<br>
├── docker-compose.yml<br>
└── public/<br>          

Create the public directory if it doesn't exist:
```bash
mkdir -p public
```

### 2. Generate the Dashboard HTML
You can run the Python script on-demand using a temporary Python container. 

Mount your project folder to `/app` and your Navidrome data directory to `/nddata`:

```bash
docker run --rm -v $(pwd):/app -v /path/to/your/navidrome/data:/nddata python:3.11-slim python /app/dashboard.py
```

### 3. Start the Web Server
Spin up the Nginx container using Docker Compose:
```bash
docker compose up -d
```

You can now view your dashboard in your browser at `http://<your-server-ip>:8081`.

## Background Services & Automation

### 1. HTTP Listener (Systemd Service)
To power the "Regenerate Stats" button directly from the dashboard web UI, `listener.py` runs a lightweight HTTP server on port `8083` that triggers the update command when called.

You can set this up as a persistent systemd service so it starts automatically on boot:

1. Create the systemd service file:
   ```bash
   sudo nano /etc/systemd/system/dashboard-listener.service
   ```

2. Add the following configuration (make sure to replace `/home/username/dashboard` and `User=username` with your actual system path and username):
   ```ini
   [Unit]
   Description=Dashboard Refresh Listener
   After=network.target docker.service

   [Service]
   User=username
   WorkingDirectory=/home/username/dashboard
   ExecStart=/usr/bin/python3 /home/username/dashboard/listener.py
   Restart=always

   [Install]
   WantedBy=multi-user.target
   ```

3. Enable and start the service:
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable dashboard-listener
   sudo systemctl start dashboard-listener
   ```

### 2. Daily Cron Job (Optional)
To keep the dashboard updated automatically once a day at midnight, you can add a cron job on your host machine.

Open your crontab editor:
```bash
crontab -e
```

Add the following line (making sure to replace paths with your absolute project path and actual Navidrome data path):

```bash
0 0 * * * docker run --rm -v /home/username/dashboard:/app -v /path/to/your/navidrome/data:/nddata python:3.11-slim python /app/dashboard.py
```
---

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/theunknownuniverse)

https://unknownuniverse.uk/