app backend prima
This commit is contained in:
239
QUICKSTART.md
Normal file
239
QUICKSTART.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user