diff --git a/README.md b/README.md index 2562c9a..2861bb5 100644 --- a/README.md +++ b/README.md @@ -3,47 +3,95 @@ 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. +- 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 two files:
+Ensure you have your project directory set up with your files: your-dashboard-folder/
├── dashboard.py
-└── docker-compose.yml +├── listener.py
+├── docker-compose.yml
+└── public/
-And make sure you have an empty public directory for the generated HTML output: -`mkdir -p public` +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:
+Mount your project folder to `/app` and your Navidrome data directory to `/nddata`: -`docker run --rm -v $(pwd):/app -v /path/to/your/navidrome/data:/nddata -e NAVIDROME_DB_PATH="/nddata/navidrome.db" -e OUTPUT_HTML_PATH="/app/public/index.html" python:3.11-slim python /app/dashboard.py` +```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: -`docker compose up -d` +```bash +docker compose up -d +``` You can now view your dashboard in your browser at `http://:8081`. -### Automation (Crontab) -To keep the dashboard updated automatically, you can add a cron job on your host machine to regenerate the HTML page once a day at midnight. +## 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: -`crontab -e` +```bash +crontab -e +``` -Add the following line (making sure to replace `/home/username/dashboard` with your absolute project path and `/path/to/your/navidrome/data` with your actual Navidrome data path): +Add the following line (making sure to replace paths with your absolute project path and actual Navidrome data path): -`0 0 * * * docker run --rm -v /home/username/dashboard:/app -v /path/to/your/navidrome/data:/nddata -e NAVIDROME_DB_PATH="/nddata/navidrome.db" -e OUTPUT_HTML_PATH="/app/public/index.html" python:3.11-slim python /app/dashboard.py` +```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/ \ No newline at end of file +https://unknownuniverse.uk/