Docker

Una guida per installare CUBE OS usando Docker sui sistemi Linux.

Installa CUBE OS come contenitore Docker su un host Linux. Questo metodo funziona bene per server domestici, dispositivi NAS e macchine Linux sempre attive.

La distribuzione Docker è supportata su solo Linux.

Se non hai un host Linux, usa Raspberry Pi o Macchina virtuale.

1. Preparazione

1

Controlla l'architettura dell'host

CUBE Docker supporta queste architetture Linux:

• amd64 (x86_64) — PC, server, NAS Synology e dispositivi simili

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi e altri host ARM

2

Controlla la versione del kernel Linux

Kernel 4.15 o successivo è richiesto.

uname -r

Alcuni dispositivi NAS vengono forniti con kernel più vecchi, come 4.4.x. Questi host non sono compatibili con CUBE Docker. In tal caso, esegui invece CUBE OS in una macchina virtuale Linux.

3

Installa Docker Engine

Installa Docker Engine sull'host prima di continuare.

Usa la guida ufficiale all'installazione di Docker.

4

Verifica le porte richieste

Assicurati che le porte 80 e 1883 siano libere sull'host.

sudo lsof -i :80
sudo lsof -i :1883

• 80 — interfaccia web di CUBE OS

• 1883 — broker MQTT

Se un altro servizio sta usando queste porte, arrestalo prima.

5

Prepara un dongle Zigbee se necessario

Se prevedi di aggiungere dispositivi Zigbee, collega all'host un dongle Zigbee compatibile.

I dongle Zigbee testati includono:

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Altri elencati dal sviluppatore @darkxst

Per ulteriori informazioni sulle configurazioni e la compatibilità Zigbee, consultare questo guida.

Per ulteriori informazioni sul supporto Zigbee, fai riferimento a questa guida.

2. Scarica l'immagine

1

Scarica l'ultima immagine

docker pull ghcr.io/ewelinkcube/cube-os:latest

Puoi sostituire latest con un tag di versione specifico, come 2.10.3. Le versioni disponibili sono elencate su GitHub Releases.

3. Avvia CUBE OS

1

Crea una directory dati

mkdir -p ~/cubeos-data

Questa directory memorizza i tuoi dispositivi, scene e impostazioni.

2

Controlla il percorso del dispositivo Zigbee se ne usi uno (facoltativo)

I percorsi comuni dei dispositivi sono:

ls /dev/ttyUSB* /dev/ttyACM*

Usa il percorso corretto nel comando successivo.

3

Avvia il contenitore

Usa questo comando come base:

docker run -d \
  --name cubeos \
  --privileged \
  --net=host \
  -v ~/cubeos-data:/data \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
  ghcr.io/ewelinkcube/cube-os:latest

Se non usi Zigbee, rimuovi --device /dev/ttyUSB0:/dev/ttyUSB0.

Se non usi Matter Hub o eWeLink Remote, puoi anche rimuovere il mount di D-Bus.

4

Comprendi i parametri principali

• --privileged — richiesto per l'accesso all'hardware

• --net=host — richiesto per il rilevamento in LAN e MQTT

• -v ~/cubeos-data:/data — conserva i tuoi dati dopo i riavvii del contenitore

• --device /dev/ttyUSB0:/dev/ttyUSB0 — inoltra un dongle Zigbee

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — abilita l'accesso a D-Bus per le funzionalità supportate

4. Accedi a CUBE OS

1

Verifica che il contenitore sia in esecuzione

docker ps

Lo stato del contenitore dovrebbe mostrare In esecuzione.

2

Apri l'interfaccia web

Apri un browser sulla stessa rete e visita uno di questi indirizzi:

• http://<HOST_IP>/

• http://cube.local

Sostituisci <HOST_IP> con l'indirizzo IP dell'host Linux.

3

Usa in seguito il breve indirizzo locale

Dopo la configurazione, puoi trovare il breve ID nella pagina delle impostazioni.

Puoi quindi usare cube-{short-id}.local per identificare questa istanza di CUBE OS sulla tua LAN.

5. Aggiorna CUBE OS

La distribuzione Docker non supporta gli aggiornamenti OTA dall'interfaccia web.

Per aggiornare manualmente:

docker stop cubeos
docker rm cubeos
docker pull ghcr.io/ewelinkcube/cube-os:latest

docker run -d \
  --name cubeos \
  --privileged \
  --net=host \
  -v ~/cubeos-data:/data \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
  ghcr.io/ewelinkcube/cube-os:latest

I tuoi dati rimangono in ~/cubeos-data, quindi dispositivi, scene e impostazioni rimangono dopo l'aggiornamento.

6. Limitazioni

A causa dell'isolamento del contenitore, queste funzionalità non sono disponibili nelle distribuzioni Docker:

• Componenti aggiuntivi — non è possibile installare o gestire componenti aggiuntivi

• Altoparlante Bluetooth — il passthrough Bluetooth non è supportato

• Aggiornamento di sistema — gli aggiornamenti OTA nell'interfaccia web sono disabilitati

• Riavvio / Spegnimento — i controlli di alimentazione a livello di sistema non sono disponibili

7. Nota su Raspberry Pi

Se esegui Docker su un Raspberry Pi, assicurati che la dimensione della pagina sia 4096:

getconf PAGE_SIZE

# Se il risultato non è 4096, aggiungi questa riga e riavvia
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot