Building the WindNinja Docker Image

Creating a WindNinja Docker Image

This page describes building and testing the WindNinja Docker image. See Running the WindNinja Docker Image in an HPC Environment, for guidance building and running the Docker image on an HPC cluster.

Get WindNinja Source

Clone the WindNinja source code to your local machine.

git clone https://github.com/firelab/windninja.git 

Install Docker

Install Docker on your system.

sudo apt install docker.io

Build the WindNinja Docker Image

Note: The most up to date dockerfile is found in the master branch here. Additionally, If you do not need OpenFOAM, remove lines 84-100.

Navigate to the source directory and build the docker image. This will build the Docker image with the tag windninja:latest. See Dockerfile for more.

cd ~/src/wind/windninja 
sudo docker build -t windninja:latest .   

After the build is complete, confirm the image is available. It will be listed as windninja.

docker images

Run and Test the WindNinja Docker Image

Note: While the CLI works, the GUI will require additional configuration as it needs access to a display.

Start an interactive container from the Docker image.

docker run -it windninja:latest /bin/bash

Ensure the CLI was built properly. Need to also test that OpenFOAM works with multiple threads.

mkdir /workdir
cd /workdir
WindNinja_cli --help
simpleFoam -help
WindNinja_cli ./test.cfg

Example Configuration File (test.cfg)

### for the momentum solver, need to uncomment out the momentum_flag

num_threads                = 3  ## don't use too many, no more than the number of cores for momentum runs
#momentum_flag             = true
elevation_file             = /opt/src/windninja/data/missoula_valley.tif  # path to /windninja/data in the Docker image
vegetation                 = brush  ## needs commented out if the dem is an lcp file
mesh_choice                = coarse
##mesh_resolution          = 200.0  ## can use instead of mesh_choice
##units_mesh_resolution    = m
initialization_method      = domainAverageInitialization
input_speed                = 5.0
input_speed_units          = mph
input_direction            = 220
input_wind_height          = 20.0
units_input_wind_height    = ft
output_wind_height         = 20.0
units_output_wind_height   = ft
##write_goog_output        = true
write_ascii_output         = true
##write_shapefile_output   = true
##write_pdf_output         = true
##write_vtk_output         = true
output_path                = .  # current directory, can also set it to a desired path in the Docker image

Additional example .cfg files are available in /windninja/data. These can be used for both interactive testing and local execution, but file paths must be updated before use (e.g., to the correct locations within /windninja/data, or to /input and /output when using mounted directories in Docker).

Note: Changes made to files inside the container are not persistent unless the files are stored in a mounted directory.

For more information on using the CLI, see here.

Some Useful Docker Commands

List Docker images:

docker images

Start an interactive shell / run a container:

docker run -it windninja:latest /bin/bash

List running containers (-a shows ALL containers, otherwise only RUNNING containers are shown):

docker ps -a

Remove / kill a specific container

## Stop then remove
docker stop <container_id>
docker rm <container_id>
## or Force remove (stops automatically)
docker rm -f <container_id>

Remove all stopped containers (required for removing Docker images):

docker container prune

Remove a Docker image (must have no containers, even stopped containers):

docker rmi <image_name>

Remove dangling Docker images (untagged intermediate layers, seen when running docker images -a):

docker image prune

Mount a Local Directory (the current directory) to the Docker image at /data at runtime:

docker run -it \
    -v $PWD:/data \
    windninja:latest \
    /bin/bash

Run WindNinja non-interactively using mounted input and output Local Directories:

docker run --rm \
    -v $PWD/input:/input \
    -v $PWD/output:/output \
    -u $(id -u):$(id -g) \
    windninja:latest \
    WindNinja_cli /input/test.cfg

Note: The -u $(id -u):$(id -g) flag ensures that files written to the output directory are owned by your local user rather than root. Alternatively, you can manually adjust ownership after the run using:

sudo chown -R $USER:$USER /path/to/output

Mounted directories /input and /output are used to pass input data into the container and collect outputs on the host system. Always ensure proper ownership to avoid permission issues.