> 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-it/per-iniziare/quickstart/docker.md). # Docker Installa CUBE OS come contenitore Docker su un host Linux. Questo metodo funziona bene per server domestici, dispositivi NAS e macchine Linux sempre attive. {% hint style="info" %} La distribuzione Docker è supportata su **solo Linux**. Se non hai un host Linux, usa [Raspberry Pi](/english-it/per-iniziare/quickstart/raspberry-pi.md) o [Macchina virtuale](/english-it/per-iniziare/quickstart/macchina-virtuale/virtualbox.md). {% endhint %} ### 1. Preparazione {% stepper %} {% step %} **Controlla l'architettura dell'host** CUBE Docker supporta queste architetture Linux: * **amd64** (`x86_64`) — PC, server, NAS Synology e dispositivi simili * **arm64** (`aarch64`) — Raspberry Pi 4/5, Orange Pi e altri host ARM {% endstep %} {% step %} **Controlla la versione del kernel Linux** Kernel `4.15` o successivo è richiesto. ```bash uname -r ``` {% hint style="warning" %} Alcuni dispositivi NAS vengono forniti con kernel più vecchi, come `4.4.x`. Questi host non sono compatibili con CUBE Docker. In tal caso, esegui invece CUBE OS in una macchina virtuale Linux. {% endhint %} {% endstep %} {% step %} **Installa Docker Engine** Installa Docker Engine sull'host prima di continuare. Usa la [guida ufficiale all'installazione di Docker](https://docs.docker.com/engine/install/). {% endstep %} {% step %} **Verifica le porte richieste** Assicurati che le porte `80` e `1883` siano libere sull'host. ```bash sudo lsof -i :80 sudo lsof -i :1883 ``` * **80** — interfaccia web di CUBE OS * **1883** — broker MQTT Se un altro servizio sta usando queste porte, arrestalo prima. {% endstep %} {% step %} **Prepara un dongle Zigbee se necessario** Se prevedi di aggiungere dispositivi Zigbee, collega all'host un dongle Zigbee compatibile. I dongle Zigbee testati includono: > SONOFF ZBDongle-MAX\ > SONOFF ZBDongle-PMG24\ > SONOFF ZBDongle-LMG21\ > SONOFF ZBDongle-E\ > SONOFF ZBDongle-P\ > [Altri elencati](https://darkxst.github.io/silabs-firmware-builder/) dal sviluppatore @darkxst {% hint style="info" %} Per ulteriori informazioni sulle configurazioni e la compatibilità Zigbee, consultare questo [guida](/english-it/verifica-compatibilita/zigbee.md). {% endhint %} Per ulteriori informazioni sul supporto Zigbee, fai riferimento a [questa guida](/english-it/verifica-compatibilita/zigbee.md). {% endstep %} {% endstepper %} ### 2. Scarica l'immagine {% stepper %} {% step %} **Scarica l'ultima immagine** ```bash docker pull ghcr.io/ewelinkcube/cube-os:latest ```
{% hint style="info" %} Puoi sostituire `latest` con un tag di versione specifico, come `2.10.3`. Le versioni disponibili sono elencate su [GitHub Releases](https://github.com/eWeLinkCUBE/CUBE-OS/releases/). {% endhint %} {% endstep %} {% endstepper %} ### 3. Avvia CUBE OS {% stepper %} {% step %} **Crea una directory dati** ```bash mkdir -p ~/cubeos-data ``` Questa directory memorizza i tuoi dispositivi, scene e impostazioni. {% endstep %} {% step %} **Controlla il percorso del dispositivo Zigbee se ne usi uno (facoltativo)** I percorsi comuni dei dispositivi sono: ```bash ls /dev/ttyUSB* /dev/ttyACM* ``` Usa il percorso corretto nel comando successivo. {% endstep %} {% step %} **Avvia il contenitore** Usa questo comando come 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 non usi Zigbee, rimuovi `--device /dev/ttyUSB0:/dev/ttyUSB0`. Se non usi Matter Hub o eWeLink Remote, puoi anche rimuovere il mount di D-Bus. {% endhint %} {% endstep %} {% step %} **Comprendi i parametri principali** * `--privileged` — richiesto per l'accesso all'hardware * `--net=host` — richiesto per il rilevamento in LAN e MQTT * `-v ~/cubeos-data:/data` — conserva i tuoi dati dopo i riavvii del contenitore * `--device /dev/ttyUSB0:/dev/ttyUSB0` — inoltra un dongle Zigbee * `-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro` — abilita l'accesso a D-Bus per le funzionalità supportate {% endstep %} {% endstepper %} ### 4. Accedi a CUBE OS {% stepper %} {% step %} **Verifica che il contenitore sia in esecuzione** ```bash docker ps ``` Lo stato del contenitore dovrebbe mostrare `In esecuzione`. {% endstep %} {% step %} **Apri l'interfaccia web** Apri un browser sulla stessa rete e visita uno di questi indirizzi: * `http:///` * Sostituisci `` con l'indirizzo IP dell'host Linux. {% endstep %} {% step %} **Usa in seguito il breve indirizzo locale** Dopo la configurazione, puoi trovare il breve ID nella pagina delle impostazioni. Puoi quindi usare `cube-{short-id}.local` per identificare questa istanza di CUBE OS sulla tua LAN. {% endstep %} {% endstepper %} ### 5. Aggiorna CUBE OS La distribuzione Docker non supporta gli aggiornamenti OTA dall'interfaccia web. Per aggiornare 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 ``` I tuoi dati rimangono in `~/cubeos-data`, quindi dispositivi, scene e impostazioni rimangono dopo l'aggiornamento. ### 6. Limitazioni A causa dell'isolamento del contenitore, queste funzionalità non sono disponibili nelle distribuzioni Docker: * **Componenti aggiuntivi** — non è possibile installare o gestire componenti aggiuntivi * **Altoparlante Bluetooth** — il passthrough Bluetooth non è supportato * **Aggiornamento di sistema** — gli aggiornamenti OTA nell'interfaccia web sono disabilitati * **Riavvio / Spegnimento** — i controlli di alimentazione a livello di sistema non sono disponibili ### 7. Nota su Raspberry Pi Se esegui Docker su un Raspberry Pi, assicurati che la dimensione della pagina sia `4096`: ```bash getconf PAGE_SIZE # Se il risultato non è 4096, aggiungi questa riga e riavvia 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-it/per-iniziare/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.