============================================================
       INSTALLATION GUIDE - FLEET CONTROL CONSOLE (SERVER)
============================================================

------------------------------------------------------------
1. PRE-REQUISITES (CRITICAL)
------------------------------------------------------------
Before installing Python dependencies, you must install 
system compilers, development libraries, and pip/venv tools.

Debian/Ubuntu:
   sudo apt update
   sudo apt install build-essential python3-dev libssl-dev libffi-dev python3-pip python3-venv

Create and activate a virtual environment (CRITICAL on Debian 12+):
   cd /opt/fleet-control-server
   python3 -m venv venv
   source venv/bin/activate

Upgrade base pip tools (Must be done INSIDE the venv):
   pip install --upgrade pip setuptools wheel

Install project requirements:
   pip install -r requirements.txt

------------------------------------------------------------
2. SERVER SETUP (CENTRAL HUB)
------------------------------------------------------------
The server handles the web interface and user permissions.

Steps:
1. Configure 'config.json' using 'config.example.json'.
2. Enter MQTT credentials and VAPID keys.
3. Define repeaters in the 'clients.json' file.
4. Install production WSGI server packages (if not in requirements):
   pip install gunicorn gevent gevent-websocket
5. Start the production server: 
   gunicorn -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" -w 1 --bind 0.0.0.0:9000 app:app

------------------------------------------------------------
3. GENERATING VAPID KEYS (PUSH NOTIFICATIONS)
------------------------------------------------------------
⚠️ WARNING: Web Push Notifications strictly require the 
dashboard to be accessed via a secure HTTPS connection.
They will NOT work over standard HTTP.

1. Go to https://vapidkeys.com/ and generate the keys.
2. Copy 'Public Key' and 'Private Key' into 'config.json'.
3. Set 'vapid_claim_email' (e.g., "mailto:your@email.com").

------------------------------------------------------------
4. RUNNING AS A SERVICE (SYSTEMD)
------------------------------------------------------------
⚠️ IMPORTANT (VENV USERS): Before copying the service file, 
open 'fleet-control.service' and ensure the paths point to your 
virtual environment.

Example:
WorkingDirectory=/opt/fleet-control-server
ExecStart=/opt/fleet-control-server/venv/bin/gunicorn -k ...

Configuration:
1. Copy .service file to '/etc/systemd/system/':
   sudo cp fleet-control.service /etc/systemd/system/
2. Reload systemd: sudo systemctl daemon-reload
3. Enable on boot: sudo systemctl enable fleet-console
4. Start service:  sudo systemctl start fleet-console

============================================================
       GUIDA ALL'INSTALLAZIONE - SERVER (ITALIANO)
============================================================

------------------------------------------------------------
1. REQUISITI PRELIMINARI (CRITICI)
------------------------------------------------------------
Prima di installare le dipendenze Python, è necessario 
installare i compilatori di sistema e gli strumenti per pip/venv.
Senza questi, l'installazione fallirà su VPS vergini.

Esegui su Debian/Ubuntu:
   sudo apt update
   sudo apt install build-essential python3-dev libssl-dev libffi-dev python3-pip python3-venv

Crea e attiva un ambiente virtuale (FONDAMENTALE su Debian 12+):
   cd /opt/fleet-control-server
   python3 -m venv venv
   source venv/bin/activate

Aggiorna gli strumenti di base di pip (DA FARE DENTRO il venv):
   pip install --upgrade pip setuptools wheel

Installa i requisiti del progetto:
   pip install -r requirements.txt

------------------------------------------------------------
2. SETUP DEL SERVER
------------------------------------------------------------
Passaggi:
1. Configura 'config.json' partendo da 'config.example.json'.
2. Inserisci credenziali MQTT e chiavi VAPID.
3. Definisci i ripetitori in 'clients.json'.
4. Avvia il server di produzione: 
   gunicorn -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" -w 1 --bind 0.0.0.0:9000 app:app

------------------------------------------------------------
3. GENERAZIONE CHIAVI VAPID
------------------------------------------------------------
⚠️ ATTENZIONE: Le notifiche push richiedono HTTPS.
1. Vai su https://vapidkeys.com/ e genera le chiavi.
2. Copia 'Public Key' e 'Private Key' nel 'config.json'.
3. Imposta 'vapid_claim_email' (es. "mailto:tua@email.com").

------------------------------------------------------------
4. ESECUZIONE COME SERVIZIO (SYSTEMD)
------------------------------------------------------------
⚠️ IMPORTANTE (PER UTENTI VENV): Prima di copiare il file di 
servizio, apri 'fleet-control.service' e assicurati che i percorsi 
puntino al tuo ambiente virtuale!

Esempio:
WorkingDirectory=/opt/fleet-control-server
ExecStart=/opt/fleet-control-server/venv/bin/gunicorn -k ...

Passaggi:
1. Copia il file in systemd: sudo cp fleet-control.service /etc/systemd/system/
2. Ricarica la configurazione: sudo systemctl daemon-reload
3. Abilita all'avvio: sudo systemctl enable fleet-console
4. Avvia il servizio: sudo systemctl start fleet-console