XYCarto

Small example of using Docker and Makefile to implement GRASS GIS. This blog is written to be complimentary to the Github repository found here. Included in this post is a more verbose explanation of what is happening in the Github repository. Users can explore the scripts to see the underlying bits that make it each step. The intention is to help simplify the GRASS set-up and execution of processes using GRASS operations.

TL;DR

GitHub repository is here with the method and documents.

Summary

This is a basic example of setting up scripted GRASS process through a Docker image and using a makefile to launch the process. The goal is remove the need to install GRASS on your machine and to fully containerize the process within Docker.

It is assumed that users have a familiarity with Docker, Make, and GRASS.

In short, the repo is built to launch a GRASS environment and call a script with the users GRASS commands. Ideally, users should be able to clone the Github repository, build the Docker locally (or pull it), and run a simple make command calling the primary script to perform the GRASS operations.

Methods in the repository have been tested using Ubuntu and MacOS operating systems.

Important

This method is developed for scripting purposes and not intended for saving data in your GRASS environment. Using this method, each time the script is run the initial operation checks to see if a GRASS environment exists. If so, that environment is destroyed and a new environment is built.

Requirements

make
docker

Methods

If you prefer try out the commands given below, you will need to clone the Git repo:

git clone git@github.com:xycarto/grass-docker-make.git

These are the two primary commands to set-up the GRASS, Docker, Make operations. Users will first need to build a Docker containing the GRASS installation. Inside the makefile are all the necessary components to find the Dockerfile and build the image. I’ve tagged this build with “xycarto” (see the top of the makefile); however, you can name this whatever you choose.

Build GRASS Docker

make docker-local

Run GRASS Script

With the Docker image in place, you can test if the method is working by checking the GRASS version. This make command uses two scripts. First, a script is called to construct the GRASS environment and then, call the script with all your GRASS operations. The second script is launched using:

grass grass/GRASS_ENV/PERMANENT --exec bash grass-script.sh

The —exec indicates the script is run within the GRASS environment giving users access to all the GRASS capabilities.

GRASS needs to run within a designated projection. Included in the make command is a variable to set this. Users can implement any projection here using the EPSG value. The following is building a GRASS environment in New Zealand Transverse Mercator (NZTM), EPSG:2193:

make grass-project proj="2193"

This should output the GRASS version installed in the Docker.

Modifications

Users can implement any GRASS commands and methods in the run-grass.sh script, simply by modifying the file.

How this can be used

File variables can be given to the GRASS process back in the make command and passing this through the run-grass.sh script. For example, say you have a example.tif file you’d like to process in GRASS. Users can add a variable to the make file called tif. It might look like this in the makefile:

grass-project:
$(RUN) bash run-grass.sh $(proj) $(tif)

The call of the command looks like:

make grass-project proj=“2193" tif=example.tif

Now with the makefile modified, you need to pass the variable through to the GRASS processing. First you need to modify the run-grass.sh script to accept the new variable from make. This can be done by adding the following line at the top:

tif=$2

Where $2 means the second argument in the command given. The run-grass.sh script now has the tif path variable. With this, you can now pass the path to the actual GRASS script by modifying the last line like so:

grass grass/GRASS_ENV/PERMANENT --exec bash grass-script.sh $tif

The grass-script.sh can now be modified to accept the tif variable by adding the following line at the top:

tif=$1

Once you get this all set up an running, the real power comes now in a scripted method run a large collection of tifs through a GRASS process.

Let’s say you have 1000 tifs that need to run. You can list these tifs and simply develop a method like the the following:

cat list-of-tifs.txt | xargs -P 1 -t -I % make grass-project proj=“2193" tif=%

This method would sequentially process the tif list through your GRASS process.

Having a hard time following? Please feel free to contact me and I’ll see if I can help.