chore: update water data sets and migrate docker configuration to directory-based structure
continuous-integration/drone/push Build encountered an error
continuous-integration/drone/push Build encountered an error
This commit is contained in:
David Fencl
@@ -1,101 +1,102 @@
|
||||
# 🌊 HLADINATOR
|
||||
|
||||
HLADINATOR je interaktivní a vizuálně poutavá webová aplikace pro sledování aktuálního stavu a historie českých přehrad. Aplikace poskytuje přesná data o výšce hladiny, odtoku, přítoku, aktuálním objemu a navíc sbírá historii počasí (teploty a srážek) přímo od zdroje.
|
||||
HLADINATOR is an interactive and visually engaging web application for monitoring the current status and history of Czech reservoirs. The application provides precise data on water level, outflow, inflow, current volume, and additionally collects weather history (temperature and precipitation) directly from the source.
|
||||
|
||||
Zdroj dat: **Povodí Vltavy (pvl.cz)** a další povodí v ČR.
|
||||
Data source: **Povodí Vltavy (pvl.cz)** and other river basin administrators in the Czech Republic.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Jak spustit aplikaci lokálně
|
||||
## 🚀 How to Run the Application Locally
|
||||
|
||||
Aplikace je postavena na moderním stacku (React, Vite, TypeScript, Recharts, Leaflet). Pro její spuštění nepotřebuješ žádný složitý backend, data se čtou z předgenerovaných JSON souborů.
|
||||
The application is built on a modern stack (React, Vite, TypeScript, Recharts, Leaflet). You don't need any complex backend to run it locally; the data is read directly from pre-generated static JSON files.
|
||||
|
||||
1. Nainstaluj závislosti (pokud jsi to ještě neudělal):
|
||||
1. Install dependencies (if you haven't already):
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
2. Spusť lokální vývojový server:
|
||||
2. Start the local development server:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
3. Otevři prohlížeč na adrese `http://localhost:5173`.
|
||||
3. Open your browser at `http://localhost:5173`.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Jak aktualizovat data (Scraping)
|
||||
## 🔄 How to Update Data (Scraping)
|
||||
|
||||
Povodí Vltavy neposkytuje standardní API pro historii srážek a teplot, ani nepodporuje přímé dotazy z klientského prohlížeče (kvůli CORS a bezpečnosti). Proto využíváme vlastní **scraper**.
|
||||
Povodí Vltavy does not provide a standard API for weather history, nor does it support direct requests from client browsers (due to CORS and security restrictions). Therefore, we use our own custom **scraper**.
|
||||
|
||||
Pro ruční stažení těch nejnovějších dat z webu povodí spusť v terminálu:
|
||||
To manually fetch the latest data from the river basin websites, run in your terminal:
|
||||
```bash
|
||||
npm run data:update
|
||||
```
|
||||
|
||||
Tento příkaz provede dvě věci:
|
||||
1. `npm run scrape`: Otevře stránky povodí pro všech **53 nádrží a říčních stanic**, přečte tabulky s historickými měřeními a najde "Aktuální hodnoty", odkud vytáhne exaktní **přítok, odtok, objem, srážky a teplotu**. Tato data inteligentně sloučí s tvojí lokální databází (`public/data/*.json`) a automaticky doplňuje chybějící hodnoty přítoku/objemu z minula, aby graf neměl výpadky k nule.
|
||||
2. `npm run build-index`: Zaktualizuje hlavní indexový soubor `lakes_index.json`, který aplikace využívá pro vykreslení rychlých náhledů (např. v levém menu nebo na mapě).
|
||||
This command performs two actions:
|
||||
1. `npm run scrape`: Scrapes the website for all **53 reservoirs and river stations**, parses historical measurement tables, extracts precise **inflow, outflow, volume, precipitation, and temperature**. It then merges this data intelligently with your local database (`public/data/*.json`) and automatically backfills missing values from previous steps to avoid zero-drop anomalies in the charts.
|
||||
2. `npm run build-index`: Updates the main index file `lakes_index.json`, which the app uses to render fast previews (e.g., in the side menu or on the map).
|
||||
|
||||
---
|
||||
|
||||
## ⏰ Automatické stahování dat (Cron / Spouštěč)
|
||||
## ⏰ Automated Data Updates (Cron / Scheduler)
|
||||
|
||||
Aby se ti automaticky budovala bohatá historie počasí a srážek i ve chvíli, kdy spíš, doporučuji nastavit automatické spouštění skriptu `npm run data:update`.
|
||||
To automatically accumulate weather and precipitation history even when your machine is off or you are sleeping, we recommend automating the execution of the `npm run data:update` script.
|
||||
|
||||
Zde jsou nejběžnější možnosti, jak si to můžeš nastavit ty sám:
|
||||
Here are the most common deployment methods:
|
||||
|
||||
### Možnost A: Přes Crontab na Macu / Linuxu (Lokálně)
|
||||
Pokud ti běží počítač (nebo domácí server/Raspberry Pi) nepřetržitě, můžeš využít systémový `cron`.
|
||||
1. Otevři terminál a napiš: `crontab -e`
|
||||
2. Na konec souboru vlož následující řádek (uprav cestu ke svému projektu a Node.js):
|
||||
### Option A: Using Crontab on macOS / Linux (Local)
|
||||
If you have a computer or home server (like a Raspberry Pi) running continuously:
|
||||
1. Open the terminal and type: `crontab -e`
|
||||
2. Add the following line at the end of the file (adjust the paths to your project and Node.js installation):
|
||||
```bash
|
||||
# Spustit scraping každých 15 minut
|
||||
# Run scraping every 15 minutes
|
||||
*/15 * * * * cd /Users/davis/WebstormProjects/davisfe.cz && /usr/local/bin/npm run data:update >> scraper.log 2>&1
|
||||
```
|
||||
3. Ulož a zavři editor. Od této chvíle se systém postará o automatický sběr dat!
|
||||
3. Save and close the editor. The system scheduler will take care of the rest.
|
||||
|
||||
### Možnost B: Pomocí GitHub Actions (Pro Produkci)
|
||||
Až projekt nahraješ na GitHub, můžeš si vytvořit workflow soubor (např. `.github/workflows/scrape.yml`), který bude skript spouštět na serverech GitHubu zdarma každou hodinu, a výsledné `.json` soubory automaticky commitne a publikuje na web.
|
||||
### Option B: Using GitHub Actions (For Production Hosting)
|
||||
Once you push the project to GitHub, you can create a workflow file (e.g., `.github/workflows/scrape.yml`) to run the scraping script every hour on GitHub runners for free, and automatically commit and publish the updated `.json` data files back to the repository.
|
||||
|
||||
### Možnost C: Jednoduchý integrovaný spouštěč (Doporučeno pro vývoj)
|
||||
Pokud nechceš řešit složitý systémový crontab, je v projektu připraven inteligentní plánovač. Stačí si otevřít další okno terminálu a napsat:
|
||||
### Option C: Built-in Simple Scheduler (Recommended for Development)
|
||||
If you do not want to set up system cron, the project has a built-in scheduler. Open another terminal tab/window and run:
|
||||
```bash
|
||||
npm run data:watch
|
||||
```
|
||||
Tento příkaz provede okamžitou aktualizaci a poté automaticky spouští stahování vždy 7 minut po každém 10minutovém kroku (např. 18:07, 18:17, 18:27...). Tento posun zaručuje, že Povodí už stihlo na svůj web nahrát nová data a nestahuješ staré hodnoty.
|
||||
This command triggers an immediate update and then automatically schedules updates at 7 minutes past every 10-minute step (e.g., 18:07, 18:17, 18:27...). This delay ensures that the river basin web page has updated its data, preventing duplicate/empty requests.
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Spuštění v Dockeru (Produkce a vlastní server)
|
||||
## 🐳 Running in Docker (Production & Own Server)
|
||||
|
||||
Pokud chceš aplikaci nasadit na vlastní server a rovnou s ní spustit i databázi PostgreSQL (TimescaleDB) pro budoucí ukládání dat, je připravena konfigurace pro Docker Compose.
|
||||
If you want to deploy the application on your own server and run a PostgreSQL (TimescaleDB) database alongside it for future data collection, a Docker Compose configuration is prepared inside the `Docker` directory.
|
||||
|
||||
### Požadavky:
|
||||
- Nainstalovaný **Docker** a **Docker Compose**.
|
||||
### Requirements:
|
||||
- Installed **Docker** and **Docker Compose**.
|
||||
|
||||
### Spuštění:
|
||||
1. Spusť sestavení a start kontejnerů na pozadí:
|
||||
### Deployment:
|
||||
1. Go to the `Docker` directory and build/run the containers in the background:
|
||||
```bash
|
||||
cd Docker
|
||||
docker-compose up -d --build
|
||||
```
|
||||
2. Docker Compose spustí dva kontejnery:
|
||||
- **`hladinator-db`**: Kontejner s databází PostgreSQL (TimescaleDB) běžící na portu `5432` se svazkem `pgdata` pro persistenci.
|
||||
- **`hladinator-web`**: Webový server Apache servírující zkompilovanou React aplikaci na portu `80`.
|
||||
2. Docker Compose will launch two containers:
|
||||
- **`hladinator-db`**: PostgreSQL (TimescaleDB) database running on port `5432` with a `pgdata` volume for data persistence.
|
||||
- **`hladinator-web`**: Apache web server serving the built React static application on port `80`.
|
||||
|
||||
3. Web je následně dostupný na portu `80` vašeho serveru.
|
||||
3. The web application is then accessible on port `80` of your server.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Oprava chyb v historii (Zuby / Nuly v grafu)
|
||||
## 🛠️ Fixing Anomalies in History (Zero Drops / Teeth in Graphs)
|
||||
|
||||
Pokud ti aplikace delší dobu neběžela (např. při vypnutém počítači) a následně došlo k doplnění dat z historie, mohly se v grafech přítoku a objemu objevit falešné propady k nule (zuby). Pro vyčištění celé historie a dopočítání těchto bodů z posledních známých hodnot spusť:
|
||||
If the scraper hasn't run for a while (e.g., when your computer was turned off) and data was filled in subsequently, anomalies or drops to zero (teeth) might appear in the inflow and volume graphs. To clean up the entire history and interpolate these points from the last known state, run:
|
||||
|
||||
```bash
|
||||
npm run data:fix
|
||||
```
|
||||
Tento skript projde všechny datové JSON soubory, detekuje anomálie/nuly a opraví je.
|
||||
This script scans all data JSON files, detects anomalies/zeros, and repairs them.
|
||||
|
||||
## 📁 Struktura klíčových datových složek
|
||||
## 📁 Key File and Folder Structure
|
||||
|
||||
* `/scripts/lakesConfig.ts` - Tady najdeš definici všech **53 sledovaných nádrží a řek** (včetně jejich ID pro Povodí Vltavy, GPS souřadnic, maximálních objemů a stavebních kót). Sem můžeš přidávat nové stanice.
|
||||
* `/public/data/` - Zde se ukládají vygenerovaná JSON data. V produkci musí být tyto soubory přístupné jako statické assety.
|
||||
* `/src/components/` - Obsahuje samotné vizuální karty, Leaflet mapu a detailní `LakeDetail.tsx` (kde se vykresluje hydrologický a meteorologický graf přes Recharts s automatickým čištěním chyb a senzorických úletů).
|
||||
* `/scripts/lakesConfig.ts` - Contains configuration definitions for all **53 monitored reservoirs and rivers** (including their river basin ID, GPS coordinates, maximum capacity limits, and elevation heights). You can add new stations here.
|
||||
* `/public/data/` - Static storage location for generated JSON files. In production, these must be exposed as static assets.
|
||||
* `/src/components/` - Holds user interface components, the Leaflet map, and `LakeDetail.tsx` (renders historical hydrology and weather charts via Recharts with automatic anomaly filtering).
|
||||
|
||||
Reference in New Issue
Block a user