Docker

A guide to install CUBE OS using Docker on Linux systems.

Install CUBE OS as a Docker container on a Linux host. This method works well for home servers, NAS devices, and always-on Linux machines.

Docker deployment is supported on Linux only.

If you do not have a Linux host, use Raspberry Pi or Virtual Machine.

1. Preparation

1

Check the host architecture

CUBE Docker supports these Linux architectures:

• amd64 (x86_64) — PCs, servers, Synology NAS, and similar devices

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi, and other ARM hosts

2

Check the Linux kernel version

Kernel 4.15 or later is required.

uname -r

Some NAS devices ship with older kernels, such as 4.4.x. These hosts are not compatible with CUBE Docker. In that case, run CUBE OS in a Linux virtual machine instead.

3

Install Docker Engine

Install Docker Engine on the host before you continue.

Use the official Docker installation guide.

4

Check required ports

Make sure ports 80 and 1883 are free on the host.

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

• 80 — CUBE OS web UI

• 1883 — MQTT broker

If another service is using these ports, stop it first.

5

Prepare a Zigbee dongle if needed

If you plan to add Zigbee devices, connect a compatible Zigbee dongle to the host.

Tested Zigbee dongles include:

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Others listed by developer @darkxst

For more information on Zigbee configurations and compatibility, please refer to this guide.

For more information on Zigbee support, refer to this guide.

2. Pull the image

1

Download the latest image

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

You can replace latest with a specific version tag, such as 2.10.3. Available versions are listed on GitHub Releases.

3. Start CUBE OS

1

Create a data directory

mkdir -p ~/cubeos-data

This directory stores your devices, scenes, and settings.

2

Check the Zigbee device path if you use one(optional)

Common device paths are:

ls /dev/ttyUSB* /dev/ttyACM*

Use the correct path in the next command.

3

Start the container

Use this command as a baseline:

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

If you do not use Zigbee, remove --device /dev/ttyUSB0:/dev/ttyUSB0.

If you do not use Matter Hub or eWeLink Remote, you can also remove the D-Bus mount.

4

Understand the main parameters

• --privileged — required for hardware access

• --net=host — required for LAN discovery and MQTT

• -v ~/cubeos-data:/data — keeps your data after container restarts

• --device /dev/ttyUSB0:/dev/ttyUSB0 — passes through a Zigbee dongle

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — enables D-Bus access for supported features

4. Access CUBE OS

1

Confirm that the container is running

docker ps

The container status should show Up.

2

Open the web UI

Open a browser on the same network and visit one of these addresses:

• http://<HOST_IP>/

• http://cube.local

Replace <HOST_IP> with the Linux host IP address.

3

Use the short local address later

After setup, you can find the short ID on the settings page.

You can then use cube-{short-id}.local to identify this CUBE OS instance on your LAN.

5. Update CUBE OS

The Docker deployment does not support OTA updates from the web UI.

To update manually:

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

Your data stays in ~/cubeos-data, so devices, scenes, and settings remain after the update.

6. Limitations

Due to container isolation, these features are not available in Docker deployments:

• Add-ons — cannot install or manage add-ons

• Bluetooth Speaker — Bluetooth passthrough is not supported

• System Update — OTA updates in the web UI are disabled

• Reboot / Shutdown — system-level power controls are unavailable

7. Raspberry Pi note

If you run Docker on a Raspberry Pi, make sure the page size is 4096:

getconf PAGE_SIZE

# If the result is not 4096, add this line and reboot
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot