Docker

Un guide pour installer CUBE OS à l’aide de Docker sur les systèmes Linux.

Installez CUBE OS comme conteneur Docker sur un hôte Linux. Cette méthode fonctionne bien pour les serveurs domestiques, les appareils NAS et les machines Linux toujours allumées.

Le déploiement Docker est pris en charge sur Linux uniquement.

Si vous n'avez pas d'hôte Linux, utilisez Raspberry Pi ou Machine virtuelle.

1. Préparation

1

Vérifiez l'architecture de l'hôte

CUBE Docker prend en charge ces architectures Linux :

• amd64 (x86_64) — PC, serveurs, NAS Synology et appareils similaires

• arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi et autres hôtes ARM

2

Vérifiez la version du noyau Linux

Le noyau 4.15 ou version ultérieure est requis.

uname -r

Certains appareils NAS sont livrés avec des noyaux plus anciens, tels que 4.4.x. Ces hôtes ne sont pas compatibles avec CUBE Docker. Dans ce cas, exécutez CUBE OS dans une machine virtuelle Linux à la place.

3

Installez Docker Engine

Installez Docker Engine sur l'hôte avant de continuer.

Utilisez le guide d'installation officiel de Docker.

4

Vérifiez les ports requis

Assurez-vous que les ports 80 et 1883 sont libres sur l'hôte.

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

• 80 — interface web de CUBE OS

• 1883 — broker MQTT

Si un autre service utilise ces ports, arrêtez-le d'abord.

5

Préparez un dongle Zigbee si nécessaire

Si vous prévoyez d'ajouter des appareils Zigbee, connectez un dongle Zigbee compatible à l'hôte.

Les dongles Zigbee testés incluent :

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Autres répertoriés par le développeur @darkxst

Pour plus d'informations sur les configurations et la compatibilité Zigbee, veuillez vous référer à ceci guide.

Pour plus d'informations sur la prise en charge de Zigbee, consultez ce guide.

2. Récupérer l'image

1

Téléchargez la dernière image

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

Vous pouvez remplacer latest par un tag de version spécifique, comme 2.10.3. Les versions disponibles sont listées sur GitHub Releases.

3. Démarrer CUBE OS

1

Créez un répertoire de données

mkdir -p ~/cubeos-data

Ce répertoire stocke vos appareils, scènes et paramètres.

2

Vérifiez le chemin du périphérique Zigbee si vous en utilisez un (facultatif)

Les chemins de périphérique courants sont :

ls /dev/ttyUSB* /dev/ttyACM*

Utilisez le bon chemin dans la commande suivante.

3

Démarrez le conteneur

Utilisez cette commande comme 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 vous n'utilisez pas Zigbee, supprimez --device /dev/ttyUSB0:/dev/ttyUSB0.

Si vous n'utilisez pas Matter Hub ou eWeLink Remote, vous pouvez également supprimer le montage D-Bus.

4

Comprendre les principaux paramètres

• --privileged — requis pour l'accès au matériel

• --net=host — requis pour la découverte sur le réseau local et MQTT

• -v ~/cubeos-data:/data — conserve vos données après les redémarrages du conteneur

• --device /dev/ttyUSB0:/dev/ttyUSB0 — transmet un dongle Zigbee

• -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — permet l'accès D-Bus pour les fonctionnalités prises en charge

4. Accéder à CUBE OS

1

Confirmez que le conteneur est en cours d'exécution

docker ps

L'état du conteneur devrait afficher Up.

2

Ouvrez l'interface web

Ouvrez un navigateur sur le même réseau et rendez-vous à l'une de ces adresses :

• http://<HOST_IP>/

• http://cube.local

Remplacez <HOST_IP> par l'adresse IP de l'hôte Linux.

3

Utilisez plus tard l'adresse locale courte

Après la configuration, vous pouvez trouver l'ID court sur la page des paramètres.

Vous pouvez ensuite utiliser cube-{short-id}.local pour identifier cette instance de CUBE OS sur votre réseau local.

5. Mettre à jour CUBE OS

Le déploiement Docker ne prend pas en charge les mises à jour OTA depuis l'interface web.

Pour mettre à jour manuellement :

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

Vos données restent dans ~/cubeos-data, donc les appareils, scènes et paramètres restent après la mise à jour.

6. Limitations

En raison de l'isolation du conteneur, ces fonctionnalités ne sont pas disponibles dans les déploiements Docker :

• Modules complémentaires — impossible d'installer ou de gérer des modules complémentaires

• Haut-parleur Bluetooth — le transfert Bluetooth n'est pas pris en charge

• Mise à jour du système — les mises à jour OTA dans l'interface web sont désactivées

• Redémarrage / Arrêt — les commandes d'alimentation au niveau système ne sont pas disponibles

7. Remarque pour Raspberry Pi

Si vous exécutez Docker sur un Raspberry Pi, assurez-vous que la taille de page est 4096:

getconf PAGE_SIZE

# Si le résultat n'est pas 4096, ajoutez cette ligne et redémarrez
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot