# eWeLink CUBE OS Docker Installation Support is Here! **URL:** \ **Category:** eWeLink CUBE\ **Tags:** ihost, cube, docker\ **Created:** [June 10, 2026, 3:22am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561 "2026-06-10T03:22:09Z")\ **Posts on this page:** 17\ **Page:** 1
**Author:** ![KwayLi99](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/kwayli99/32/7691_2.png) [@KwayLi99](https://forum.ewelink.cc/u/KwayLi99)\ **Post date:** [June 10, 2026, 3:22am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/1 "2026-06-10T03:22:09Z")
Hello Community! In the latest version **CUBE OS 2.10.3** , you can now run CUBE as a Docker container! This opens up new possibilities for deploying CUBE on NAS devices, home servers, and other Linux machines. ## Currently Supported Architectures CUBE Docker currently supports the following architectures **under Linux systems only** : - **amd64** (x86\_64) — regular PCs, servers, Synology NAS, QNAP NAS, etc. - **arm64** (aarch64) — Raspberry Pi 4/5, Orange Pi, Apple Silicon Mac (via Linux VM), etc. > **Note:** Docker images are built for Linux containers. If you’re on Windows or macOS, we highly recommend using the one-click installer. Please check [One-click Installation | eWeLink CUBE](https://cube.ewelink.cc/getting-started/quickstart/one-click-installation). ## Before You Start Make sure **port 80** and **port 1883** are not in use on your host machine: - **Port 80** — CUBE Web UI (HTTP) - **Port 1883** — MQTT (device communication) If these ports are occupied (e.g., by nginx or Apache), you’ll need to stop those services first. ## Quick Start ### 1. Pull the image ```bash docker pull ghcr.io/ewelinkcube/cube-os:2.10.3 ``` ### 2. Start the container ```bash docker run -d \ --name cubeos \ --privileged \ --net=host \ -v /xxx/data:/data \ --device /dev/ttyUSB0:/dev/ttyUSB0 \ -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \ cubeos:2.10.3 ``` Replace `xxx` with the actual directory path on your host where you want CUBE to store its data (e.g., `/home/pi/cubeos-data`). ### Parameter Explained | Parameter | Purpose | | --- | --- | | `--privileged` | Privileged mode — CUBE needs access to host hardware | | `--net=host` | Host networking — required for device discovery and MQTT communication | | `-v /xxx/data:/data` | Mount data directory — replace `xxx` with your actual path; data persists across recreations | | `--device /dev/ttyUSB0` | Pass through Zigbee dongle — only needed if you have Zigbee devices | | `-v .../system_bus_socket:ro` | Mount host D-Bus — required for eWeLink Remote and Matter Hub | ### 3. Verify ```bash docker ps ``` Then open your browser and visit `http://your-device-ip` > ## Important Notes > > Due to Docker’s containerized architecture, some features are **not available** in the Docker version: > > - **Add-ons** — cannot install/manage add-ons (like Node-RED, Z2M, etc.) > - **Bluetooth Speaker** — Bluetooth hardware passthrough is not supported > - **System Update** — cannot update CUBE from the web UI (you need to pull the new image and recreate the container) > - **Reboot / Shutdown** — these system-level controls are not available ## How to Update CUBE OS Since the Docker version doesn’t support OTA updates, you’ll need to update manually when a new version is released. Don’t worry — **your data is safe** as long as you’ve mounted the data volume. ```bash # 1. Stop the old container docker stop cubeos # 2. Pull the new image (replace X.X.X with the new version) docker pull ghcr.io/ewelinkcube/cube-os:X.X.X # 3. Start a new container with the same parameters docker run -d \ --name cubeos \ --privileged \ --net=host \ -v /xxx/data:/data \ --device /dev/ttyUSB0:/dev/ttyUSB0 \ -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \ cubeos:X.X.X ``` > **Note:** Use the same startup parameters as before. Replace `xxx` with your actual data directory path and `X.X.X` with the new version number. Your config, devices, and scenes are stored in the mounted data directory, so they will persist across updates. ## Raspberry Pi Users If you’re using a Raspberry Pi, make sure your page size is set to 4K: ```bash # Check current page size getconf PAGE_SIZE # If it's not 4096, add this line: echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt sudo reboot ``` ## Want Support for More Architectures? We currently support amd64 and arm64 Linux systems. If you’d like us to support other architectures (like **arm32** , etc.), please leave a comment below and let us know what hardware you’re using! ---
**Author:** ![KwayLi99](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/kwayli99/32/7691_2.png) [@KwayLi99](https://forum.ewelink.cc/u/KwayLi99)\ **Post date:** [June 10, 2026, 7:32am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/2 "2026-06-10T07:32:21Z")
---
**Author:** ![KwayLi99](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/kwayli99/32/7691_2.png) [@KwayLi99](https://forum.ewelink.cc/u/KwayLi99)\ **Post date:** [June 10, 2026, 7:32am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/3 "2026-06-10T07:32:29Z")
---
**Author:** ![eerke](https://avatars.discourse-cdn.com/v4/letter/e/eb9ed0/32.png) [@eerke](https://forum.ewelink.cc/u/eerke)\ **Post date:** [June 11, 2026, 8:36am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/4 "2026-06-11T08:36:48Z")
My docker-compose files usually have memory and CPU limits for each docker container. What settings would you recommend? For example I have Jellyfin set to 2GB and 2.0 CPU. I was thinking of getting a RISC V device to play with. Maybe that architecture would be useful. My guess is it’ll be more popular in future. Not sure much has 32bit ARM anymore. ---
**Author:** ![Jojkoba](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/jojkoba/32/8490_2.png) [@Jojkoba](https://forum.ewelink.cc/u/Jojkoba)\ **Post date:** [June 14, 2026, 5:56am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/5 "2026-06-14T05:56:49Z")
Raspberry Pi 4 and 5. ---
**Author:** ![Minnie](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/minnie/32/9791_2.png) [@Minnie](https://forum.ewelink.cc/u/Minnie)\ **Post date:** [June 29, 2026, 5:56am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/6 "2026-06-29T05:56:33Z")
We recommend using the **2C2G** configuration for the Docker version, which should be sufficient for everyday iHost operations. If you find that memory usage is high during later use, you can flexibly increase the allocated memory as needed. ---
**Author:** ![Tamer\_Salah](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/tamer_salah/32/4047_2.png) [@Tamer\_Salah](https://forum.ewelink.cc/u/Tamer_Salah)\ **Post date:** [July 3, 2026, 7:31pm UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/7 "2026-07-03T19:31:48Z")
how about docker compose ? ---
**Author:** ![KwayLi99](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/kwayli99/32/7691_2.png) [@KwayLi99](https://forum.ewelink.cc/u/KwayLi99)\ **Post date:** [July 6, 2026, 7:09am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/8 "2026-07-06T07:09:35Z")
---
**Author:** ![Miao](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/miao/32/11137_2.png) [@Miao](https://forum.ewelink.cc/u/Miao)\ **Post date:** [July 9, 2026, 12:26pm UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/9 "2026-07-09T12:26:28Z")
Hello, are you requesting that we provide an example `docker-compose.yml` file? ---
**Author:** ![eerke](https://avatars.discourse-cdn.com/v4/letter/e/eb9ed0/32.png) [@eerke](https://forum.ewelink.cc/u/eerke)\ **Post date:** [July 13, 2026, 7:11pm UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/10 "2026-07-13T19:11:09Z")
Which formats does your docker work on ARM64, X86 and RISC V? ---
**Author:** ![Miao](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/miao/32/11137_2.png) [@Miao](https://forum.ewelink.cc/u/Miao)\ **Post date:** [July 14, 2026, 12:45pm UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/11 "2026-07-14T12:45:32Z")
Hello, currently the Docker images for eWeLink CUBE OS support two architectures: amd64 (x86\_64) and arm64 (aarch64). They can run on standard PCs, servers, Raspberry Pi 4/5, and other compatible devices. ---
**Author:** ![Tamer\_Salah](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/tamer_salah/32/4047_2.png) [@Tamer\_Salah](https://forum.ewelink.cc/u/Tamer_Salah)\ **Post date:** [July 24, 2026, 12:22pm UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/12 "2026-07-24T12:22:50Z")
yes if possible , also to mention requirements if running at proxmox ---
**Author:** ![Martin66](https://avatars.discourse-cdn.com/v4/letter/m/8797f3/32.png) [@Martin66](https://forum.ewelink.cc/u/Martin66)\ **Post date:** [July 26, 2026, 11:35am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/13 "2026-07-26T11:35:11Z")
Hello, and thank you for the support regarding CubeOs in Docker containers. I encountered the following error in the Docker implementation when using the “Create Backup” function(CubeOs2.12.0): Failed to create backup “”: Error: ENOENT: no such file or directory, open '/data/.dockerd/image/overlay2/repositories.json I created the missing file using the following command, and the backup is now working. echo ‘{“Repositories”:{}}’ \> /data/.dockerd/image/overlay2/repositories.json Please check whether this error was specific to my installation or if it is a general issue with the Docker implementation. Many thanks in advance, Martin I am using Docker on: DEBIAN\_VERSION\_FULL=13.6 Server: Docker Engine - Community Engine: Version: 29.6.2 API version: 1.55 (minimum version 1.40) Go version: go1.26.5 Git commit: 3d80467 Built: Thu Jul 16 16:13:12 2026 OS/Arch: linux/arm64 Experimental: false containerd: Version: v2.2.6 GitCommit: 11ce9d5f3c68c941867e82890e93e815c1304f1b runc: Version: 1.3.6 GitCommit: v1.3.6-0-g491b69ba docker-init: Version: 0.19.0 GitCommit: de40ad0 Log File ./data/.logs/aibridge-recovery/aibridge\_recovery.log [2026-07-26T09:42:20.616Z] [INFO] default - [OperationManager] - Operation 11 is at stage addon, 25.761570727811023% completed. [2026-07-26T09:42:20.619Z] [INFO] default - [BackupManager] - ReleaseVersion ignore mountSDCard… [2026-07-26T09:42:20.622Z] [ERROR] default - [BackupManager] - Failed to create backup br8p4ytjnb\_1785058936995: Error: ENOENT: no such file or directory, open ‘/data/.dockerd/image/overlay2/repositories.json’ at async open (node:internal/fs/promises:633:25) at async Object.readFile (node:internal/fs/promises:1237:14) at async BackupManager.getAddonImageCount (/root/aibridge-recovery/src/extension/backup\_manager.js:1:29193) at async BackupManager.createBackup (/root/aibridge-recovery/src/extension/backup\_manager.js:1:15029) { errno: -2, code: ‘ENOENT’, syscall: ‘open’, path: ‘/data/.dockerd/image/overlay2/repositories.json’ } [2026-07-26T09:42:20.625Z] [INFO] default - [BackupManager] - startAllServiceProcess start… [2026-07-26T09:42:24.516Z] [INFO] default - [BackupManager] - startAllServiceProcess end… [2026-07-26T09:42:24.516Z] [ERROR] default - [OperationManager] - Backup operation createBackup failed: ENOENT: no such file or directory, open ‘/data/.dockerd/image/overlay2/repositories.json’ [2026-07-26T09:42:24.526Z] [INFO] default - [OperationManager] - backup Operation 11 failed. ---
**Author:** ![Ryan\_CraftX](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/ryan_craftx/32/8694_2.png) [@Ryan\_CraftX](https://forum.ewelink.cc/u/Ryan_CraftX)\ **Post date:** [July 28, 2026, 7:50am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/14 "2026-07-28T07:50:06Z")
Thanks for confirming. Below is an example `compose.yaml` based on the Docker command in the original post: ```yaml services: cubeos: image: ghcr.io/ewelinkcube/cube-os:2.12.0 container_name: cubeos privileged: true network_mode: host restart: unless-stopped volumes: - ./data:/data - /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro # Uncomment and adjust this path if a USB Zigbee coordinator is used. # devices: # - /dev/ttyUSB0:/dev/ttyUSB0 ``` Start CUBE OS with: ```bash mkdir -p data docker compose pull docker compose up -d ``` Check the container status and logs with: ```bash docker compose ps docker compose logs -f cubeos ``` Please note: - Ports `80` and `1883` must be available on the host. - Uncomment and adjust the USB device path if a Zigbee coordinator is used. - We recommend approximately 2 CPU cores and 2 GB of available memory as a starting point. ### Regarding Proxmox VE I have not personally used or tested CUBE OS Docker in a Proxmox environment, so I do not want to provide detailed platform-specific instructions that have not been verified. In general, the same Linux Docker requirements apply, including host networking, persistent storage, available ports, and USB passthrough if a Zigbee coordinator is used. If you need any technical guidance, we can investigate the specific requirements further. ---
**Author:** ![Miao](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/miao/32/11137_2.png) [@Miao](https://forum.ewelink.cc/u/Miao)\ **Post date:** [July 28, 2026, 10:46am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/15 "2026-07-28T10:46:10Z")
Hello, thank you for your feedback. We apologize for any inconvenience this may have caused. We have identified the root cause of this issue, and it will be fixed in the **2.13.0 Docker version of Cube OS** , which is scheduled for release in August. ---
**Author:** ![vaczi.zoli](https://avatars.discourse-cdn.com/v4/letter/v/d07c76/32.png) [@vaczi.zoli](https://forum.ewelink.cc/u/vaczi.zoli)\ **Post date:** [September 7, 2026, 6:35am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/16 "2026-09-07T06:35:53Z")
**Bug report: dynamic-security MQTT “Not authorized” on fresh Docker install (amd64)** Running CUBE OS 2.10.3 Docker image ( [Package cube-os · GitHub](http://ghcr.io/ewelinkcube/cube-os:2.10.3) ) on Ubuntu/Xubuntu, amd64, kernel 7.0.0, with `--privileged` and a macvlan network (container has its own LAN IP, ports 80/1883 reachable). On a completely fresh install (empty data dir), the web UI loads but stays stuck on the red “Disconnected. Please check your Internet connection” banner, and the initial password setup / login does nothing. Diagnosis from `/data/.logs/aibridge-api/aibridge_api.log`: - The regular MQTT client connects fine: “connect successfully” / “Connected to MQTT server” / subscribes and receives `cube/supervisor/os/info`. - But the `[dynamic-security-mqtt]` client repeatedly fails: `[ERROR] [dynamic-security-mqtt] MQTT error: Connection refused: Not authorized`. `/data/mosquitto/` contains only `dynamic-security.json` (generated, 1245 bytes), no separate mosquitto log. The error persists after `docker restart`, and also after a full wipe of the data dir + redeploy + restart — so it appears deterministic, not a first-boot race. Network, DNS and core MQTT all work; only the dynamic-security admin client is rejected. Looks like a credential mismatch between the generated `dynamic-security.json` and the password the services use. Could you check the dynamic-security init on amd64 Docker? ---
**Author:** ![Miao](https://dub1.discourse-cdn.com/flex005/user_avatar/forum.ewelink.cc/miao/32/11137_2.png) [@Miao](https://forum.ewelink.cc/u/Miao)\ **Post date:** [September 7, 2026, 11:19am UTC](https://forum.ewelink.cc/t/ewelink-cube-os-docker-installation-support-is-here/208561/17 "2026-09-07T11:19:27Z")
Hello, Could you please follow the steps below to verify whether the issue can be resolved: 1. Please check whether port 1883 is already in use on your host, or if any other MQTT broker is running. If so, please stop it first, as it may cause port conflicts. 2. Delete all files in the host directory that is mounted to the container’s `/data` directory, or mount a completely new host directory instead. 3. We also recommend that you use the latest version of the software, as older versions may be more difficult to troubleshoot.