Installation

Did You Know?

You can skip the installation and run WebODM from webodm.net, which supports the development of the software ❤ Try it for free.

Installation on your machine

If you’re on Windows or macOS, the easiest way is to download the installer for your platform.

If you’re on Linux, you need to use docker (see below).

Docker

To install WebODM on your machine with docker, first install:

• Git
• Docker

Windows and macOS users should install Docker Desktop. Then:

1. Give Docker enough CPUs (default 2) and RAM (>4Gb, 16Gb better but leave some for the operating system) by going to Settings -- Resources
2. Select where on your hard drive you want virtual hard drives to reside (Settings -- Resources -- Advanced).

Then:

• Open Git Bash (Windows), or from the command line (Mac / Linux / WSL), type:

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

• If you face any issues at the last step on Linux, make sure your user is part of the docker group:

sudo usermod -aG docker $USER
exit
(restart shell by logging out and then back-in)
./webodm.sh start

🎉 Congratulations! You should be up and running. Open a browser to http://localhost:8000

To stop WebODM press CTRL+C or run:

./webodm.sh stop

To update WebODM to the latest version use:

./webodm.sh update

Installation on other machines

Google Compute, Amazon AWS

These steps are for Google Cloud, but can also be used for Amazon AWS, and other cloud platforms with small modifications:

1. Launch a Google Cloud instance of Ubuntu LTS.
2. Open the SSH terminal - Google offers SSH via the website.
3. Run sudo apt-get update
4. Run sudo apt-get upgrade
5. Install docker-compose. Do not install via apt for 24.04 onward.
6. Run sudo apt-get install python-pip
7. Run git clone https://github.com/WebODM/WebODM --config core.autocrlf=input --depth 1
8. cd WebODM (Linux is case sensitive)
9. sudo ./webodm.sh start
10. You now can access WebODM via the public IP address for your Google instance. Remember the default port of 8000.
11. Check that your instance’s firewall is allowing inbound TCP connections on port 8000! If you forget this step you will not be able to connect to WebODM.
12. Open http://publicip:8000

To setup the firewall on Google Cloud, open the instance, on the middle of the instance settings page find NIC0. Open it, and then add the TCP Port 8000 for ingress, and egress on the firewall.

NAS (Qnap)

If you use Lightning or another processor node the requirements for WebODM are low enough for it to run on a fairly low power device such as a NAS. Testing has been done on a Qnap-TS264 with 32Gb of RAM (Celeron N5095 processor) To install WebODM on a Qnap NAS:

1. Enable ssh access to the NAS in control panel
2. Install git. This might be easily achieved using the qgit qkpg
3. Follow the “Installation with Docker” instructions above.
4. A new “webodm” application should appear in container station along with four individual containers for the app.
5. WebODM should be available at port 8000 of the NAS.
6. Setup a Lightning account online and configure it within “processing nodes”. It’s also possible to setup a more powerful computer to run processing tasks instead of Lightning.

Advanced Setups

Manage Processing Nodes

WebODM can be linked to one or more processing nodes that speak the NodeODM API, such as NodeODM, NodeMICMAC, ClusterODM and Lightning. The default configuration includes a “node-odm-1” processing node which runs on the same machine as WebODM, just to help you get started. As you become more familiar with WebODM, you might want to install processing nodes on separate machines.

Adding more processing nodes will allow you to run multiple jobs in parallel.

You can also setup a ClusterODM node to run a single task across multiple machines with distributed split-merge and process dozen of thousands of images more quickly, with less memory.

If you don’t need the default “node-odm-1” node, simply pass --default-nodes 0 flag when starting WebODM:

./webodm.sh restart --default-nodes 0.

Then from the web interface simply manually remove the “node-odm-1” node.

Enable SSL

WebODM has the ability to automatically request and install a SSL certificate via Let’s Encrypt, or you can manually specify your own key/certificate pair.

• Setup your DNS record (webodm.myorg.com —> IP of server).
• Make sure port 80 and 443 are open.
• Run the following:

./webodm.sh restart --ssl --hostname webodm.myorg.com

That’s it! The certificate will automatically renew when needed.

If you want to specify your own key/certificate pair, simply pass the --ssl-key and --ssl-cert option to ./webodm.sh. See ./webodm.sh --help for more information.

Note! You cannot pass an IP address to the hostname parameter! You need a DNS record setup.

Enable MicMac

WebODM can use MicMac as a processing engine via NodeMICMAC. To add MicMac, simply run:

./webodm.sh restart --with-micmac

This will create a “node-micmac-1” processing node on the same machine running WebODM. Please note that NodeMICMAC is in active development and is currently experimental. If you find issues, please report them on the NodeMICMAC repository.

Enable IPv6

Your installation must first have a public IPv6 address. To enable IPv6 on your installation, you need to activate IPv6 in Docker by adding the following to a file located at /etc/docker/daemon.json:

{
  "ipv6": true,
  "fixed-cidr-v6": "fdb4:4d19:7eb5::/64"
}

Restart Docker: systemctl restart docker

To add IPv6, simply run:

./webodm.sh restart --ipv6

Note: When using --ssl mode, you cannot pass an IP address to the hostname parameter; you must set up a DNS AAAA record. Without --ssl mode enabled, access the site at (e.g., http://[2001:0db8:3c4d:0015::1]:8000). The brackets around the IPv6 address are essential! You can add a new NodeODM node in WebODM by specifying an IPv6 address. Don’t forget to include brackets around the address! e.g., [2001:0db8:fd8a:ae80::1]

Common Troubleshooting

Symptoms	Possible Solutions
Run out of memory	Make sure that your Docker environment has enough RAM allocated: MacOS Instructions, Windows Instructions
On Windows, docker-compose fails with Failed to execute the script docker-compose	Make sure you have enabled VT-x virtualization in the BIOS
Cannot access WebODM using Microsoft Edge on Windows 10	Try to tweak your internet properties according to these instructions
Getting a No space left on device error, but hard drive has enough space left	Docker on Windows by default will allocate only 20GB of space to the default docker-machine. You need to increase that amount. See this link and this link
Cannot start WebODM via ./webodm.sh start, error messages are different at each retry	You could be running out of memory. Make sure you have enough RAM available. 2GB should be the recommended minimum, unless you know what you are doing
On Windows, the storage space shown on the WebODM diagnostic page is not the same as what is actually set in Docker’s settings.	From Hyper-V Manager, right-click “DockerDesktopVM”, go to Edit Disk, then choose to expand the disk and match the maximum size to the settings specified in the docker settings. Upon making the changes, restart docker.
On Linux or WSL, Warning: GPU use was requested, but no GPU has been found	Run nvidia-smi (natively) or docker run --rm --gpus all nvidia/cuda:11.2.2-devel-ubuntu20.04 nvidia-smi (docker) to check with NVIDIA driver and NVIDIA Container Toolkit.

Common Administration Tasks

It’s fairly straightforward to manage an installation of WebODM. Here’s a list of common operations you might need to do:

Reset Admin Password

If you forgot the password you picked the first time you logged into WebODM, to reset it just type:

./webodm.sh start && ./webodm.sh resetadminpassword newpass

The password will be reset to newpass. The command will also tell you what username you chose.

Backup and Restore

If you want to move WebODM to another system, you just need to transfer the docker volumes (unless you are storing your files on the file system).

On the old system:

mkdir -v backup
docker run --rm --volume webodm_dbdata:/temp --volume `pwd`/backup:/backup ubuntu tar cvf /backup/dbdata.tar /temp
docker run --rm --volume webodm_appmedia:/temp --volume `pwd`/backup:/backup ubuntu tar cvf /backup/appmedia.tar /temp

Your backup files will be stored in the newly created backup directory. Transfer the backup directory to the new system, then on the new system:

ls backup # --> appmedia.tar  dbdata.tar
./webodm.sh down # Make sure WebODM is down
docker run --rm --volume webodm_dbdata:/temp --volume `pwd`/backup:/backup ubuntu bash -c "rm -fr /temp/* && tar xvf /backup/dbdata.tar"
docker run --rm --volume webodm_appmedia:/temp --volume `pwd`/backup:/backup ubuntu bash -c "rm -fr /temp/* && tar xvf /backup/appmedia.tar"
./webodm.sh start

Update

If you use docker, updating is as simple as running:

./webodm.sh update

Customizing and Extending

Small customizations such as changing the application colors, name, logo, or adding custom CSS/HTML/Javascript can be performed directly from the Customize — Brand/Theme panels within WebODM. No need to fork or change the code.

More advanced customizations can be achieved by writing plugins. This is the preferred way to add new functionality to WebODM since it requires less effort than maintaining a separate fork. The plugin system features server-side signals that can be used to be notified of various events, a ES6/React build system, a dynamic client-side API for adding elements to the UI, a built-in data store, an async task runner, hooks to add menu items and functions to rapidly inject CSS, Javascript and Django views.

To learn more, start from the plugin development guide. It’s also helpful to study the source code of existing plugins.

If a particular hook / signal for your plugin does not yet exist, request it. We are adding hooks and signals as we go.

Hardware Requirements

To run a standalone installation of WebODM (the user interface), including the processing component (NodeODM), we recommend at a minimum:

• 100 GB free disk space
• 16 GB RAM

Don’t expect to process more than a few hundred images with these specifications. To process larger datasets, add more RAM linearly to the number of images you want to process:

Number of Images	RAM or RAM + Swap (GB)
40	4
250	16
500	32
1500	64
2500	128
3500	192
5000	256

Note

These are conservative estimates. A lot of factors influence memory usage, such as image dimensions, flight altitude and processing settings. So you might be able to process more images with less memory than reported above.

A CPU with more cores will speed up processing, but can increase memory usage. GPU acceleration is also supported on Linux and WSL. To make use of your CUDA-compatible graphics card, make sure to pass --gpu when starting WebODM. You need the nvidia-docker installed in this case, see https://github.com/NVIDIA/nvidia-docker and https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker for information on docker/NVIDIA setup.

WebODM runs best on Linux, but works well on Windows and Mac too.

WebODM by itself is just a user interface and does not require many resources. WebODM can be loaded on a machine with just 1 or 2 GB of RAM and work fine without NodeODM. You can use a processing service such as webodm.net or run NodeODM on a separate, more powerful machine.