Passa al contenuto principale

Aggiungi un nodo worker

Il worker è l'unico nodo di Superhome che gira come container Docker normale (il master gira come app HAOS). È tipicamente un computer piccolo e separato, come un Raspberry Pi 5 o un mini-PC. Va bene qualsiasi macchina in grado di eseguire Docker.

La fotocamera si configura sul master

Non imposti l'URL della fotocamera sul worker. Il worker legge il suo rtsp_url e le altre impostazioni dalla configurazione dell'app Superhome in Home Assistant. Ricordati di impostare lì inference_mode su master-worker (vedi Cluster master-worker).

Prerequisito: Docker​

Il worker gira come container Docker, quindi sulla macchina worker serve Docker (con il plugin Compose) installato. Verifica con docker --version e docker compose version.

Se non è ancora installato:

  • Linux (Pi 5, Debian/Ubuntu, ecc.): lo script ufficiale installa Docker + Compose in un colpo solo con curl -fsSL https://get.docker.com | sh. Vedi docs.docker.com/engine/install.
  • Windows / macOS: installa Docker Desktop, che include Compose.
Usare Docker senza sudo (Linux)

Dopo l'installazione, aggiungi il tuo utente al gruppo docker così da non dover usare sudo: sudo usermod -aG docker $USER, poi esci e rientra nella sessione.

Passaggi​

1. Genera una chiave di registrazione sul master​

Apri il pannello Superhome nel menu laterale di Home Assistant (è l'Hub), vai alla sezione Cluster e clicca Genera chiave di registrazione. Viene visualizzata un'unica chiave come 123456-a1b2c3d4 (PIN a 6 cifre combinato con l'impronta del master) con un pulsante Copia. La chiave è monouso e scade automaticamente dopo poco tempo, quindi esegui questo passo subito prima di avviare il worker.

2. Avvia il container worker​

Sulla macchina worker, crea una cartella dedicata (es. superhome-worker) e, al suo interno, un file chiamato docker-compose.yml con questo contenuto:

services:
  superhome-worker:
    image: ghcr.io/superhome-vision/superhome-worker:latest
    ports:
      - "8765:8765"
    restart: unless-stopped
    user: "1000:1000"
    cap_drop:
      - ALL
    environment:
      SUPERHOME_ROLE: worker
      SUPERHOME_MASTER_HOST: "192.168.1.X:8765"     # IP del tuo host HA, poi :8765 (vedi nota sotto)
      SUPERHOME_ENROLLMENT_PIN: "123456-a1b2c3d4"   # chiave di registrazione dal passaggio 1
    volumes:
      - superhome-worker-data:/data                 # dati persistenti del worker
      - /etc/machine-id:/etc/machine-id:ro

volumes:
  superhome-worker-data:

Poi apri un terminale dentro quella stessa cartella e avvialo:

  • Linux / macOS: apri un terminale nella cartella.
  • Windows: apri la cartella in Esplora File, poi scrivi powershell nella barra degli indirizzi e premi Invio, oppure tasto destro dentro la cartella → Apri nel terminale.
docker compose up -d

docker compose cerca il file docker-compose.yml nella directory corrente, quindi il comando va eseguito dalla cartella che hai creato.

Imposta correttamente SUPERHOME_MASTER_HOST

Usa la forma <IP_HA>:8765 (es. 192.168.1.50:8765):

  • <IP_HA>: l'indirizzo IP del tuo host Home Assistant, senza http://, https:// né slash finale.
  • :8765: la porta di Superhome, non quella di Home Assistant (8123). Lasciala su 8765.

3. Approva il worker sul master​

Dopo che il worker si avvia e si registra, appare nell'Hub del master → Cluster. Approvalo lì. Un worker appena registrato resta inattivo finché non lo approvi.

4. Riavvia il worker​

Una volta approvato, riavvia il container worker così che riceva le sue credenziali e la sua configurazione:

docker compose restart

5. Verifica​

Nell'Hub del master → Cluster, il worker dovrebbe ora risultare connesso. La chiave di registrazione è monouso e non è più valida una volta completato l'enrollment.

Nessuna chiave dopo un riavvio

Riavviare o aggiornare il container worker non richiede una nuova chiave di registrazione; si riconnette da solo. Ti serve una nuova chiave solo se ricrei il worker da zero.

Windows: consigli per Docker​

Se Docker Desktop non parte su Windows, controlla quanto segue da PowerShell:

  • WSL è attivo: wsl --status deve indicare una distribuzione predefinita attiva. Se WSL non è installato/aggiornato, esegui wsl --install (oppure wsl --update) e riavvia.
  • La virtualizzazione è abilitata: Docker Desktop richiede la virtualizzazione hardware. Apri Gestione attività → Prestazioni → CPU e verifica Virtualizzazione: Abilitata. Se è disabilitata, attiva la virtualizzazione (VT-x / AMD-V / SVM) nel BIOS/UEFI.

Qualcosa non funziona?​

Se il worker si registra ma il live stream non si vede, le rilevazioni non scattano mai o il cluster si blocca, vedi la pagina Risoluzione dei problemi.