Add readme.md
This commit is contained in:
commit
242c7fb25a
1 changed files with 275 additions and 0 deletions
275
readme.md
Normal file
275
readme.md
Normal file
|
|
@ -0,0 +1,275 @@
|
||||||
|
# UrNetwork Stats Dashboard - Refactored
|
||||||
|
|
||||||
|
|
||||||
|
Hits - [demo](http://38.242.156.120:90) | [](https://hits.sh/38.242.156.120:90/)
|
||||||
|
|
||||||
|
Hits - [repo](https://forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade) | [](https://hits.sh/forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade/)
|
||||||
|
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
## 🇬🇧 English
|
||||||
|
|
||||||
|
### About The Project
|
||||||
|
|
||||||
|
This project is a significantly enhanced and refactored version of the original [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). The application is designed to track, store, and visualize statistics about data transfers (both paid and unpaid) and earnings from your UrNetwork account.
|
||||||
|
|
||||||
|
The entire application is packaged into a single `main_app.py` file for simplicity, yet it contains robust features including a web-based installer, authentication, public/private views, interactive charts, a provider map, and support for webhook notifications.
|
||||||
|
|
||||||
|
> **A Note from the Author**
|
||||||
|
>
|
||||||
|
> I know I might get some hate for using AI to build and refactor this, but since I have access to it for free, I want to make the most of it. Plus, no offense to my friends who can code, but Gemini often explains concepts more clearly! (no hate)
|
||||||
|
> (this readme is made by ai too.... please just dont hate me, im a stupid bitch-ass idiot that's almost braindead and im not even kidding.)
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### ✨ Features
|
||||||
|
|
||||||
|
* **🐍 All-in-One Python Script:** The entire application logic, including the frontend, is contained within a single `main_app.py` file.
|
||||||
|
* **🚀 Web-Based Installer:** A simple setup wizard guides you through configuring your UrNetwork API credentials on the first run.
|
||||||
|
* **🔐 Dual Views (Public/Private):**
|
||||||
|
* **Public Dashboard:** Displays summary stats, total data over time, and a world map of provider locations. Perfect for a quick overview.
|
||||||
|
* **Private Dashboard:** After logging in, you get access to detailed charts, a complete history of data points, webhook management, and other administrative functions.
|
||||||
|
* **📊 Interactive Charts:** Utilizes `Chart.js` for data visualization, including:
|
||||||
|
* Total data provided over time.
|
||||||
|
* Paid vs. Unpaid data comparison.
|
||||||
|
* A bar chart showing data change between intervals.
|
||||||
|
* **🗺️ Provider Map:** Displays the number of active providers by country on a world map using `Leaflet.js`.
|
||||||
|
* **⚙️ Automated Data Collection:** A scheduler (`APScheduler`) automatically fetches and saves new data from the API every 15 minutes.
|
||||||
|
* **🔔 Webhook Notifications:** Add your own webhook URLs (e.g., for Discord) to receive notifications with each new data sync.
|
||||||
|
* **🎨 Modern UI:**
|
||||||
|
* Styled with **Tailwind CSS**.
|
||||||
|
* **Light/Dark/System theme** support.
|
||||||
|
* Fully responsive design.
|
||||||
|
* **💾 Persistent Storage:** Uses `SQLAlchemy` and a `SQLite` database to store historical data.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🚀 Getting Started
|
||||||
|
|
||||||
|
#### Prerequisites
|
||||||
|
|
||||||
|
* Python 3.x
|
||||||
|
* Pip (Python package manager)
|
||||||
|
|
||||||
|
#### Installation
|
||||||
|
|
||||||
|
1. **Clone the repository:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <YOUR_REPOSITORY_URL>
|
||||||
|
cd <FOLDER_NAME>
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Create and activate a virtual environment (recommended):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m venv venv
|
||||||
|
# On Windows
|
||||||
|
.venvScriptsactivate
|
||||||
|
# On macOS / Linux
|
||||||
|
source venv/bin/activate
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Install requirements:**
|
||||||
|
Create a `requirements.txt` file with the following content:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
Flask
|
||||||
|
Flask-SQLAlchemy
|
||||||
|
Flask-APScheduler
|
||||||
|
requests
|
||||||
|
python-dateutil
|
||||||
|
gunicorn
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, install them:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Run the application:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python main_app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
*Note: For a production environment, it's better to use a WSGI server like `gunicorn`.*
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gunicorn --bind 0.0.0.0:90 main_app:app
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Web-based Configuration:**
|
||||||
|
|
||||||
|
* Open `http://localhost:90` (or your server's IP address) in your browser.
|
||||||
|
* You will be redirected to the setup page. Enter your UrNetwork **username** and **password**.
|
||||||
|
* Upon successful verification, a `.env` file will be created with your credentials and a secret key will be generated for the session. The application is now installed.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🕹️ Usage
|
||||||
|
|
||||||
|
After installation, the application is ready to use.
|
||||||
|
|
||||||
|
* **Public Dashboard (`/`):** The main page, accessible to anyone. It shows summary stats and the provider map. The data on this page updates automatically every minute without a page refresh.
|
||||||
|
* **Private Dashboard (`/dashboard`):**
|
||||||
|
* Click on "Owner Dashboard" to access it.
|
||||||
|
* Log in using the same credentials you entered during setup.
|
||||||
|
* Here you will find detailed charts, the full history of all measurements, and you can manage your webhooks.
|
||||||
|
* **Fetch Now:** Manually triggers a data fetch from the API.
|
||||||
|
* **Clear All Data:** Deletes all historical data from the database.
|
||||||
|
* **Webhook Management:** Add or remove URLs for notifications.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🛠️ Tech Stack
|
||||||
|
|
||||||
|
* **Backend:** [Flask](https://flask.palletsprojects.com/)
|
||||||
|
* **Database:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (with SQLite)
|
||||||
|
* **Job Scheduler:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler)
|
||||||
|
* **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/)
|
||||||
|
* **HTTP Requests:** [Requests](https://requests.readthedocs.io/en/latest/)
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🙏 Acknowledgements
|
||||||
|
|
||||||
|
* Original concept and project by **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**.
|
||||||
|
* This version was completely refactored and extended with the help of AI.
|
||||||
|
|
||||||
|
<br>
|
||||||
|
<hr>
|
||||||
|
<br>
|
||||||
|
|
||||||
|
## 🇨🇿 Česky
|
||||||
|
|
||||||
|
### O Projektu
|
||||||
|
|
||||||
|
Tento projekt je výrazně vylepšená a refaktorovaná verze původního [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). Aplikace slouží ke sledování, ukládání a vizualizaci statistik o přenesených datech (placených i neplacených) a výdělcích z vašeho účtu v síti UrNetwork.
|
||||||
|
|
||||||
|
Celá aplikace je zabalena do jediného souboru `main_app.py` pro jednoduchost, ale obsahuje robustní funkce, včetně webového instalátoru, autentizace, veřejného a soukromého pohledu, interaktivních grafů, mapy poskytovatelů a podpory pro webhooky.
|
||||||
|
|
||||||
|
> **Poznámka od Autora**
|
||||||
|
>
|
||||||
|
> Vím, že asi dostanu hejt za to, že jsem na stavbu a refaktoring použil AI, ale když k tomu mám přístup zadarmo, chci toho co nejvíc využít. Navíc, nic proti mým kamarádům, co umí programovat, ale Gemini mi to často vysvětlí srozumitelněji! (no hate)
|
||||||
|
> (Tento soubor readme je také vytvořen umělou inteligencí... Prosím, nenávidějte mě, jsem debilní idiot, který je skoro mrtvýmozkově, a to ani nepřeháním.)
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### ✨ Klíčové Vlastnosti
|
||||||
|
|
||||||
|
* **🐍 All-in-One Python Skript:** Celá logika aplikace, včetně frontendu, je obsažena v jediném souboru `main_app.py`.
|
||||||
|
* **🚀 Webový Instalátor:** Při prvním spuštění vás provede jednoduchým nastavením přihlašovacích údajů k UrNetwork API.
|
||||||
|
* **🔐 Dva Pohledy (Public/Private):**
|
||||||
|
* **Veřejný Dashboard:** Zobrazuje souhrnné statistiky, celkový objem dat v čase a mapu poskytovatelů po celém světě. Ideální pro rychlý přehled.
|
||||||
|
* **Soukromý Dashboard:** Po přihlášení získáte přístup k detailním grafům, kompletní historii měření, správě webhooků a dalším administrátorským funkcím.
|
||||||
|
* **📊 Interaktivní Grafy:** Využívá `Chart.js` pro vizualizaci dat, včetně:
|
||||||
|
* Celkový objem dat v čase.
|
||||||
|
* Porovnání placených vs. neplacených dat.
|
||||||
|
* Graf přírůstků dat mezi jednotlivými měřeními.
|
||||||
|
* **🗺️ Mapa Poskytovatelů:** Zobrazuje na mapě světa (pomocí `Leaflet.js`) počet aktivních poskytovatelů v jednotlivých zemích.
|
||||||
|
* **⚙️ Automatický Sběr Dat:** Plánovač (`APScheduler`) automaticky stahuje a ukládá data z API každých 15 minut.
|
||||||
|
* **🔔 Notifikace přes Webhooky:** Možnost přidat si vlastní webhooky (např. pro Discord) a dostávat notifikace při každé nové synchronizaci dat.
|
||||||
|
* **🎨 Moderní UI:**
|
||||||
|
* Stylováno pomocí **Tailwind CSS**.
|
||||||
|
* Podpora **Světlého/Tmavého režimu** s možností synchronizace s nastavením systému.
|
||||||
|
* Plně responzivní design.
|
||||||
|
* **💾 Perzistentní Úložiště:** Využívá `SQLAlchemy` a `SQLite` databázi pro ukládání historických dat.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🚀 Jak začít
|
||||||
|
|
||||||
|
#### Požadavky
|
||||||
|
|
||||||
|
* Python 3.x
|
||||||
|
* Pip (správce balíčků pro Python)
|
||||||
|
|
||||||
|
#### Instalace
|
||||||
|
|
||||||
|
1. **Klonujte repozitář:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <URL_VAŠEHO_REPOZITÁŘE>
|
||||||
|
cd <NÁZEV_SLOŽKY>
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Vytvořte a aktivujte virtuální prostředí (doporučeno):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m venv venv
|
||||||
|
# Windows
|
||||||
|
.venvScriptsactivate
|
||||||
|
# macOS / Linux
|
||||||
|
source venv/bin/activate
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Nainstalujte potřebné balíčky:**
|
||||||
|
Vytvořte soubor `requirements.txt` s následujícím obsahem:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
Flask
|
||||||
|
Flask-SQLAlchemy
|
||||||
|
Flask-APScheduler
|
||||||
|
requests
|
||||||
|
python-dateutil
|
||||||
|
gunicorn
|
||||||
|
```
|
||||||
|
|
||||||
|
A poté je nainstalujte:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Spusťte aplikaci:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python main_app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
*Poznámka: Pro produkční nasazení je lepší použít WSGI server jako `gunicorn`.*
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gunicorn --bind 0.0.0.0:90 main_app:app
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Webová konfigurace:**
|
||||||
|
|
||||||
|
* Otevřete v prohlížeči adresu `http://localhost:90` (nebo IP adresu vašeho serveru).
|
||||||
|
* Budete přesměrováni na instalační stránku. Zde zadejte své **uživatelské jméno** a **heslo** k účtu UrNetwork.
|
||||||
|
* Po úspěšném ověření se automaticky vytvoří soubor `.env` s vašimi údaji a vygeneruje se tajný klíč pro session. Aplikace se tímto nainstaluje.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🕹️ Použití
|
||||||
|
|
||||||
|
Po instalaci je aplikace připravena k použití.
|
||||||
|
|
||||||
|
* **Veřejný Dashboard (`/`):** Hlavní stránka dostupná komukoliv. Zobrazuje souhrnné statistiky a mapu. Data na této stránce se automaticky aktualizují každou minutu bez nutnosti obnovení stránky.
|
||||||
|
* **Soukromý Dashboard (`/dashboard`):**
|
||||||
|
* Pro přístup klikněte na "Owner Dashboard".
|
||||||
|
* Přihlaste se pomocí stejných údajů, které jste zadali při instalaci.
|
||||||
|
* Zde naleznete detailní grafy, historii všech měření a můžete spravovat webhooky.
|
||||||
|
* **Fetch Now:** Manuálně spustí sběr dat z API.
|
||||||
|
* **Clear All Data:** Smaže veškerá historická data z databáze.
|
||||||
|
* **Webhook Management:** Přidávejte nebo odebírejte URL pro notifikace.
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🛠️ Použité Technologie
|
||||||
|
|
||||||
|
* **Backend:** [Flask](https://flask.palletsprojects.com/)
|
||||||
|
* **Databáze:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (s SQLite)
|
||||||
|
* **Plánovač úloh:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler)
|
||||||
|
* **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/)
|
||||||
|
* **HTTP Požadavky:** [Requests](https://requests.readthedocs.io/en/latest/)
|
||||||
|
|
||||||
|
-----
|
||||||
|
|
||||||
|
### 🙏 Poděkování
|
||||||
|
|
||||||
|
* Původní koncept a projekt vytvořil **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**.
|
||||||
|
* Tato verze byla kompletně refaktorována a rozšířena pomocí AI.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue