docker-voltronic-homeassistant/documentation/DOCKER_SETUP.md

# Docker Setup e Configurazione

## Variabili d'Ambiente

Il container supporta la configurazione tramite variabili d'ambiente per massima flessibilità.

### Variabili Disponibili

| Variabile | Descrizione | Default |
|-----------|-------------|---------|
| `INVERTER_DEVICE` | Device seriale inverter | `/dev/ttyUSB0` |
| `MQTT_SERVER` | Indirizzo IP/hostname broker MQTT | `192.168.1.37` |
| `MQTT_PORT` | Porta broker MQTT | `1883` |
| `MQTT_TOPIC` | Topic base MQTT | `homeassistant` |
| `MQTT_DEVICENAME` | Nome device per i topic | `voltronic` |
| `MQTT_USERNAME` | Username autenticazione MQTT | (vuoto) |
| `MQTT_PASSWORD` | Password autenticazione MQTT | (vuoto) |
| `FORCE_DISCOVERY` | Forza discovery ad ogni avvio | `false` |
| `SKIP_DISCOVERY` | Salta discovery, usa solo config | `false` |

### Esempio docker-compose.yml

```yaml
version: '3'

services:
  voltronic-mqtt:
    image: bushrangers/ha-voltronic-mqtt
    container_name: voltronic-mqtt
    privileged: true
    restart: always
    
    environment:
      # Device configuration
      - INVERTER_DEVICE=/dev/ttyUSB0
      
      # MQTT Broker configuration
      - MQTT_SERVER=192.168.1.100
      - MQTT_PORT=1883
      - MQTT_TOPIC=homeassistant
      - MQTT_DEVICENAME=voltronic
      - MQTT_USERNAME=mqtt_user
      - MQTT_PASSWORD=secret_password
      
      # Discovery options
      - FORCE_DISCOVERY=false
      - SKIP_DISCOVERY=false
    
    volumes:
      - ./config/:/etc/inverter/
    
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0:rwm
      - /dev/ttyUSB1:/dev/ttyUSB1:rwm
```

### Esempio docker run

```bash
docker run -d \
  --name voltronic-mqtt \
  --privileged \
  --restart always \
  -e INVERTER_DEVICE=/dev/ttyUSB0 \
  -e MQTT_SERVER=192.168.1.100 \
  -e MQTT_PORT=1883 \
  -e MQTT_USERNAME=mqtt_user \
  -e MQTT_PASSWORD=secret_password \
  -v $(pwd)/config:/etc/inverter/ \
  --device=/dev/ttyUSB0:/dev/ttyUSB0:rwm \
  bushrangers/ha-voltronic-mqtt
```

## Topic MQTT Pubblicati

Con configurazione default (`MQTT_DEVICENAME=voltronic`):

### Singolo Inverter
```
homeassistant/sensor/voltronic_Battery_voltage
homeassistant/sensor/voltronic_Load_watt
homeassistant/sensor/voltronic_PV_in_voltage
... (e altri)
```

### Multi-Inverter Paralleli
```
homeassistant/sensor/voltronic_inv1_serial
homeassistant/sensor/voltronic_inv1_Battery_voltage
homeassistant/sensor/voltronic_inv1_Load_watt
homeassistant/sensor/voltronic_inv2_serial
homeassistant/sensor/voltronic_inv2_Battery_voltage
homeassistant/sensor/voltronic_inv2_Load_watt
... (e altri)
```

## Build Locale

### Build Semplice (architettura corrente)
```bash
docker build -f Dockerfile.multiarch -t voltronic-mqtt:local .
```

### Build Multi-Arch (richiede buildx)
```bash
docker buildx build \
  --platform linux/arm/v6,linux/arm/v7,linux/arm64 \
  -f Dockerfile.multiarch \
  -t voltronic-mqtt:multi-arch \
  --load \
  .
```

## Configurazione Secrets Gitea (per CI/CD)

Se vuoi abilitare il push automatico su Docker Hub tramite Gitea Actions:

1. Vai su Gitea → Repository → Settings → Secrets
2. Aggiungi i seguenti secrets:
   - `DOCKER_USERNAME`: tuo username Docker Hub
   - `DOCKER_PASSWORD`: token di accesso Docker Hub (o password)

**Nota:** Se i secrets non sono configurati, il workflow eseguirà comunque la build ma **non farà push** su Docker Hub (utile per testing).

### Creare un Access Token Docker Hub

1. Login su https://hub.docker.com
2. Account Settings → Security → New Access Token
3. Copia il token generato
4. Usa questo token come `DOCKER_PASSWORD` in Gitea

## Troubleshooting

### Container non si avvia

**Verifica device:**
```bash
ls -la /dev/ttyUSB*
```

**Verifica permessi:**
```bash
# Aggiungi utente al gruppo dialout
sudo usermod -a -G dialout $USER

# Riavvia la sessione o logout/login
```

### MQTT non funziona

**Test connessione MQTT:**
```bash
docker exec -it voltronic-mqtt bash -c "mosquitto_pub -h \$MQTT_SERVER -p \$MQTT_PORT -u \$MQTT_USERNAME -P \$MQTT_PASSWORD -t test/voltronic -m 'test'"
```

**Verifica topic pubblicati:**
```bash
mosquitto_sub -h 192.168.1.100 -p 1883 -u mqtt_user -P password -v -t "homeassistant/sensor/voltronic_#"
```

### Discovery fallisce

**Forza re-discovery:**
```bash
docker restart voltronic-mqtt
# oppure
docker stop voltronic-mqtt
docker rm voltronic-mqtt
docker-compose up -d
```

**Test manuale discovery:**
```bash
docker exec -it voltronic-mqtt bash -c '/opt/inverter-cli/bin/inverter_poller -d -a'
```

### Verificare logs

```bash
# Logs real-time
docker logs -f voltronic-mqtt

# Ultimi 100 righe
docker logs --tail 100 voltronic-mqtt

# Logs con timestamp
docker logs -t voltronic-mqtt
```

## Health Check

Il container include un healthcheck automatico che verifica:
- Processo inverter_poller attivo
- Comunicazione con l'inverter funzionante

Status:
```bash
docker ps
# Colonna STATUS mostra "healthy" o "unhealthy"

# Dettagli healthcheck
docker inspect --format='{{json .State.Health}}' voltronic-mqtt | jq
```