Docker

Um guia para instalar o CUBE OS usando Docker em sistemas Linux.

Instale o CUBE OS como um contentor Docker num anfitrião Linux. Este método funciona bem para servidores domésticos, dispositivos NAS e máquinas Linux sempre ligadas.

A implementação Docker é suportada em Apenas Linux.

Se não tiver um anfitrião Linux, use Raspberry Pi ou Máquina Virtual.

1. Preparação

1

Verifique a arquitetura do anfitrião

O CUBE Docker suporta estas arquiteturas Linux:

• amd64 (x86_64) — PCs, servidores, Synology NAS e dispositivos semelhantes

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi e outros anfitriões ARM

2

Verifique a versão do kernel Linux

Kernel 4.15 ou posterior é necessário.

uname -r

Alguns dispositivos NAS vêm com kernels mais antigos, como 4.4.x. Estes anfitriões não são compatíveis com o CUBE Docker. Nesse caso, execute o CUBE OS numa máquina virtual Linux em vez disso.

3

Instale o Docker Engine

Instale o Docker Engine no anfitrião antes de continuar.

Use o guia oficial de instalação do Docker.

4

Verifique as portas necessárias

Certifique-se de que as portas 80 e 1883 estão livres no anfitrião.

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

• 80 — interface web do CUBE OS

• 1883 — broker MQTT

Se outro serviço estiver a usar estas portas, pare-o primeiro.

5

Prepare um dongle Zigbee, se necessário

Se pretende adicionar dispositivos Zigbee, ligue um dongle Zigbee compatível ao anfitrião.

Os dongles Zigbee testados incluem:

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Outros listados pelo desenvolvedor @darkxst

Para obter mais informações sobre configurações e compatibilidade do Zigbee, consulte este guia.

Para mais informações sobre suporte Zigbee, consulte este guia.

2. Obtenha a imagem

1

Descarregue a imagem mais recente

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

Pode substituir latest por uma etiqueta de versão específica, como 2.10.3. As versões disponíveis estão listadas em GitHub Releases.

3. Inicie o CUBE OS

1

Crie um diretório de dados

mkdir -p ~/cubeos-data

Este diretório armazena os seus dispositivos, cenários e definições.

2

Verifique o caminho do dispositivo Zigbee, se usar um (opcional)

Os caminhos de dispositivos comuns são:

ls /dev/ttyUSB* /dev/ttyACM*

Use o caminho correto no próximo comando.

3

Inicie o contentor

Use este comando como 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 não usar Zigbee, remova --device /dev/ttyUSB0:/dev/ttyUSB0.

Se não usar Matter Hub ou eWeLink Remote, também pode remover a montagem D-Bus.

4

Compreenda os principais parâmetros

• --privileged — necessário para acesso ao hardware

• --net=host — necessário para descoberta na LAN e MQTT

• -v ~/cubeos-data:/data — mantém os seus dados após reinícios do contentor

• --device /dev/ttyUSB0:/dev/ttyUSB0 — faz a passagem de um dongle Zigbee

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — permite acesso D-Bus para funcionalidades suportadas

4. Aceda ao CUBE OS

1

Confirme que o contentor está em execução

docker ps

O estado do contentor deve mostrar Up.

2

Abra a interface web

Abra um navegador na mesma rede e visite um destes endereços:

• http://<HOST_IP>/

• http://cube.local

Substitua <HOST_IP> pelo endereço IP do anfitrião Linux.

3

Use mais tarde o endereço local curto

Após a configuração, pode encontrar o ID curto na página de definições.

Pode então usar cube-{short-id}.local para identificar esta instância do CUBE OS na sua LAN.

5. Atualize o CUBE OS

A implementação Docker não suporta atualizações OTA a partir da interface web.

Para atualizar 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

Os seus dados permanecem em ~/cubeos-data, por isso os dispositivos, cenários e definições permanecem após a atualização.

6. Limitações

Devido ao isolamento do contentor, estas funcionalidades não estão disponíveis em implementações Docker:

• Complementos — não é possível instalar ou gerir complementos

• Coluna Bluetooth — a passagem de Bluetooth não é suportada

• Atualização do sistema — as atualizações OTA na interface web estão desativadas

• Reiniciar / Desligar — os controlos de energia ao nível do sistema não estão disponíveis

7. Nota sobre Raspberry Pi

Se executar o Docker num Raspberry Pi, certifique-se de que o tamanho da página é 4096:

getconf PAGE_SIZE

# Se o resultado não for 4096, adicione esta linha e reinicie
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot