> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/english-pt-br/primeiros-passos/quickstart/docker.md). # Docker 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. {% hint style="info" %} A implantação via Docker é compatível com **Somente Linux**. Se você não tiver um host Linux, use [Raspberry Pi](/english-pt-br/primeiros-passos/quickstart/raspberry-pi.md) ou [Máquina virtual](/english-pt-br/primeiros-passos/quickstart/maquina-virtual/virtualbox.md). {% endhint %} ### 1. Preparação {% stepper %} {% step %} **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 {% endstep %} {% step %} **Verifique a versão do kernel Linux** Kernel `4.15` ou posterior é necessário. ```bash uname -r ``` {% hint style="warning" %} 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. {% endhint %} {% endstep %} {% step %} **Instale o Docker Engine** Instale o Docker Engine no host antes de continuar. Use o [guia oficial de instalação do Docker](https://docs.docker.com/engine/install/). {% endstep %} {% step %} **Verifique as portas necessárias** Certifique-se de que as portas `80` e `1883` estejam livres no host. ```bash 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. {% endstep %} {% step %} **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](https://darkxst.github.io/silabs-firmware-builder/) pelo desenvolvedor @darkxst {% hint style="info" %} Para mais informações sobre configurações e compatibilidade do Zigbee, por favor consulte isto [guia](/english-pt-br/verificacao-de-compatibilidade/zigbee.md). {% endhint %} Para mais informações sobre suporte a Zigbee, consulte [este guia](/english-pt-br/verificacao-de-compatibilidade/zigbee.md). {% endstep %} {% endstepper %} ### 2. Baixe a imagem {% stepper %} {% step %} **Baixe a imagem mais recente** ```bash docker pull ghcr.io/ewelinkcube/cube-os:latest ```
{% hint style="info" %} 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](https://github.com/eWeLinkCUBE/CUBE-OS/releases/). {% endhint %} {% endstep %} {% endstepper %} ### 3. Inicie o CUBE OS {% stepper %} {% step %} **Crie um diretório de dados** ```bash mkdir -p ~/cubeos-data ``` Este diretório armazena seus dispositivos, cenas e configurações. {% endstep %} {% step %} **Verifique o caminho do dispositivo Zigbee, se usar um (opcional)** Os caminhos de dispositivo mais comuns são: ```bash ls /dev/ttyUSB* /dev/ttyACM* ``` Use o caminho correto no próximo comando. {% endstep %} {% step %} **Inicie o contêiner** Use este comando como base: ```bash 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 ```
{% hint style="info" %} 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. {% endhint %} {% endstep %} {% step %} **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 {% endstep %} {% endstepper %} ### 4. Acesse o CUBE OS {% stepper %} {% step %} **Confirme que o contêiner está em execução** ```bash docker ps ``` O status do contêiner deve mostrar `Em execução`. {% endstep %} {% step %} **Abra a interface web** Abra um navegador na mesma rede e visite um destes endereços: * `http:///` * Substitua `` pelo endereço IP do host Linux. {% endstep %} {% step %} **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. {% endstep %} {% endstepper %} ### 5. Atualize o CUBE OS A implantação via Docker não oferece suporte a atualizações OTA pela interface web. Para atualizar manualmente: ```bash 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`: ```bash 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 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cube.ewelink.cc/english-pt-br/primeiros-passos/quickstart/docker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.