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

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

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)

docker build -f Dockerfile.multiarch -t voltronic-mqtt:local .

Build Multi-Arch (richiede buildx)

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:

ls -la /dev/ttyUSB*

Verifica permessi:

# Aggiungi utente al gruppo dialout
sudo usermod -a -G dialout $USER

# Riavvia la sessione o logout/login

MQTT non funziona

Test connessione MQTT:

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:

mosquitto_sub -h 192.168.1.100 -p 1883 -u mqtt_user -P password -v -t "homeassistant/sensor/voltronic_#"

Discovery fallisce

Forza re-discovery:

docker restart voltronic-mqtt
# oppure
docker stop voltronic-mqtt
docker rm voltronic-mqtt
docker-compose up -d

Test manuale discovery:

docker exec -it voltronic-mqtt bash -c '/opt/inverter-cli/bin/inverter_poller -d -a'

Verificare logs

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

docker ps
# Colonna STATUS mostra "healthy" o "unhealthy"

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