WebODM e ODM su Windows con Docker Desktop e WSL2

Quando scegliere Docker invece dell'installer#

Su Windows entrambe le linee offrono un installer nativo che non richiede nulla di ciò che leggerai qui: WebODM gratuito da webodm.org, OpenDroneMap Desktop a pagamento da opendronemap.org. Scegli Docker se ti serve almeno una di queste cose: l'accelerazione GPU NVIDIA, che su Windows funziona solo tramite WSL2; l'esposizione in rete con HTTPS; lo spostamento dell'archivio progetti su un disco dedicato; il collegamento a nodi di elaborazione remoti o a un cluster; motori alternativi; oppure vuoi la stessa installazione che userai poi su un server Linux, per imparare una volta sola.

Cosa ottieni con Docker è però diverso per le due linee, ed è bene saperlo prima di iniziare.

I tre strati: virtualizzazione, WSL2, Docker#

Vale la pena capire cosa stai installando, perché la maggior parte dei problemi nasce da uno di questi tre strati. Questa parte vale per entrambe le linee.

Docker esegue i programmi in contenitori (container) Linux. Su Windows, per far girare Linux, serve una macchina virtuale leggera. Il componente che la fornisce è WSL2, Windows Subsystem for Linux versione 2, integrato in Windows. WSL2, a sua volta, funziona solo se il processore espone le istruzioni di virtualizzazione (Intel VT-x o AMD-V) e se queste sono abilitate nel BIOS o UEFI del computer. Docker Desktop, infine, è l'applicazione che installa Docker e lo collega a WSL2.

Quando uno script o un docker run fallisce su Windows, la documentazione di WebODM indica come prima causa proprio la virtualizzazione disabilitata nel BIOS o WSL2 non attivo. Lo stesso vale per le immagini della linea ODM, perché lo strato Docker è lo stesso. Da qui parte la procedura.

Installazione#

Passo 1: abilita la virtualizzazione nel BIOS#

Apri Gestione attività, scheda Prestazioni, voce CPU: in basso a destra trovi "Virtualizzazione: Abilitata" o "Disabilitata". Se è abilitata, passa oltre.

Se è disabilitata, riavvia il computer ed entra nel BIOS o UEFI con il tasto indicato all'avvio (spesso Canc, F2, F10 o F12, dipende dal produttore). Cerca un'opzione chiamata Intel Virtualization Technology, VT-x, AMD-V o SVM Mode, di solito nelle sezioni Advanced, CPU Configuration o Security. Attivala, salva ed esci. Al riavvio, Gestione attività deve mostrare la virtualizzazione abilitata.

Passo 2: attiva WSL2#

Su Windows 11 e su Windows 10 aggiornato, WSL2 si installa da un terminale con privilegi di amministratore con un solo comando, seguito da un riavvio; la procedura, e il comando esatto per la tua versione, sono nella guida di Microsoft. Al termine avrai una distribuzione Linux, in genere Ubuntu, installata e avviabile dal menu Start. Non è necessario configurarla: Docker Desktop la userà come base.

Passo 3: installa Docker Desktop#

Scarica Docker Desktop per Windows dal sito di Docker e installalo. Durante l'installazione, assicurati che sia selezionata l'opzione che usa WSL2 come backend (è la scelta predefinita nelle versioni recenti). Al primo avvio Docker Desktop può chiedere di completare l'installazione di WSL2 o di riavviare: segui le indicazioni.

Quando l'icona di Docker nella barra delle applicazioni indica che il servizio è in esecuzione, sei pronto per il passo più importante.

Passo 4: assegna RAM e disco a Docker Desktop#

Questo passo è quello che gli utenti saltano più spesso, e che causa quasi tutti i fallimenti in elaborazione, con entrambi i motori. Con WSL2, Docker Desktop usa per impostazione predefinita una parte della RAM del computer, e il disco virtuale in cui vivono le immagini e i volumi ha un limite predefinito di 20 GB, indipendente dallo spazio libero del tuo disco fisico.

Apri Docker Desktop, poi Settings e Resources. La documentazione di WebODM chiede almeno 4 GB di RAM assegnati a Docker, e consiglia 16 GB; la documentazione di ODM indica 4 GB come minimo per 100–200 immagini e 16 GB come valore consigliato. Regola il valore in base alla RAM fisica e ai tuoi dataset, seguendo la tabella immagini → RAM della guida sui requisiti: la memoria che conta per il motore è quella assegnata qui, non quella totale del PC. Aumenta anche la dimensione del disco virtuale ben oltre i 20 GB predefiniti, in proporzione ai progetti che elaborerai.

Se la tua versione di Docker Desktop non mostra i cursori di memoria e disco nella sezione Resources, perché con WSL2 le risorse sono gestite dal file di configurazione di WSL, la stessa pagina di impostazioni rimanda alla procedura: si tratta di un file .wslconfig nella tua cartella utente, descritto nella documentazione Microsoft. Applica le modifiche e riavvia Docker Desktop.

Passo 5: installa Git#

Scarica e installa Git per Windows dal sito ufficiale git-scm.com. Durante l'installazione puoi lasciare tutte le impostazioni predefinite. Per la linea WebODM Git serve a scaricare il codice e ad aggiornarlo in seguito; per entrambe le linee ti serve Git Bash, una shell Bash in cui eseguire gli script e i comandi docker. Se scegli la linea ODM e non intendi mai installare WebODM, Git in senso stretto non è indispensabile, ma Git Bash resta la shell più comoda.

Passo 6: scarica e avvia la tua linea#

Da qui le due linee divergono: WebODM si clona da Git e si avvia con uno script; per la linea ODM si scaricano direttamente le immagini Docker. Apri Git Bash (oppure il terminale della tua distribuzione WSL2: entrambi funzionano, purché Docker sia accessibile da lì) e segui il blocco della tua linea.

git clone https://github.com/WebODM/WebODM --config core.autocrlf=input --depth 1
cd WebODM
./webodm.sh start

docker pull opendronemap/odm
docker run -ti --rm -v /home/utente/datasets:/datasets opendronemap/odm --project-path /datasets progetto

docker pull opendronemap/nodeodm
docker run -d -p 3000:3000 opendronemap/nodeodm

Passo 7: apri l'interfaccia#

WebODM / ODXOpenDroneMap / ODM

WebODM / ODX

Apri il browser su http://localhost:8000. Alla prima apertura WebODM chiede di creare l'utente amministratore. Scegli nome utente e password. Controlla poi, nel menu dei nodi di elaborazione, che il nodo locale sia online.

OpenDroneMap / ODM

Con ODM da riga di comando non c'è un'interfaccia: i risultati sono nelle sottocartelle della cartella del progetto (l'elenco delle cartelle di output è su docs.opendronemap.org), pronti per QGIS. Con NodeODM apri il browser sulla porta che hai pubblicato (http://localhost:3000 se hai usato il comando sopra): l'interfaccia web minima permette di caricare immagini, avviare un lavoro e scaricare gli output, senza utenti, progetti né mappa. Non richiede un account.

Gestire l'installazione#

./webodm.sh stop
./webodm.sh update
./webodm.sh start && ./webodm.sh resetadminpassword nuovapassword
./webodm.sh down

./webodm.sh restart --gpu

Docker Desktop deve essere in esecuzione perché i contenitori funzionino, in entrambe le linee. Se al riavvio del PC Docker Desktop non parte da solo, attivane l'avvio automatico nelle impostazioni generali; i contenitori riprenderanno con esso, oppure li riavvii a mano (./webodm.sh start per WebODM, docker start per NodeODM).

Problemi frequenti#

Lo script o docker run si interrompe subito, oppure Docker Desktop non parte. È il caso più comune: virtualizzazione disabilitata nel BIOS oppure WSL2 non attivo. Ripeti i passi 1 e 2. Dopo ogni modifica al BIOS riavvia e verifica in Gestione attività.

Errori strani negli script di WebODM, riferimenti a caratteri \r o "command not found" con nomi corretti. Il repository è stato clonato senza --config core.autocrlf=input. Cancella la cartella e ripeti il clone con il comando esatto del passo 6.

"Out of memory" durante l'elaborazione. La RAM assegnata a Docker Desktop è insufficiente per il numero di immagini. Vale per ODX e per ODM. Aumentala in Settings, Resources, oppure riduci il dataset. La tabella di riferimento è nella guida sui requisiti.

"No space left on device". Il disco virtuale di Docker ha raggiunto il limite predefinito di 20 GB, anche se il tuo disco fisico è quasi vuoto. Aumenta la dimensione in Settings, Resources.

Porta 8000 (o 3000) già occupata. Un altro programma usa la stessa porta. La guida agli errori comuni spiega come individuarlo e come cambiare porta; per NodeODM basta cambiare il primo numero in -p.

ODM da riga di comando non trova le immagini. Il percorso passato a -v non è quello giusto per Git Bash, oppure le foto non sono nella sottocartella images. Controlla il percorso con ls dalla stessa shell prima di lanciare il contenitore.

Ho un'installazione vecchia clonata da OpenDroneMap. Il repository storico oggi reindirizza a quello di WebODM. Punta il repository al nuovo indirizzo e aggiorna: i due comandi sono nella guida su aggiornare e fare backup. Se invece vuoi passare alla linea ODM, la guida Repository, immagini Docker e migrazioni tratta entrambe le direzioni.

Prossimi passi#

• Elabora il primo dataset: Il primo progetto passo passo.
• Confronta i comandi delle due linee su tutte le piattaforme: Installazione a confronto.
• Attiva la scheda video: GPU NVIDIA.
• Tieni l'installazione aggiornata e al sicuro: Aggiornare, fare backup e ripristinare.