Docker

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

Instale o CUBE OS como um contêiner Docker em um host Linux. Este método funciona bem para servidores domésticos, dispositivos NAS e máquinas Linux sempre ligadas.

A implantação via Docker é compatível com Somente Linux.

Se você não tiver um host Linux, use Raspberry Pi ou Máquina virtual.

1. Preparação

1

Verifique a arquitetura do host

O CUBE Docker é compatível com estas arquiteturas Linux:

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

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi e outros hosts 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. Esses hosts não são compatíveis com o CUBE Docker. Nesse caso, execute o CUBE OS em uma máquina virtual Linux.

3

Instale o Docker Engine

Instale o Docker Engine no host 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 estejam livres no host.

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

• 80 — interface web do CUBE OS

• 1883 — broker MQTT

Se outro serviço estiver usando essas portas, pare-o primeiro.

5

Prepare um dongle Zigbee, se necessário

Se você planeja adicionar dispositivos Zigbee, conecte um dongle Zigbee compatível ao host.

Entre os dongles Zigbee testados estão:

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

Para mais informações sobre configurações e compatibilidade do Zigbee, por favor consulte isto guia.

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

2. Baixe a imagem

1

Baixe a imagem mais recente

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

Você pode substituir latest por uma tag de versão específica, como 2.10.3. As versões disponíveis estão listadas em Releases do GitHub.

3. Inicie o CUBE OS

1

Crie um diretório de dados

mkdir -p ~/cubeos-data

Este diretório armazena seus dispositivos, cenas e configurações.

2

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

Os caminhos de dispositivo mais comuns são:

ls /dev/ttyUSB* /dev/ttyACM*

Use o caminho correto no próximo comando.

3

Inicie o contêiner

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 você não usar Zigbee, remova --device /dev/ttyUSB0:/dev/ttyUSB0.

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

4

Entenda 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 seus dados após reinicializações do contêiner

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

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — habilita acesso ao D-Bus para recursos compatíveis

4. Acesse o CUBE OS

1

Confirme que o contêiner está em execução

docker ps

O status do contêiner deve mostrar Em execução.

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 host Linux.

3

Use o endereço local curto mais tarde

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

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

5. Atualize o CUBE OS

A implantação via Docker não oferece suporte a atualizações OTA pela 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

Seus dados permanecem em ~/cubeos-data, então os dispositivos, cenas e configurações permanecem após a atualização.

6. Limitações

Devido ao isolamento do contêiner, estes recursos não estão disponíveis em implantações via Docker:

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

• Alto-falante Bluetooth — o passthrough de Bluetooth não é suportado

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

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

7. Observação sobre Raspberry Pi

Se você executar o Docker em um Raspberry Pi, verifique se 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