Riskscape Engine
================

This directory contains the Riskscape source code and build tools.

Riskscape is:

- Java, JDK8 (but we encourage running on JDK17 so we can upgrade when it suits)
- Built using gradle
- Has dockerized build scripts
- Has integration tests that are run on docker images

The Riskscape development team use Ubuntu Linux. All of the commands and
scripts refered to should work well on Ubuntu or any other modern debian
based operating system.

# Project layout

Riskscape is made up of multiple sub-projects.

- engine, the core engine
- core, core API's required by sub-projects
- cli, the command line interface
- defaults, default plugin. provides default functionality,
- plugins/jython, implements functions and types in jython(python2)
- plugins/<others>, provide additional functionality in a plugable way

- test-shared, library useful for tests
- test-integration, where integration tests are

# Build

RiskScape can be built on traditional bare-metal or inside a docker container.  The
build is tested under a debian-based linux environment and is x86_64 only.

## Traditional build

Assumes you have a Java JDK (> JDK17) installed.

```
./gradlew installDist
./engine/app/build/install/riskscape/bin/riskscape
```

The *installDist* build target will build the riskscape software so that the CLI
can be run from *./engine/app/build/install/riskscape/bin/riskscape*.  Alternatively,
the `bin/riskscape` script is a shortcut for both of these steps.

Other useful build targets are:
- clean, removes all built artifacts
- check, checks code style and runs unit tests
- distzip, assembles built software into a zip bundle to distribute
- publishToMavenLocal, builds and installs project's jars to your ~/.m2 directory

## Using Docker

Assumes you have a recent version of docker installed.

```
# Prepare a base image with Java
./bin/build-base-image.sh

# install the results on docker images *riskscape-cli*, *riskscape-cli-ogr*, *riskscape-cli-hdf5*
./bin/docker-build.sh

# to start a terminal session using *riskscape-cli* image (your home directory and pwd are available)
./bin/docker-as-user.sh -it riskscape-cli
```

### Catalyst Infrastructure

Some aspects of the RiskScape containerized build refer to Catalyst IT's internal infrastructure:

* harbor.catalyst.net.nz - A docker registry used for distributing public and private
  docker images.  RiskScape uses a public base ubuntu image (instead of docker library's
  ubuntu images).

* gitlab.catalyst.net.nz:4567 - A docker registry used for CI and developer builds.  Should
  not be required to build a containerized version of RiskScape, although you will see
  access denied errors during the build without it.

# Development

Non-trivial changes should be mentioned in the changelog - see `changelog.d/README.md`
for more details.

## Release Procedure

### Prerequisites

Before proceeding with the release process please check that
the RiskScape codebase is stable and is ready for release.

In particular check:
- the license `riskscape --license` has the current year in the copyright. Check in the
docs license page as well.
- the version links in docs/source/intro/downloads.md have been updated (the links are placeholders
that will point to the new release once we've uploaded it). Make sure to check the version for
riskscape-geotools-patches.jar as well

#### Bump the VERSION

Update the version number in `VERSION` for the new Riskscape Engine release,
and store it in a bash variable for running subsequent commands:

```
vim VERSION # remove -dev suffix
read VERSION < VERSION
```

#### Update the Changelog

Move the 'unreleased' changelog.d directory to reflect the release version
(note the changelog.d directory must start with 'v'),
and update the vx.y.z-header.md file to include the current date:

```
git mv changelog.d/unreleased changelog.d/v$VERSION
echo "Built $(date +"%-d %B %Y")" > changelog.d/v$VERSION-header.md
git add changelog.d/v$VERSION-header.md
```

Build the docs and check that the CHANGELOG.md is accurate, is correctly formatted,
makes sense to users, and has the correct version heading/date.

#### Edit `downloads.md`

Open `docs/source/intro/downloads.md` and update it:

* Copy the current latest release and add it to "Older releases"
* Replace the references to the old version with the new ones.  A search and replace should do it, but be aware of the hyphenated version in the changelog.

Note that these links won't be live yet, they are placeholders
that will point to the new release once we've uploaded it.

Make sure to check the version for riskscape-geotools-patches.jar as well

### Building the release

Once the branch is all ready to go, tag and sign a new version:

```
git add VERSION && git commit -m "build: Remove dev suffix for ${VERSION} build"
git tag --sign "${VERSION}" --message "Release ${VERSION}"
git push --tags
# bump version, typically this is the minor version, e.g. 1.3.0 -> 1.4.0'
# Don't forget to add the -dev suffix!
vim VERSION
# seed the unreleased directory. we need to put a file (.gitkeep) in it to keep git happy
# but the build change log script only processes *.md files so this is fine.
mkdir changelog.d/unreleased && touch changelog.d/unreleased/.gitkeep && git add changelog.d/unreleased/.gitkeep
grep '\-dev$' VERSION \
	&& read VERSION < VERSION \
	&& git add VERSION \
	&& git commit -m "build: Bump version to ${VERSION}"
```

Assuming the tests pass, CI will then publish a new docker image as
`gitlab.catalyst.net.nz:4567/riskscape/riskscape/cli:${VERSION}`.

### Uploading the release

Now follow the `../riskscape-opscode/releases/README.md` instructions to
update the new release.

### Follow-up tasks

Once released, remember to update any other repositories that rely on
the RiskScape snapshot packages to build. Currently these are:
- eqc (RISKSCAPE_VERSION in .gitlab-ci.yml)
- riskscape-platform (riskscapeVersion in plugin/build.gradle)

## Documentation

Refer [docs README](./docs/README.md).

## Testing

### Testing PostGIS

To fire up a PostGIS database, use:

```
bin/docker-postgis.sh start
```

Then use the following to access it:

```
export PGPASSWORD=riskscape
postgis://riskscape@localhost:55432/riskscape
```
