web-app-python/QUICKSTART.md

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

# 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)

# 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

# Copia template
cp .env.example .env

# Modifica .env (usa questi valori per local development)
nano .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

# 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

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:

# 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

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:

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

# 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

# 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

# Verifica che il container sia in esecuzione
docker-compose ps

# Riavvia PostgreSQL
docker-compose restart postgres

Errore: "Firebase credentials not found"

# Verifica che il file esista
ls -la firebase-credentials.json

# Controlla il path in .env
cat .env | grep FIREBASE

MQTT non riceve messaggi

# 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 completo.