240 lines
5.0 KiB
Markdown
240 lines
5.0 KiB
Markdown
# Quick Start Guide - Terrain Monitor
|
|
|
|
Guida rapida per avviare il sistema di monitoraggio terreni in locale.
|
|
|
|
## Prerequisiti
|
|
|
|
- Python 3.12+
|
|
- Docker e Docker Compose
|
|
- Account Firebase (gratuito)
|
|
|
|
## Setup in 5 Passi
|
|
|
|
### 1. Clona e Prepara Ambiente
|
|
|
|
```bash
|
|
# Entra nella directory del progetto
|
|
cd web-app-python
|
|
|
|
# Crea virtual environment
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Linux/Mac
|
|
# .venv\Scripts\activate # Windows
|
|
|
|
# Installa dipendenze
|
|
pip install -e .
|
|
```
|
|
|
|
### 2. Avvia Infrastruttura (PostgreSQL + MQTT)
|
|
|
|
```bash
|
|
# Avvia database e broker MQTT
|
|
docker-compose up -d
|
|
|
|
# Verifica che siano in esecuzione
|
|
docker-compose ps
|
|
```
|
|
|
|
Servizi disponibili:
|
|
- PostgreSQL: `localhost:5432`
|
|
- MQTT Broker: `localhost:1883`
|
|
- pgAdmin: http://localhost:5050 (user: admin@terrain.local, pwd: admin)
|
|
|
|
### 3. Configura Firebase
|
|
|
|
1. Vai su https://console.firebase.google.com/
|
|
2. Crea nuovo progetto "Terrain Monitor"
|
|
3. Abilita Cloud Messaging
|
|
4. Scarica credenziali:
|
|
- ⚙️ Settings → Service Accounts
|
|
- "Generate new private key"
|
|
- Salva come `firebase-credentials.json` nella root
|
|
|
|
### 4. Configura Variabili d'Ambiente
|
|
|
|
```bash
|
|
# Copia template
|
|
cp .env.example .env
|
|
|
|
# Modifica .env (usa questi valori per local development)
|
|
nano .env
|
|
```
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://terrain_user:terrain_pass@localhost:5432/terrain_monitor
|
|
SECRET_KEY=dev-secret-key-change-in-production-minimum-32-chars
|
|
MQTT_BROKER_HOST=localhost
|
|
MQTT_BROKER_PORT=1883
|
|
MQTT_TOPIC=terrain/alarms/#
|
|
FIREBASE_CREDENTIALS_PATH=./firebase-credentials.json
|
|
DEBUG=True
|
|
```
|
|
|
|
### 5. Inizializza Database e Avvia Server
|
|
|
|
```bash
|
|
# Inizializza database con dati di esempio
|
|
python scripts/init_db.py
|
|
|
|
# Avvia il server FastAPI
|
|
python main.py
|
|
```
|
|
|
|
Server disponibile su: http://localhost:8000
|
|
|
|
## Test del Sistema
|
|
|
|
### 1. Verifica API
|
|
|
|
Apri http://localhost:8000/docs per la documentazione interattiva Swagger.
|
|
|
|
### 2. Login
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "admin@azienda.it",
|
|
"password": "admin123"
|
|
}'
|
|
```
|
|
|
|
Salva il token restituito.
|
|
|
|
### 3. Test Allarme MQTT
|
|
|
|
In un nuovo terminale:
|
|
|
|
```bash
|
|
# Attiva virtual environment
|
|
source .venv/bin/activate
|
|
|
|
# Invia allarme di test
|
|
python scripts/test_mqtt.py
|
|
```
|
|
|
|
Dovresti vedere:
|
|
1. ✓ Log nel backend che riceve l'allarme
|
|
2. ✓ Nuovo record nella tabella `allarmi`
|
|
3. ✓ Notifica push inviata (se hai configurato FCM token)
|
|
|
|
### 4. Verifica Allarmi via API
|
|
|
|
```bash
|
|
curl -X GET http://localhost:8000/allarmi \
|
|
-H "Authorization: Bearer YOUR_TOKEN"
|
|
```
|
|
|
|
## Credenziali Utenti Demo
|
|
|
|
Dopo `init_db.py` avrai questi utenti:
|
|
|
|
| Email | Password | Ruolo |
|
|
|-------|----------|-------|
|
|
| admin@azienda.it | admin123 | Admin |
|
|
| operatore@azienda.it | operatore123 | Operatore |
|
|
| viewer@azienda.it | viewer123 | Visualizzatore |
|
|
|
|
## Siti Monitorati Demo
|
|
|
|
1. **Ponte Morandi** (ID: 1) - Genova
|
|
2. **Galleria San Boldo** (ID: 2) - Treviso
|
|
3. **Diga del Vajont** (ID: 3) - Pordenone
|
|
4. **Versante Cà di Sotto** (ID: 4) - Parma
|
|
|
|
## Struttura Allarme MQTT
|
|
|
|
Per inviare allarmi personalizzati via MQTT:
|
|
|
|
```bash
|
|
mosquitto_pub -h localhost -t "terrain/alarms/1" -m '{
|
|
"sito_id": 1,
|
|
"tipo": "movimento_terreno",
|
|
"severita": "critical",
|
|
"titolo": "Movimento rilevato",
|
|
"descrizione": "Movimento anomalo di 15mm",
|
|
"valore_rilevato": 15.0,
|
|
"valore_soglia": 10.0,
|
|
"unita_misura": "mm",
|
|
"timestamp": "2025-10-18T10:30:00Z",
|
|
"dati_sensori": {
|
|
"sensore_1": 15.0,
|
|
"sensore_2": 12.3
|
|
}
|
|
}'
|
|
```
|
|
|
|
## Monitoraggio Logs
|
|
|
|
```bash
|
|
# Backend logs
|
|
# Visibili nel terminale dove hai eseguito python main.py
|
|
|
|
# MQTT broker logs
|
|
docker-compose logs -f mosquitto
|
|
|
|
# Database logs
|
|
docker-compose logs -f postgres
|
|
```
|
|
|
|
## Stop e Cleanup
|
|
|
|
```bash
|
|
# Ferma il server FastAPI
|
|
Ctrl+C nel terminale
|
|
|
|
# Ferma i container Docker
|
|
docker-compose down
|
|
|
|
# Rimuovi anche i dati (ATTENZIONE: cancella il database!)
|
|
docker-compose down -v
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Errore: "Connection refused" su PostgreSQL
|
|
```bash
|
|
# Verifica che il container sia in esecuzione
|
|
docker-compose ps
|
|
|
|
# Riavvia PostgreSQL
|
|
docker-compose restart postgres
|
|
```
|
|
|
|
### Errore: "Firebase credentials not found"
|
|
```bash
|
|
# Verifica che il file esista
|
|
ls -la firebase-credentials.json
|
|
|
|
# Controlla il path in .env
|
|
cat .env | grep FIREBASE
|
|
```
|
|
|
|
### MQTT non riceve messaggi
|
|
```bash
|
|
# Testa la connessione MQTT
|
|
mosquitto_sub -h localhost -t "terrain/alarms/#" -v
|
|
|
|
# In un altro terminale, pubblica un test
|
|
mosquitto_pub -h localhost -t "terrain/alarms/test" -m "hello"
|
|
```
|
|
|
|
## Prossimi Passi
|
|
|
|
1. **App Mobile**: Sviluppa client Flutter/React Native
|
|
2. **Integrazione**: Connetti il tuo sistema di monitoraggio reale
|
|
3. **Deployment**: Usa Docker per deployare in produzione
|
|
4. **Sicurezza**: Configura MQTT con autenticazione
|
|
5. **Monitoring**: Aggiungi logging e metriche
|
|
|
|
## Risorse
|
|
|
|
- FastAPI Docs: https://fastapi.tiangolo.com/
|
|
- Firebase FCM: https://firebase.google.com/docs/cloud-messaging
|
|
- MQTT Protocol: https://mqtt.org/
|
|
- SQLAlchemy: https://docs.sqlalchemy.org/
|
|
|
|
## Supporto
|
|
|
|
Per problemi o domande, consulta il [README.md](README.md) completo.
|