Building the WindNinja Docker Image

Creating a WindNinja Docker Image

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.