WebODM via Docker — Guia de Instalação e Configuração

Cobertura: Linux (Ubuntu/Debian/Mint) · macOS · Windows 10/11
Método: Docker + Docker Compose (todas as plataformas)
Versão de referência: WebODM ≥ 2.x · Docker Engine ≥ 24 · Docker Compose v2

Sumário

O que é o WebODM?
Requisitos de Hardware
Requisitos de Software
Instalação no Linux (Ubuntu / Debian / Linux Mint)
Instalação no macOS
Instalação no Windows 10/11
Configuração Inicial do WebODM (todas as plataformas)
Opções de Configuração Avançada
Uso de GPU (NVIDIA)
Gerenciamento de Dados e Volumes
Atualização do WebODM
Portabilidade entre Sistemas Operacionais
Solução de Problemas Comuns
Referências

1. O que é o WebODM?

WebODM é uma plataforma de código aberto para processamento fotogramétrico de imagens aéreas (drones, aerofotogrametria), construída sobre o motor ODM (OpenDroneMap). Permite gerar:

Nuvens de pontos (LAS, PLY)
Modelos Digitais de Superfície (DSM) e de Terreno (DTM)
Ortomosaicos georreferenciados (GeoTIFF)
Modelos 3D texturizados (OBJ, GLB)
Relatórios de qualidade

A implantação via Docker isola todas as dependências do sistema operacional hospedeiro, tornando a instalação reproduzível e multiplataforma.

2. Requisitos de Hardware

Mínimo (projetos pequenos — até ~200 imagens)

Componente	Especificação
CPU	4 núcleos, 64-bit
RAM	8 GB
Armazenamento	20 GB livres (SSD preferível)
GPU	Não obrigatória

Grande escala (1000+ imagens)

Componente	Especificação
CPU	16+ núcleos
RAM	64–128 GB
Armazenamento	500 GB+ NVMe
GPU	NVIDIA RTX 3080/4080 ou superior (12+ GB VRAM)

Regra prática: O ODM utiliza aproximadamente 1 GB de RAM por 100 imagens em resolução padrão. Projetos com --pc-quality ultra podem consumir 3–4× mais.

3. Requisitos de Software

Comuns a todas as plataformas

Software	Versão mínima	Finalidade
Docker Engine / Docker Desktop	24.x	Runtime dos contêineres
Docker Compose	v2.x (plugin `compose`)	Orquestração dos serviços
Git	2.x	Clonar o repositório WebODM

Específicos por plataforma

Plataforma	Pré-requisito extra
Linux	Kernel ≥ 4.15; `curl`, `git` via gerenciador de pacotes
macOS	macOS 12 Monterey ou superior; Apple Silicon ou Intel
Windows	Windows 10 21H2 / Windows 11; WSL 2 habilitado; Hyper-V ativo

4. Instalação no Linux (Ubuntu / Debian / Linux Mint)

4.1 Pré-requisitos do sistema

# Atualizar o sistema
sudo apt update && sudo apt upgrade -y

# Instalar dependências básicas
sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    git \
    lsb-release \
    software-properties-common

4.2 Instalar o Docker Engine

# Adicionar a chave GPG oficial do Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Adicionar o repositório Docker
# ATENÇÃO: no Linux Mint, substitua $(lsb_release -cs) pelo codinome Ubuntu base
# Mint 21.x → ubuntu jammy | Mint 22.x → ubuntu noble
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$UBUNTU_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker Engine e o plugin Compose
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin

Linux Mint — atenção especial: a variável $(lsb_release -cs) retorna o codinome do Mint (ex.: virginia), não o do Ubuntu base. Use $(. /etc/os-release && echo "$UBUNTU_CODENAME") como mostrado acima, ou substitua manualmente pelo codinome Ubuntu correto.

4.3 Configurar o Docker para uso sem `sudo`

# Adicionar o usuário atual ao grupo docker
sudo usermod -aG docker $USER

# Aplicar a mudança sem reiniciar
newgrp docker

# Verificar se o Docker está funcionando
docker run --rm hello-world

4.4 Verificar instalação

docker --version
# Exemplo de saída: Docker version 27.x.x, build ...

docker compose version
# Exemplo de saída: Docker Compose version v2.x.x

4.5 Clonar e iniciar o WebODM

# Clonar o repositório oficial
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input --depth=1
cd WebODM

# Iniciar o WebODM (primeira execução faz o pull das imagens automaticamente)
./webodm.sh start

O script webodm.sh é o ponto de entrada principal no Linux/macOS. Ele utiliza internamente docker compose.

4.6 Acessar a interface web

Abra o navegador em: http://localhost:8000

Na primeira execução, crie o usuário administrador quando solicitado.

5. Instalação no macOS

5.1 Pré-requisitos do sistema

macOS 12 Monterey ou superior (Intel ou Apple Silicon M1/M2/M3)
Xcode Command Line Tools (necessário para Git):

xcode-select --install

5.2 Instalar o Docker Desktop para macOS

Acesse https://www.docker.com/products/docker-desktop/
Baixe a versão adequada ao seu chip:
Apple Silicon (M1/M2/M3): Docker Desktop for Mac with Apple Silicon
Intel: Docker Desktop for Mac with Intel chip
Abra o .dmg baixado e arraste o Docker.app para a pasta Aplicativos
Inicie o Docker Desktop e aguarde o ícone da baleia aparecer na barra de menus
Aceite o contrato de licença quando solicitado

5.3 Configurar recursos do Docker Desktop

O Docker Desktop no macOS roda em uma VM Linux. É essencial alocar recursos suficientes:

Abra Docker Desktop → Settings (⚙️) → Resources
Configure:

Recurso	Mínimo	Recomendado
CPUs	4	8 ou mais
Memory	8 GB	16–32 GB
Swap	2 GB	4 GB
Disk image size	60 GB	100+ GB

Clique em Apply & Restart

5.4 Instalar o Git (se necessário)

O Git já vem disponível após instalar o Xcode Command Line Tools. Verifique:

git --version

Alternativamente, instale via Homebrew:

# Instalar Homebrew (caso não tenha)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar Git
brew install git

5.5 Verificar instalação do Docker

docker --version
docker compose version

5.6 Clonar e iniciar o WebODM

# Clonar o repositório
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input --depth=1
cd WebODM

# Iniciar (mesmos comandos do Linux)
./webodm.sh start

Apple Silicon (M1/M2/M3): As imagens Docker do WebODM são compiladas para linux/amd64. O Docker Desktop gerencia a emulação via Rosetta 2 automaticamente. O processamento será funcional, porém ligeiramente mais lento que em hardware nativo Intel em alguns cenários.

5.7 Acessar a interface web

Abra o navegador em: http://localhost:8000

6. Instalação no Windows 10/11

6.1 Pré-requisitos do sistema

Windows 10 versão 21H2 (build 19044) ou superior, ou Windows 11
Arquitetura: 64-bit (x86_64)
BIOS/UEFI: Virtualização habilitada (Intel VT-x ou AMD-V)

6.2 Habilitar WSL 2 (Windows Subsystem for Linux)

O Docker Desktop no Windows requer o WSL 2 como backend. Execute o PowerShell como Administrador:

# Habilitar WSL e a plataforma de Máquina Virtual
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Reiniciar o sistema
Restart-Computer

Após reiniciar, abra novamente o PowerShell como Administrador:

# Definir WSL 2 como versão padrão
wsl --set-default-version 2

# Verificar versão do WSL
wsl --version

Se for solicitada a atualização do kernel do WSL, baixe e instale em:
https://aka.ms/wsl2kernel

Instalar uma distribuição Linux para WSL 2 (recomendado)

# Instalar Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

Será solicitada a criação de um usuário e senha para o ubuntu.

O WSL 2 não é estritamente obrigatório para executar o WebODM (o Docker Desktop pode usar Hyper-V), mas é fortemente recomendado para melhor desempenho de I/O e compatibilidade com scripts shell.

6.3 Instalar o Docker Desktop para Windows

Acesse https://www.docker.com/products/docker-desktop/
Baixe o instalador Docker Desktop Installer.exe
Execute o instalador e marque:
✅ Use WSL 2 instead of Hyper-V (recomendado)
✅ Add shortcut to desktop
Aguarde a instalação e reinicie quando solicitado
Inicie o Docker Desktop e aceite o contrato de licença
Não é necesário criar uma conta no Docker. Pode pular essa etapa.

6.4 Configurar recursos do Docker Desktop (WSL 2)

Ao usar o backend WSL 2, o Docker Desktop exibe a seguinte mensagem na aba Resources → Advanced:

"You are using the WSL 2 backend, so resource limits are managed by Windows. You can configure limits on the memory, CPU, and swap size allocated to WSL 2 in a .wslconfig file."

Isso significa que os controles de CPU, memória e swap não estão disponíveis dentro do Docker Desktop — eles devem ser definidos diretamente no arquivo .wslconfig do Windows.

6.4.1 Criar ou editar o arquivo `.wslconfig`

O arquivo .wslconfig fica na pasta do seu perfil de usuário Windows (%USERPROFILE%), que normalmente é C:\Users\<seu_usuario>\.

Opção A — Via Bloco de Notas (mais simples):

Abra o PowerShell e execute:

notepad "$env:USERPROFILE\.wslconfig"

O Bloco de Notas perguntará se deseja criar o arquivo caso ele não exista. Confirme e cole o conteúdo abaixo.

Opção B — Via PowerShell (linha de comando):

# Criar o arquivo diretamente com configurações recomendadas
# ATENÇÃO: este comando sobrescreve o arquivo se ele já existir
$config = @"
[wsl2]
memory=16GB
processors=8
swap=4GB
swapFile=%USERPROFILE%\AppData\Local\Temp\wsl-swap.vhdx
"@

$config | Out-File -FilePath "$env:USERPROFILE\.wslconfig" -Encoding utf8

Opção C — Via VS Code ou outro editor:

# Abrir no VS Code
code "$env:USERPROFILE\.wslconfig"

# Abrir com o editor padrão de texto
Invoke-Item "$env:USERPROFILE\.wslconfig"

6.4.2 Conteúdo do arquivo `.wslconfig`

Exemplo completo com as configurações mais úteis para o WebODM:

[wsl2]
# Máximo de memória RAM disponível para o WSL 2 (e portanto para o Docker)
# Ajuste conforme a RAM total da sua máquina
memory=16GB

# Número de núcleos de CPU disponíveis para o WSL 2
processors=8

# Tamanho do arquivo de swap (memória virtual)
swap=4GB

# Localização do arquivo de swap (opcional; padrão: %USERPROFILE%\AppData\Local\Temp\)
swapFile=%USERPROFILE%\AppData\Local\Temp\wsl-swap.vhdx

# Desativa a compressão de memória (pode melhorar performance em workloads pesados)
pageReporting=true

# Habilita suporte a GPU via WSLg (necessário para aceleração NVIDIA/CUDA)
# gpuSupport=true

Referência de valores recomendados por quantidade de RAM instalada:

RAM do Windows	`memory=` sugerido	`processors=` sugerido
16 GB	8GB–10GB	metade dos núcleos físicos
32 GB	16GB–24GB	metade ou mais dos núcleos
64 GB	32GB–48GB	igual ao número de núcleos físicos

Boa prática: deixe ao menos 4 GB reservados para o Windows funcionar em paralelo. Alocar 100% da RAM para o WSL 2 pode deixar o sistema lento ou instável.

6.4.3 Aplicar as configurações

Após salvar o .wslconfig, é necessário reiniciar o WSL 2 e o Docker Desktop:

# Encerrar todas as instâncias WSL 2 em execução
wsl --shutdown

# Aguardar alguns segundos e verificar se o WSL reiniciou corretamente
wsl --status

Em seguida, reabra o Docker Desktop (ou aguarde ele reiniciar automaticamente) e confirme os limites aplicados:

# Dentro de um terminal WSL 2 (Ubuntu), verificar memória disponível
wsl -e free -h

# Verificar CPUs disponíveis
wsl -e nproc

6.4.4 Ativar integração do Docker com a distribuição Linux

Independente do .wslconfig, ainda é necessário habilitar a integração do Docker Desktop com a distribuição Ubuntu instalada:

Abra Docker Desktop → Settings (⚙️) → Resources → WSL Integration
Ative o toggle ao lado da distribuição Ubuntu-24.04 (ou a que você instalou)
Clique em Apply & Restart

Após isso, os comandos docker e docker compose estarão disponíveis dentro do terminal WSL 2.

6.5 Instalar o Git para Windows

Baixe e instale em https://git-scm.com/download/win

Durante a instalação, selecione: - Git Bash como terminal padrão - Checkout as-is, commit Unix-style line endings (importante para scripts shell)

6.6 Verificar instalação

Abra o Git Bash ou o PowerShell:

docker --version
docker compose version
git --version

6.7 Clonar e iniciar o WebODM

Abra o Git Bash (não o CMD ou PowerShell puro) para garantir compatibilidade com os scripts shell:

# Clonar o repositório com tratamento correto de quebras de linha
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input --depth=1
cd WebODM

# Iniciar o WebODM
bash webodm.sh start

ATENÇÃO — quebras de linha: No Windows, o Git pode converter automaticamente LF para CRLF nos scripts .sh, corrompendo-os. A flag --config core.autocrlf=input no clone previne isso. Se o script falhar com erros de \r, execute: bash sed -i 's/\r$//' webodm.sh

6.8 Alternativa via WSL 2 (recomendada para usuários avançados)

Para evitar problemas com quebras de linha e obter melhor performance, é possível operar inteiramente de dentro do WSL 2:

# Dentro do terminal WSL 2 (Ubuntu)
sudo apt update && sudo apt install -y git curl

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

O Docker Desktop se integra automaticamente ao WSL 2 e os comandos docker e docker compose ficam disponíveis dentro do ambiente Linux.

6.9 Acessar a interface web

Abra o navegador em: http://localhost:8000

7. Configuração Inicial do WebODM (todas as plataformas)

7.1 Primeiro acesso

Acesse http://localhost:8000
Clique em "Register" para criar o usuário administrador
Defina usuário, senha e e-mail
Faça login com as credenciais criadas

7.2 Estrutura dos serviços Docker

O WebODM é composto pelos seguintes contêineres:

Serviço	Função
`webapp`	Interface web Django (frontend + API)
`worker`	Processamento assíncrono de tarefas (Celery)
`db`	Banco de dados PostgreSQL
`broker`	Fila de mensagens Redis
`node-odm-1`	Nó de processamento ODM

Verifique se todos estão rodando:

docker compose ps

7.3 Criar um projeto e processar imagens

Na interface web, clique em "Add Project"
Dê um nome ao projeto e clique em "Create Project"
Clique em "Add Task" → selecione as imagens (arraste ou navegue)
Configure as opções de processamento (ou use os padrões)
Clique em "Start Processing"

8. Opções de Configuração Avançada

8.1 Arquivo de configuração `.env`

Crie um arquivo .env na raiz do repositório WebODM para sobrescrever as configurações padrão:

# Porta da interface web (padrão: 8000)
WO_PORT=8000

# Hostname público (para acesso externo)
WO_HOST=0.0.0.0

# Número máximo de tarefas simultâneas por nó ODM
WO_MAX_IMAGES=0

# Ativar modo de debug (não use em produção)
WO_DEBUG=false

# Configuração do banco de dados (PostgreSQL)
DB_HOST=db
DB_USER=webodm
DB_PASS=webodm
DB_NAME=webodm

# Pasta de dados persistentes
WO_MEDIA_DIR=/webodm/app/media

8.2 Múltiplos nós ODM (processamento paralelo)

Para processar múltiplos projetos simultaneamente, adicione nós extras editando o docker-compose.yml ou usando as flags do script:

# Iniciar com 2 nós ODM
./webodm.sh start --with-nodeodm 2

# Verificar nós ativos na interface web:
# Configurações → Processing Nodes

8.3 Nó ODM remoto (NodeODM standalone)

Para delegar processamento a outra máquina na rede:

# Na máquina remota, iniciar o NodeODM
docker run -d -p 3000:3000 opendronemap/nodeodm

# Na interface WebODM:
# Configurações → Processing Nodes → Add Node
# Host: <IP da máquina remota>
# Port: 3000

8.4 Controle do serviço

# Iniciar
./webodm.sh start

# Parar (mantém dados)
./webodm.sh stop

# Reiniciar
./webodm.sh restart

# Ver logs em tempo real
./webodm.sh logs

# Atualizar para a versão mais recente
./webodm.sh update

# Remover completamente (ATENÇÃO: apaga todos os dados)
./webodm.sh down --remove-orphans -v

8.5 Alterar a porta padrão (8000)

A porta 8000 pode já estar em uso por outro contêiner ou serviço (Jupyter, Portainer, outras aplicações Django, etc.). Há três formas de mudar a porta — via flag de linha de comando, via variável de ambiente ou via docker-compose.yml — todas compatíveis com Linux, macOS e Windows.

Passo 1 — Identificar o conflito

Antes de alterar a porta, confirme que ela está de fato em uso e descubra qual processo a ocupa.

Linux:

# Mostra processo e PID usando a porta 8000
sudo ss -tlnp | grep ':8000'

# Alternativa com lsof
sudo lsof -i TCP:8000 -sTCP:LISTEN

# Descobrir qual contêiner Docker ocupa a porta
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep 8000

macOS:

# Mostrar processo usando a porta 8000
lsof -i TCP:8000 -sTCP:LISTEN

# Alternativa
netstat -an | grep 8000

# Descobrir qual contêiner Docker ocupa a porta
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep 8000

Windows — PowerShell:

# Listar conexões na porta 8000
netstat -ano | findstr ":8000"

# Identificar o processo pelo PID retornado acima (substitua <PID>)
Get-Process -Id <PID>

# Descobrir qual contêiner Docker ocupa a porta
docker ps --format "table {{.Names}}\t{{.Ports}}" | Select-String "8000"

Windows — Git Bash / WSL 2:

# Dentro do WSL 2, verificar portas em uso
sudo ss -tlnp | grep ':8000'

# Contêineres Docker
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep 8000

Passo 2 — Escolher e aplicar a nova porta

Escolha uma das três abordagens abaixo. A Opção A é a mais rápida; a Opção B é recomendada para uso permanente; a Opção C oferece controle máximo.

Opção A — Flag `--port` no script de inicialização (Linux e macOS)

Passe a nova porta diretamente ao iniciar. Não requer nenhuma alteração de arquivo:

# Parar a instância atual (se estiver rodando)
./webodm.sh stop

# Iniciar na nova porta (exemplo: 8080)
./webodm.sh start --port 8080

Windows (Git Bash): use bash webodm.sh start --port 8080
Windows (PowerShell): esta abordagem não é suportada diretamente; use a Opção B ou C.

Acesse em: http://localhost:8080

Opção B — Variável de ambiente `WO_PORT` no arquivo `.env` (todas as plataformas)

Esta é a abordagem recomendada para uso permanente. O arquivo .env na raiz do repositório é lido automaticamente pelo docker compose.

Linux / macOS (terminal):

cd WebODM

# Parar o serviço
./webodm.sh stop

# Criar ou editar o arquivo .env
# Se o arquivo já existir, edite apenas a linha WO_PORT
echo "WO_PORT=8080" >> .env

# Verificar o resultado
grep WO_PORT .env

Se o arquivo .env já existir com WO_PORT definido, edite o valor em vez de duplicar a linha:

# Substituir o valor existente (substitui qualquer porta definida)
sed -i 's/^WO_PORT=.*/WO_PORT=8080/' .env

macOS — edição via editor de texto:

# Abrir no editor padrão
open -e .env

# Ou usar o nano
nano .env

Windows — PowerShell:

cd WebODM

# Parar o serviço
bash webodm.sh stop

# Criar ou atualizar o arquivo .env com a nova porta
# Se o arquivo não existir, cria; se existir, adiciona a linha
Add-Content -Path ".env" -Value "WO_PORT=8080"

# Se WO_PORT já existir no .env, substitua o valor:
(Get-Content .env) -replace '^WO_PORT=.*', 'WO_PORT=8080' | Set-Content .env

Windows — Git Bash / WSL 2:

# Mesmos comandos do Linux
sed -i 's/^WO_PORT=.*/WO_PORT=8080/' .env
# Ou, se a variável ainda não existe no arquivo:
echo "WO_PORT=8080" >> .env

Após editar o .env, inicie normalmente:

./webodm.sh start        # Linux / macOS
bash webodm.sh start     # Windows Git Bash

Acesse em: http://localhost:8080

Opção C — Editar diretamente o `docker-compose.yml` (todas as plataformas)

Use esta opção quando precisar de controle total sobre o mapeamento de portas, por exemplo para expor o WebODM em uma interface de rede específica ou alterar também a porta interna.

Abra o arquivo docker-compose.yml na raiz do repositório e localize a seção do serviço webapp:

# ANTES (configuração original)
services:
  webapp:
    ports:
      - "${WO_PORT:-8000}:8000"

Substitua pelo mapeamento desejado:

# DEPOIS — porta do host alterada para 8080
services:
  webapp:
    ports:
      - "8080:8000"

A sintaxe é "PORTA_DO_HOST:PORTA_DO_CONTÊINER". A porta interna do contêiner (8000) não deve ser alterada; mude apenas a porta do host (lado esquerdo).

Para restringir o acesso a uma interface de rede específica (útil em servidores):

# Aceitar conexões apenas via localhost (mais seguro)
ports:
  - "127.0.0.1:8080:8000"

Após editar o arquivo, aplique as mudanças:

# Linux / macOS
./webodm.sh stop
./webodm.sh start

# Windows (Git Bash)
bash webodm.sh stop
bash webodm.sh start

# OU diretamente com docker compose (qualquer plataforma)
docker compose down
docker compose up -d

Acesse em: http://localhost:8080

Passo 3 — Verificar se a nova porta está ativa

Após reiniciar, confirme que o contêiner está publicando a porta correta:

# Listar portas de todos os contêineres WebODM
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep webodm

# Saída esperada (exemplo com porta 8080):
# webodm-webapp-1   0.0.0.0:8080->8000/tcp

Resumo rápido por plataforma

Plataforma	Método mais rápido	Método permanente recomendado
Linux	`./webodm.sh start --port 8080`	`WO_PORT=8080` no `.env`
macOS	`./webodm.sh start --port 8080`	`WO_PORT=8080` no `.env`
Windows (Git Bash)	`bash webodm.sh start --port 8080`	`WO_PORT=8080` no `.env`
Windows (PowerShell)	Editar `docker-compose.yml`	`WO_PORT=8080` no `.env` via `Set-Content`
Windows (WSL 2)	`./webodm.sh start --port 8080`	`WO_PORT=8080` no `.env`

9. Uso de GPU (NVIDIA)

O suporte a GPU acelera etapas específicas do pipeline ODM (correspondência de features, MVS).

9.1 Linux — NVIDIA Container Toolkit

# Adicionar repositório NVIDIA
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
    sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update
sudo apt install -y nvidia-container-toolkit

# Configurar o Docker para usar o runtime NVIDIA
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verificar
docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi

9.2 Ativar GPU no WebODM

# Iniciar WebODM com suporte a GPU
./webodm.sh start --gpu

9.3 Windows e macOS

Windows: O NVIDIA Container Toolkit funciona via WSL 2. Instale os drivers NVIDIA para Windows normalmente; o suporte a CUDA dentro do WSL é automático nas versões recentes.
macOS: Não há suporte a GPU NVIDIA (Apple descontinuou o suporte a eGPU NVIDIA e os chips M-series usam Metal, não CUDA). O processamento ocorre apenas em CPU.

10. Gerenciamento de Dados e Volumes

10.1 Localização dos dados

Os dados do WebODM são armazenados em volumes Docker nomeados, não em pastas do host por padrão. Para listar:

docker volume ls | grep webodm

10.2 Mapear dados para uma pasta do host

Edite o docker-compose.yml para montar um diretório local:

services:
  webapp:
    volumes:
      - /caminho/local/webodm-data:/webodm/app/media

Isso facilita backup e acesso direto aos arquivos gerados.

10.3 Backup dos dados

# Parar os serviços antes do backup
./webodm.sh stop

# Fazer backup do volume do banco de dados
docker run --rm \
  -v webodm_dbdata:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/webodm-db-backup.tar.gz /data

# Reiniciar
./webodm.sh start

10.4 Verificar espaço em disco

Projetos fotogramétricos geram grandes volumes de dados intermediários e finais. Monitore regularmente:

# Verificar uso de disco dos volumes Docker
docker system df -v

# Limpar imagens e contêineres não utilizados (não remove volumes com dados)
docker system prune

11. Atualização do WebODM

cd WebODM

# Atualizar via script (recomendado)
./webodm.sh update

# OU manualmente:
git pull origin master
docker compose pull
./webodm.sh restart

Antes de atualizar: faça backup dos dados conforme descrito na seção 10.3. Atualizações de versão principal (ex.: 1.x → 2.x) podem exigir migração do banco de dados.

12. Portabilidade entre Sistemas Operacionais

Esta seção explica como mover uma instalação completa do WebODM de uma máquina para outra, independentemente do sistema operacional de origem e destino. O processo preserva todos os projetos, tarefas, resultados processados e configurações.

O que precisa ser transferido?

Uma instalação WebODM em execução possui três componentes que precisam ser carregados no novo sistema:

Componente	O que contém	Tamanho típico
Imagens Docker	O software WebODM, ODM e dependências	5–15 GB
Volume de banco de dados (`webodm_dbdata`)	Usuários, projetos, tarefas e metadados	Pequeno (< 1 GB)
Volume de mídia (`webodm_media`)	Imagens enviadas e resultados gerados	Grande (varia por projeto)

Se o repositório WebODM já estiver clonado no destino e a internet estiver disponível, as imagens Docker podem ser baixadas novamente com ./webodm.sh start em vez de transferidas. Nesse caso, basta exportar apenas os dois volumes.

12.1 Preparação na máquina de origem

Execute estes passos no computador que já tem o WebODM funcionando.

Passo 1 — Parar o WebODM:

# Linux / macOS
cd WebODM
./webodm.sh stop

# Windows (Git Bash)
cd WebODM
bash webodm.sh stop

Passo 2 — Criar a pasta de exportação:

# Linux / macOS
mkdir -p ~/webodm-export

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:USERPROFILE\webodm-export" -Force

# Windows (Git Bash)
mkdir -p ~/webodm-export

12.2 Exportar as imagens Docker

Este passo empacota todas as imagens necessárias em um único arquivo .tar. Pode ser pulado se o destino tiver acesso à internet e você preferir baixar as imagens novamente.

# Listar as imagens do WebODM em uso
docker images | grep -E "webodm|nodeodm|opendronemap"

# Exportar todas as imagens WebODM em um único arquivo
# Linux / macOS
docker save \
  opendronemap/webodm_webapp \
  opendronemap/webodm_db \
  opendronemap/nodeodm \
  redis \
  | gzip > ~/webodm-export/webodm-images.tar.gz

# Windows (PowerShell) — salvar sem compressão (gzip não disponível nativamente)
docker save `
  opendronemap/webodm_webapp `
  opendronemap/webodm_db `
  opendronemap/nodeodm `
  redis `
  -o "$env:USERPROFILE\webodm-export\webodm-images.tar"

# Windows (Git Bash / WSL 2) — com compressão
docker save \
  opendronemap/webodm_webapp \
  opendronemap/webodm_db \
  opendronemap/nodeodm \
  redis \
  | gzip > ~/webodm-export/webodm-images.tar.gz

Verificar os nomes exatos das imagens: os nomes acima são os padrão. Se você tiver versões customizadas, confirme com docker images e ajuste os nomes no comando.

12.3 Exportar os volumes de dados

Os volumes contêm os dados que realmente importam: projetos, resultados e configurações do banco.

Volume do banco de dados (webodm_dbdata):

# Linux / macOS
docker run --rm \
  -v webodm_dbdata:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  tar czf /backup/webodm-db.tar.gz -C /dados .

# Windows (PowerShell)
docker run --rm `
  -v webodm_dbdata:/dados `
  -v "${env:USERPROFILE}\webodm-export:/backup" `
  ubuntu `
  tar czf /backup/webodm-db.tar.gz -C /dados .

# Windows (Git Bash / WSL 2)
docker run --rm \
  -v webodm_dbdata:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  tar czf /backup/webodm-db.tar.gz -C /dados .

Volume de mídia e projetos (webodm_media):

# Linux / macOS
docker run --rm \
  -v webodm_media:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  tar czf /backup/webodm-media.tar.gz -C /dados .

# Windows (PowerShell)
docker run --rm `
  -v webodm_media:/dados `
  -v "${env:USERPROFILE}\webodm-export:/backup" `
  ubuntu `
  tar czf /backup/webodm-media.tar.gz -C /dados .

# Windows (Git Bash / WSL 2)
docker run --rm \
  -v webodm_media:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  tar czf /backup/webodm-media.tar.gz -C /dados .

Verificar o conteúdo exportado:

# Linux / macOS / Git Bash
ls -lh ~/webodm-export/

# Windows (PowerShell)
Get-ChildItem "$env:USERPROFILE\webodm-export" | Select-Object Name, Length

Você deverá ver os três arquivos:

webodm-images.tar.gz   (ou .tar no Windows sem compressão)
webodm-db.tar.gz
webodm-media.tar.gz

12.4 Transferir os arquivos para o destino

Escolha o método mais adequado ao seu contexto:

Via HD externo / pendrive — copie a pasta webodm-export inteira para o dispositivo e conecte no computador destino.

Via rede local (SCP — Linux/macOS):

# Enviar do Linux/macOS para outro computador na rede
scp -r ~/webodm-export usuario@192.168.1.XX:~/webodm-export

Via rede local (PowerShell — Windows origem para Windows destino):

# Copiar via compartilhamento de rede
Copy-Item -Path "$env:USERPROFILE\webodm-export" `
          -Destination "\\192.168.1.XX\Users\usuario\webodm-export" `
          -Recurse

Via rsync (Linux/macOS, mais robusto para arquivos grandes):

rsync -avh --progress ~/webodm-export/ usuario@192.168.1.XX:~/webodm-export/

Para transferências de dezenas de gigabytes, a rede local com rsync ou cabo USB é significativamente mais rápida que qualquer serviço de nuvem.

12.5 Restaurar na máquina de destino

Execute estes passos no computador de destino, que deve ter o Docker instalado (seções 4, 5 ou 6 conforme o sistema operacional) e o repositório WebODM clonado.

Passo 1 — Clonar o repositório WebODM (se ainda não tiver):

# Linux / macOS / Git Bash
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input --depth=1
cd WebODM

Passo 2 — Carregar as imagens Docker:

# Linux / macOS / Git Bash (arquivo .tar.gz)
docker load < ~/webodm-export/webodm-images.tar.gz

# Windows (PowerShell) — arquivo .tar sem compressão
docker load -i "$env:USERPROFILE\webodm-export\webodm-images.tar"

# Windows (Git Bash / WSL 2) — arquivo .tar.gz
docker load < ~/webodm-export/webodm-images.tar.gz

Se preferir baixar as imagens da internet em vez de importar o .tar.gz, pule este passo — elas serão obtidas automaticamente na primeira execução.

Passo 3 — Criar os volumes e restaurar os dados:

# Criar os volumes (Docker cria automaticamente se não existirem)
docker volume create webodm_dbdata
docker volume create webodm_media

Restaurar o banco de dados:

# Linux / macOS / Git Bash
docker run --rm \
  -v webodm_dbdata:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  bash -c "cd /dados && tar xzf /backup/webodm-db.tar.gz"

# Windows (PowerShell)
docker run --rm `
  -v webodm_dbdata:/dados `
  -v "${env:USERPROFILE}\webodm-export:/backup" `
  ubuntu `
  bash -c "cd /dados && tar xzf /backup/webodm-db.tar.gz"

Restaurar a mídia e os projetos:

# Linux / macOS / Git Bash
docker run --rm \
  -v webodm_media:/dados \
  -v ~/webodm-export:/backup \
  ubuntu \
  bash -c "cd /dados && tar xzf /backup/webodm-media.tar.gz"

# Windows (PowerShell)
docker run --rm `
  -v webodm_media:/dados `
  -v "${env:USERPROFILE}\webodm-export:/backup" `
  ubuntu `
  bash -c "cd /dados && tar xzf /backup/webodm-media.tar.gz"

Passo 4 — Iniciar o WebODM:

# Linux / macOS
./webodm.sh start

# Windows (Git Bash)
bash webodm.sh start

Acesse http://localhost:8000 e faça login com as mesmas credenciais da máquina de origem. Todos os projetos e resultados estarão disponíveis.

12.6 Verificar a migração

# Confirmar que todos os contêineres estão em execução
docker compose ps

# Verificar que os volumes foram restaurados corretamente
docker run --rm -v webodm_dbdata:/dados ubuntu du -sh /dados
docker run --rm -v webodm_media:/dados ubuntu du -sh /dados

Na interface web, navegue até Projects e confirme que os projetos aparecem com seus resultados intactos.

12.7 Resumo visual do processo

ORIGEM                                    DESTINO
──────────────────────────────────────    ──────────────────────────────────────
1. ./webodm.sh stop                       5. git clone WebODM (se necessário)
2. docker save → webodm-images.tar.gz     6. docker load < webodm-images.tar.gz
3. tar volumes → webodm-db.tar.gz              (ou pular: baixa da internet)
                  webodm-media.tar.gz     7. docker volume create + tar restore
                        │                 8. ./webodm.sh start
                        └──── transferir ──▶  http://localhost:8000 ✓
                          (USB/SCP/rsync)

13. Solução de Problemas Comuns

WebODM não inicia / porta 8000 em uso

Consulte a seção 8.5 para o procedimento completo de diagnóstico e troca de porta em cada sistema operacional.

Tarefa trava em "Running" indefinidamente

# Ver logs do worker
docker compose logs -f worker

# Ver logs do nó ODM
docker compose logs -f node-odm-1

# Reiniciar apenas o worker
docker compose restart worker

Erro "No space left on device"

# Limpar artefatos Docker não utilizados
docker system prune -a --volumes

# Verificar espaço disponível
df -h

Erro de permissão nos scripts (Linux/macOS)

chmod +x webodm.sh

WSL 2 não encontra o Docker (Windows)

Abra o Docker Desktop → Settings → Resources → WSL Integration
Ative a integração para a distribuição Ubuntu
Clique em Apply & Restart
Abra um novo terminal WSL e teste: docker ps

Imagens com `\r` (CRLF) no Windows

# Corrigir quebras de linha no script principal
sed -i 's/\r$//' webodm.sh

# Ou clonar novamente com a flag correta
git clone https://github.com/OpenDroneMap/WebODM --config core.autocrlf=input --depth=1

Pouca RAM disponível para o ODM

No docker-compose.yml, adicione limites explícitos ao nó ODM:

node-odm-1:
  deploy:
    resources:
      limits:
        memory: 28g
      reservations:
        memory: 8g

14. Referências

Recurso	URL
Repositório oficial WebODM	https://github.com/OpenDroneMap/WebODM
Documentação OpenDroneMap	https://docs.opendronemap.org
Docker Engine (Linux)	https://docs.docker.com/engine/install/
Docker Desktop (macOS/Windows)	https://www.docker.com/products/docker-desktop/
NVIDIA Container Toolkit	https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/
WSL 2 (Microsoft)	https://learn.microsoft.com/pt-br/windows/wsl/install
Fórum da comunidade ODM	https://community.opendronemap.org

Documentação gerada em abril de 2026. Verifique o repositório oficial para mudanças após esta data.

Componente	Especificação
CPU	8+ núcleos (Intel Core i7/i9, AMD Ryzen 7/9, Xeon)
RAM	32 GB ou mais
Armazenamento	100 GB+ em SSD NVMe
GPU	NVIDIA com 6 GB+ VRAM (para aceleração CUDA)

WebODM via Docker — Guia de Instalação e Configuração

Sumário

1. O que é o WebODM?

2. Requisitos de Hardware

Mínimo (projetos pequenos — até ~200 imagens)

Recomendado (projetos médios — 200–1000 imagens)

Grande escala (1000+ imagens)

3. Requisitos de Software

Comuns a todas as plataformas

Específicos por plataforma

4. Instalação no Linux (Ubuntu / Debian / Linux Mint)

4.1 Pré-requisitos do sistema

4.2 Instalar o Docker Engine

4.3 Configurar o Docker para uso sem sudo

4.4 Verificar instalação

4.5 Clonar e iniciar o WebODM

4.6 Acessar a interface web

5. Instalação no macOS

5.1 Pré-requisitos do sistema

5.2 Instalar o Docker Desktop para macOS

5.3 Configurar recursos do Docker Desktop

5.4 Instalar o Git (se necessário)

5.5 Verificar instalação do Docker

5.6 Clonar e iniciar o WebODM

5.7 Acessar a interface web

6. Instalação no Windows 10/11

6.1 Pré-requisitos do sistema

6.2 Habilitar WSL 2 (Windows Subsystem for Linux)

Instalar uma distribuição Linux para WSL 2 (recomendado)

6.3 Instalar o Docker Desktop para Windows

6.4 Configurar recursos do Docker Desktop (WSL 2)

6.4.1 Criar ou editar o arquivo .wslconfig

6.4.2 Conteúdo do arquivo .wslconfig

6.4.3 Aplicar as configurações

6.4.4 Ativar integração do Docker com a distribuição Linux

6.5 Instalar o Git para Windows

6.6 Verificar instalação

6.7 Clonar e iniciar o WebODM

6.8 Alternativa via WSL 2 (recomendada para usuários avançados)

6.9 Acessar a interface web

7. Configuração Inicial do WebODM (todas as plataformas)

7.1 Primeiro acesso

7.2 Estrutura dos serviços Docker

7.3 Criar um projeto e processar imagens

8. Opções de Configuração Avançada

8.1 Arquivo de configuração .env

8.2 Múltiplos nós ODM (processamento paralelo)

8.3 Nó ODM remoto (NodeODM standalone)

8.4 Controle do serviço

8.5 Alterar a porta padrão (8000)

Passo 1 — Identificar o conflito

Passo 2 — Escolher e aplicar a nova porta

Opção A — Flag --port no script de inicialização (Linux e macOS)

Opção B — Variável de ambiente WO_PORT no arquivo .env (todas as plataformas)

Opção C — Editar diretamente o docker-compose.yml (todas as plataformas)

Passo 3 — Verificar se a nova porta está ativa

Resumo rápido por plataforma

9. Uso de GPU (NVIDIA)

9.1 Linux — NVIDIA Container Toolkit

9.2 Ativar GPU no WebODM

9.3 Windows e macOS

10. Gerenciamento de Dados e Volumes

10.1 Localização dos dados

10.2 Mapear dados para uma pasta do host

10.3 Backup dos dados

10.4 Verificar espaço em disco

11. Atualização do WebODM

12. Portabilidade entre Sistemas Operacionais

O que precisa ser transferido?

12.1 Preparação na máquina de origem

12.2 Exportar as imagens Docker

12.3 Exportar os volumes de dados

12.4 Transferir os arquivos para o destino

12.5 Restaurar na máquina de destino

12.6 Verificar a migração

12.7 Resumo visual do processo

13. Solução de Problemas Comuns

WebODM não inicia / porta 8000 em uso

Tarefa trava em "Running" indefinidamente

Erro "No space left on device"

4.3 Configurar o Docker para uso sem `sudo`

6.4.1 Criar ou editar o arquivo `.wslconfig`

6.4.2 Conteúdo do arquivo `.wslconfig`

8.1 Arquivo de configuração `.env`

Opção A — Flag `--port` no script de inicialização (Linux e macOS)

Opção B — Variável de ambiente `WO_PORT` no arquivo `.env` (todas as plataformas)

Opção C — Editar diretamente o `docker-compose.yml` (todas as plataformas)

Imagens com `\r` (CRLF) no Windows