Installation and setup

This page covers installing RiskScape using a zip file.

Warning

If RiskScape is already installed on your system, then follow the Upgrading RiskScape instructions instead.

Note

RiskScape is also available via a docker image. Please get in contact with the project team if you want to use docker.

Prerequisites

RiskScape currently requires a Java Runtime Environment of at least version 17 to run.

For instructions on installing Java on many Operating Systems refer to How to download and install pre-built Java packages.

After installation, use a terminal, Windows Command Prompt or PowerShell and run:

java -version

The result of this command should be similar to:

java version "17.x.y"

Java(TM) SE Runtime Environment (build 17...)

Java HotSpot(TM) 64-Bit Server VM (build 17..., mixed mode)

Tip

You may need administrator privileges to install Java, or for elsewhere in this guide where systems settings are edited. Check with your System Administrator if you hit a permissions problem.

Download the latest version of the RiskScape software

Download the latest RiskScape zip file.

Extract the downloaded zip file to your file system, e.g.

C:\RiskScape Windows
/opt/riskscape Linux or Mac

Tip

You can install RiskScape into any directory location you want, but make sure you adjust the file-path you use in subsequent instructions on this page. We recommend you do not extract the riskscape.zip directly into C:\Users\%USERNAME%\ as this may make upgrading RiskScape more complicated.

RiskScape can now be tested by entering the following commands (adjust the paths if necessary):

C:\RiskScape\riskscape\bin\riskscape.bat --help Windows
/opt/riskscape/riskscape/bin/riskscape --help Linux or Mac

Tip

If RiskScape fails to start with an error message like:

Exception in thread "main" java.lang.UnsupportedClassVersionError: nz/org/riskscape/engine/cli/Main has been compiled by a more recent version of the Java Runtime

Then your version of Java does not meet the minimum required standard. Refer to Prerequisites

Make the RiskScape command available

The next step is to make RiskScape easier to run, so that we don’t have to specify the full executable path every time.

Update PATH

For convenience, you can add the riskscape/bin directory to the system’s path, by editing the PATH environment variable. Instead of typing out the full executable path, you can now just run riskscape.

Below are examples of how to set the PATH on various operating systems.

Tip

Refer here for more details on how to edit the PATH environment variable for various operating systems.

Linux and Mac

For example, a Linux user would do this by adding the following to their ~/.bashrc file:

export "PATH=$PATH:/opt/riskscape/riskscape/bin/"

Adjust the /opt/riskscape/ location accordingly to match your installation directory.

Mac users would update the ~/.zshrc file here instead of ~/.bashrc. You may need to create the ~/.zshrc file if it does not exist, e.g. touch ~/.zshrc.

Once you have saved the ~/.bashrc (or ~/.zshrc) file, open a new terminal and enter riskscape --help to check that the riskscape command is now visible on your PATH.

Windows

Windows users can use this PATH approach too, instead of creating a shortcut script. To set the PATH on Windows:

Click on the Windows Start menu.
Start typing ‘command’.
Right click on the ‘Command Prompt’ application and select ‘Run as Administrator’.
Enter the following command to change the PATH permanently.
```
setx PATH "%PATH%;C:\RiskScape\riskscape\bin"
```

Tip

If you do not have administrator privileges, or would prefer not to permanently alter your PATH setting, you can create a small Desktop shortcut script instead.

Windows shortcut (alternative)

Instead of permanently changing your PATH setting, you can add a small Desktop shortcut script that will do this each time you want to use RiskScape.

Top-level project directory

As part of this script, we will open a command prompt in a top-level directory that will contain all our RiskScape project directories. Our example will use C:\RiskScape_Projects\ for our top-level directory.

Under this top-level directory, you can use separate sub-directories as needed to organize your RiskScape models (e.g. C:\RiskScape_Projects\getting-started\).

A RiskScape project is the ‘working directory’ where you will run RiskScape commands from. It should contain a plain-text project.ini file, which you can create and edit in Notepad.

Tip

Running the shortcut will open the command prompt in the C:\RiskScape_Projects\ directory. From there, you then use the cd DIRECTORY_NAME command to change to the sub-directory you want to work on. Alternatively, you could hard-code a specific project directory directly into your shortcut, e.g. cd C:\RiskScape_Projects\getting-started.

The following examples are for either Windows Command Prompt or PowerShell, depending on what you feel more comfortable using.

Windows Command prompt shortcut

To create a Desktop shortcut for running RiskScape from a Windows command prompt:

Create a top-level directory to keep your RiskScape projects in, if needed, e.g. C:\RiskScape_Projects\.
Open Notepad.
Paste in the following. Adjust the first line to match your project directory
and the set PATH line to match your installation directory.
```
cd C:\RiskScape_Projects\

@echo off

set PATH=%PATH%;C:\RiskScape\riskscape\bin

cmd -c
```
Save the file to your desktop as RiskScape Shortcut.bat. Make sure you change ‘Save as type’ to ‘All files’.
Test the shortcut works. Go to your desktop and double-click on it.
A command prompt should open. Type riskscape --help and check it works.

PowerShell shortcut

Alternatively, if you prefer using the PowerShell prompt, to create a Desktop shortcut for RiskScape:

Create a top-level directory to keep your RiskScape projects in, if needed, e.g. C:\RiskScape_Projects\.
Open Notepad.
Paste in the following. Adjust the $env:Path line to match your installation directory.
```
cd C:\RiskScape_Projects\

$env:Path += ';C:\RiskScape\riskscape\bin'

powershell
```
Save the file to your desktop as RiskScape Shortcut.ps1. Make sure you change ‘Save as type’ to ‘All files’.
Test the shortcut works. Go to your desktop, right-click on it and select ‘Run with PowerShell’.
A PowerShell prompt should open. Type riskscape --help and check it works.

Installing a GIS application

We recommend that you have also a GIS application installed on your system that you can use to view GIS data, such as shapefiles and GeoTIFF files. This will help to visualize the RiskScape input and output data.

Common GIS applications include QGIS and ArcGIS.

Note

There are some known interoperability issues with shapefile projections in ArcGIS. If your preferred GIS application is ArcGIS, then refer to Workarounds for ArcGIS for more details.

You can download QGIS from here.

Note

Follow the QGIS instructions carefully. Mac users, pay attention to the note in the QGIS instructions about security rules.

QGIS has a lot of online documentation on how to use it and how to work with GIS data. You should also be able to find many ‘how to’ videos for using QGIS online.