first commit

2026-06-03 00:24:55 -05:00
parent 54941773dd
commit f2d5129720
4 changed files with 415 additions and 0 deletions
@@ -0,0 +1,87 @@
+# AdGuard Home Leaderboard Dashboard
+
+A Flask-based dashboard that pulls DNS query stats from AdGuard Home and displays clients as anime character tier cards.
+
+## Project Structure
+
+```
+adguard-dashboard/
+├── dashboard.py          # Flask app and AdGuard API integration
+├── dashboard.wsgi        # Apache mod_wsgi entry point
+├── templates/
+│   └── dashboard.html    # Frontend tier card UI
+├── static/
+│   └── characters/       # Anime character images (tier1_1.png, etc.)
+├── .env                  # Credentials (not committed to repo)
+└── README.md
+```
+
+## Tiers
+
+| Tier | Label          | Query Range  | Character(s)       |
+|------|----------------|--------------|--------------------|
+| 1    | Innocent       | 0 - 500      | Totoro             |
+| 2    | Rookie         | 501 - 2000   | Zenitsu            |
+| 3    | Protagonist    | 2001 - 5000  | Spike Spiegel      |
+| 4    | Hardened Fighter | 5001 - 10000 | Vegeta, Mikasa, Endeavor, Zoro, Inuyasha |
+| 5    | Final Boss     | 10001+       | Eren Yeager (Founding Titan) |
+
+Each tier randomly selects a character image on page load. Images are stored as `tier{N}_{num}.png` in `static/characters/`.
+
+## Setup
+
+### Prerequisites
+
+- Python 3
+- Apache with mod_wsgi
+- AdGuard Home instance
+
+### Installation
+
+```bash
+sudo mkdir -p /opt/adguard-dashboard/templates
+sudo mkdir -p /opt/adguard-dashboard/static/characters
+sudo python3 -m venv /opt/adguard-dashboard/venv
+sudo /opt/adguard-dashboard/venv/bin/pip install flask requests python-dotenv
+```
+
+Copy files:
+```bash
+sudo cp dashboard.py /opt/adguard-dashboard/
+sudo cp dashboard.wsgi /opt/adguard-dashboard/
+sudo cp templates/dashboard.html /opt/adguard-dashboard/templates/
+```
+
+### Environment Variables
+
+Create `/opt/adguard-dashboard/.env`:
+```
+ADGUARD_HOST=http://192.168.1.235:30004
+ADGUARD_USER=your_username
+ADGUARD_PASS=your_password
+```
+
+Lock down permissions:
+```bash
+sudo chown root:www-data /opt/adguard-dashboard/.env
+sudo chmod 640 /opt/adguard-dashboard/.env
+```
+
+### Apache Configuration
+
+Add a config in `/etc/apache2/sites-available/` pointing to `dashboard.wsgi` via mod_wsgi.
+
+To reload after changes:
+```bash
+sudo touch /opt/adguard-dashboard/dashboard.wsgi
+```
+
+## Adding Characters
+
+Drop images into `static/characters/` named `tier{N}_{num}.png` (e.g. `tier3_2.png`), then update the `TIER_CHARS` object in `dashboard.html` to include the new filename in the appropriate tier array.
+```javascript
+const TIER_CHARS = {
+    1: ['tier1_1.png', 'tier1_2.png'],
+    ...
+};
+```