Docker

Una guía para instalar CUBE OS usando Docker en sistemas Linux.

Instala CUBE OS como un contenedor Docker en un host Linux. Este método funciona bien para servidores domésticos, dispositivos NAS y máquinas Linux siempre encendidas.

La implementación de Docker es compatible en Solo Linux.

Si no tienes un host Linux, usa Raspberry Pi o Máquina virtual.

1. Preparación

1

Comprueba la arquitectura del host

CUBE Docker es compatible con estas arquitecturas Linux:

• amd64 (x86_64) — PCs, servidores, NAS Synology y dispositivos similares

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi y otros hosts ARM

2

Comprueba la versión del kernel de Linux

Kernel 4.15 o posterior es necesario.

uname -r

Algunos dispositivos NAS incluyen kernels más antiguos, como 4.4.x. Estos hosts no son compatibles con CUBE Docker. En ese caso, ejecuta CUBE OS en una máquina virtual Linux.

3

Instala Docker Engine

Instala Docker Engine en el host antes de continuar.

Usa la guía oficial de instalación de Docker.

4

Comprueba los puertos necesarios

Asegúrate de que los puertos 80 y 1883 están libres en el host.

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

• 80 — interfaz web de CUBE OS

• 1883 — broker MQTT

Si otro servicio está usando estos puertos, deténlo primero.

5

Prepara un dongle Zigbee si es necesario

Si planeas añadir dispositivos Zigbee, conecta un dongle Zigbee compatible al host.

Los dongles Zigbee probados incluyen:

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Otros listados por el desarrollador @darkxst

Para obtener más información sobre las configuraciones y la compatibilidad de Zigbee, consulte esto guía.

Para más información sobre la compatibilidad con Zigbee, consulta esta guía.

2. Descarga la imagen

1

Descarga la imagen más reciente

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

Puedes reemplazar latest por una etiqueta de versión específica, como 2.10.3. Las versiones disponibles se enumeran en GitHub Releases.

3. Inicia CUBE OS

1

Crea un directorio de datos

mkdir -p ~/cubeos-data

Este directorio almacena tus dispositivos, escenas y ajustes.

2

Comprueba la ruta del dispositivo Zigbee si usas uno(opcional)

Las rutas de dispositivo comunes son:

ls /dev/ttyUSB* /dev/ttyACM*

Usa la ruta correcta en el siguiente comando.

3

Inicia el contenedor

Usa 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

Si no usas Zigbee, elimina --device /dev/ttyUSB0:/dev/ttyUSB0.

Si no usas Matter Hub ni eWeLink Remote, también puedes quitar el montaje de D-Bus.

4

Comprende los parámetros principales

• --privileged — necesario para acceder al hardware

• --net=host — necesario para el descubrimiento en LAN y MQTT

• -v ~/cubeos-data:/data — conserva tus datos tras reiniciar el contenedor

• --device /dev/ttyUSB0:/dev/ttyUSB0 — pasa a través un dongle Zigbee

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — habilita el acceso a D-Bus para las funciones compatibles

4. Accede a CUBE OS

1

Confirma que el contenedor se está ejecutando

docker ps

El estado del contenedor debería mostrar En ejecución.

2

Abre la interfaz web

Abre un navegador en la misma red y visita una de estas direcciones:

• http://<HOST_IP>/

• http://cube.local

Reemplaza <HOST_IP> por la dirección IP del host Linux.

3

Usa más adelante la dirección local corta

Después de la configuración, puedes encontrar el ID corto en la página de ajustes.

Entonces puedes usar cube-{short-id}.local para identificar esta instancia de CUBE OS en tu LAN.

5. Actualiza CUBE OS

La implementación de Docker no admite actualizaciones OTA desde la interfaz web.

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

Tus datos permanecen en ~/cubeos-data, así que los dispositivos, escenas y ajustes permanecen después de la actualización.

6. Limitaciones

Debido al aislamiento del contenedor, estas funciones no están disponibles en las implementaciones con Docker:

• Complementos — no se pueden instalar ni administrar complementos

• Altavoz Bluetooth — no se admite el paso a través de Bluetooth

• Actualización del sistema — las actualizaciones OTA en la interfaz web están desactivadas

• Reinicio / Apagado — los controles de energía a nivel de sistema no están disponibles

7. Nota sobre Raspberry Pi

Si ejecutas Docker en una Raspberry Pi, asegúrate de que el tamaño de página sea 4096:

getconf PAGE_SIZE

# Si el resultado no es 4096, añade esta línea y reinicia
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot