web-app-python/DOCKER_SYSTEMD_GUIDE.md

Guida Servizio Systemd per Docker Compose

Panoramica

Vengono creati 2 servizi systemd:

1. terrain-docker.service - Gestisce i container Docker (PostgreSQL + Mosquitto)
2. terrain-monitor.service - Gestisce il backend FastAPI (dipende da terrain-docker)

Ordine di avvio automatico: docker → terrain-docker (PostgreSQL + Mosquitto) → terrain-monitor (Backend)

Installazione sul server cloud

Passo 1: Carica i file sul server

# Dal workspace locale
cd /home/alex/devel/web-app-python

scp terrain-docker.service alex@94.177.199.207:/tmp/
scp terrain-monitor.service alex@94.177.199.207:/tmp/
scp start_backend.sh alex@94.177.199.207:/home/alex/devel/web-app-python/

Passo 2: Installa i servizi sul server cloud

# Connettiti al server
ssh alex@94.177.199.207

# Copia i servizi in systemd
sudo cp /tmp/terrain-docker.service /etc/systemd/system/
sudo cp /tmp/terrain-monitor.service /etc/systemd/system/

# Rendi eseguibile lo script di avvio
cd /home/alex/devel/web-app-python
chmod +x start_backend.sh

# Ricarica systemd
sudo systemctl daemon-reload

Passo 3: Abilita e avvia i servizi

# Abilita avvio automatico al boot
sudo systemctl enable terrain-docker
sudo systemctl enable terrain-monitor

# Avvia i servizi (terrain-docker parte automaticamente prima di terrain-monitor)
sudo systemctl start terrain-docker
sudo systemctl start terrain-monitor

# Verifica che tutto funzioni
sudo systemctl status terrain-docker
sudo systemctl status terrain-monitor

Comandi utili

Gestione servizio Docker

# Avvia i container
sudo systemctl start terrain-docker

# Ferma i container
sudo systemctl stop terrain-docker

# Riavvia i container
sudo systemctl restart terrain-docker

# Stato dei container
sudo systemctl status terrain-docker
docker-compose ps

Gestione servizio Backend

# Avvia il backend
sudo systemctl start terrain-monitor

# Ferma il backend
sudo systemctl stop terrain-monitor

# Riavvia il backend (dopo modifiche al codice)
sudo systemctl restart terrain-monitor

# Stato del backend
sudo systemctl status terrain-monitor

# Log in tempo reale
sudo journalctl -u terrain-monitor -f

Riavviare tutto l'ambiente

# Riavvia prima i container, poi il backend
sudo systemctl restart terrain-docker
sleep 5
sudo systemctl restart terrain-monitor

Fermare tutto

# Ferma nell'ordine inverso
sudo systemctl stop terrain-monitor
sudo systemctl stop terrain-docker

Ordine delle dipendenze

Boot
 ↓
docker.service (Docker daemon)
 ↓
terrain-docker.service (PostgreSQL + Mosquitto containers)
 ↓
terrain-monitor.service (FastAPI backend)

Se terrain-docker non parte, terrain-monitor non partirà automaticamente.

Verifica funzionamento

1. Verifica che i container siano running

docker-compose ps

Output atteso:

NAME                          STATUS              PORTS
terrain_monitor-mosquitto-1   Up X minutes        0.0.0.0:1883->1883/tcp
terrain_monitor-postgres-1    Up X minutes        0.0.0.0:5432->5432/tcp

2. Verifica che il backend risponda

curl http://localhost:8000/health

Output atteso:

{"status":"healthy","mqtt_connected":true}

3. Verifica i log

# Log Docker Compose
sudo journalctl -u terrain-docker -n 20

# Log Backend
sudo journalctl -u terrain-monitor -n 50

# Log in tempo reale di entrambi (in due terminali)
sudo journalctl -u terrain-docker -f
sudo journalctl -u terrain-monitor -f

Troubleshooting

I container non partono

# Verifica che Docker sia attivo
sudo systemctl status docker

# Prova manualmente
cd /home/alex/devel/web-app-python
docker-compose up -d
docker-compose ps
docker-compose logs

Il backend non si connette al database/MQTT

# Verifica che i container siano raggiungibili
docker exec -it terrain_monitor-postgres-1 pg_isready
docker exec -it terrain_monitor-mosquitto-1 mosquitto -h

# Controlla i log del backend
sudo journalctl -u terrain-monitor -n 100

Al riavvio del server i servizi non partono

# Verifica che siano abilitati
sudo systemctl is-enabled terrain-docker
sudo systemctl is-enabled terrain-monitor

# Abilita se necessario
sudo systemctl enable terrain-docker
sudo systemctl enable terrain-monitor

Modificare la configurazione dei servizi

# Modifica il servizio
sudo nano /etc/systemd/system/terrain-docker.service
# oppure
sudo nano /etc/systemd/system/terrain-monitor.service

# Ricarica sempre dopo le modifiche
sudo systemctl daemon-reload

# Riavvia il servizio modificato
sudo systemctl restart terrain-docker
sudo systemctl restart terrain-monitor

Note importanti

1. Type=oneshot: Il servizio terrain-docker usa Type=oneshot perché docker-compose è un comando che parte e termina (i container continuano a girare in background).

2. RemainAfterExit=yes: Questo dice a systemd che il servizio è ancora attivo anche se il comando è terminato.

3. Before/After: Definiscono l'ordine di avvio. terrain-docker parte PRIMA di terrain-monitor.

4. Requires vs Wants:

   • Requires: Se terrain-docker fallisce, terrain-monitor non parte
   • Wants: Preferibile ma non obbligatorio

5. User e Group: Entrambi i servizi girano come utente alex. Assicurati che:

   • L'utente possa eseguire docker-compose (gruppo docker)
   • Abbia i permessi sui file del progetto

6. Path di docker-compose: Se docker-compose non è in /usr/bin/, trova il path con which docker-compose e aggiornalo nel servizio.

Aggiunta utente al gruppo docker (se necessario)

# Se ricevi errori di permessi Docker
sudo usermod -aG docker alex
# Poi rilogga o riavvia il server