Build tools

Software requirements

To run a Genesis application, including on your local machine, the following software must be installed:

Software	Access Information
JDK v17	Windows (.msi) Other Platforms
Node.js v20	Windows (.msi) Other Platforms
LMDB (Mac Only)	Installation Guide
Genesis Server Framework (GSF)	Artifact Access
Genesis Web Framework (Foundation)	Artifact Access
Gradle	Bundled with your Genesis application project (unless you create a new project with "Exclude Gradle Wrapper JAR" selected)

LMDB installation guide (MacOS)

When running a Genesis application on MacOS, you must install and configure LMDB. The following steps can be followed:

1. Install lmdb for Mac: homebrew installation instructions
2. Add liblmdb.dylib to your Java Extensions:

mkdir -p ~/Library/Java/Extensions
cp /opt/homebrew/opt/lmdb/lib/liblmdb.dylib ~/Library/Java/Extensions/

Gradle deploy plugin

The Genesis Application Platform provides a Gradle plugin that makes it easy to perform all the installation tasks that are necessary to deploy your own Genesis project on your local workstation, from your IDE.

The plugin is designed to work on workstations running Linux, or on WSL.

Enabling the deployment plugin in your project

Simply set genesisDeploy.enabled = true in your application's server/settings.gradle.kts file.

  plugins {
    genesisDeploy.enabled = true
  }

General set-up

Make sure you have a gradle.properties file in the .gradle directory in your user home directory; this file must contain your Genesis Artifactory credentials in clear (unencrypted) text:

genesisArtifactoryUser=<your-artifactory-user>
genesisArtifactoryPassword=<your-artifactory-password>

note

This requires credentials for accessing Genesis Artifactory. If you have not been provided with the credentials, please contact your administrator, or contact us. It's not possible to complete the training without this access, because you won't be able to download the Genesis platform components and build your project.

Application Distribution

Applications can build zip distributions using the appDistZip Gradle task.

This Gradle task will create a standalone zip distribution for an application that can be deployed and that is used as input for the docker image process.

The zip file will include the full Genesis distribution, each PBC distribution, the app's server and web distribution.

There are two ways in which this zip can be constructed:

• By default, each Genesis dependency, including Genesis-Server and each PBC, will include its full set of jars.
• If dynamic deployments are enabled, an App can take control of dependency resolution, and this will result in a single set of jars in site-specific/lib

Dynamic Deployments

Using dynamic deployments, Apps can take control of dependency resolution, which achieves the following:

• Apps are able to overwrite vulnerable dependencies. It is the developer's responsibility to assess binary compatibility.
• A smaller distribution will be created, as jars are only included if required, and then only once.

Enabling Dynamic Deployments

To enable dynamic deployments you can either add a Gradle property in your site-side project's gradle.properties:

enableDynamicDeployment=true

Or set the same property in genesisExec { ... } in your -app or -deploy module.

genesisExec {
    enableDynamicDeployment = true
}

Using genesisRuntime configuration

To add runtime dependencies and set constraints, use the genesisRuntime configuration in Gradle. Add these in server/build.gradle.kts. For example, to add a runtime dependency on javax.mail:mail:1.4 for all your processes, use:

dependencies {
    genesisRuntime("javax.mail:mail:1.4")
}

Overwriting Dependency Vulnerabilities

The same configuration can be used for setting dependency constraints. This is useful to patch the application, in case a vulnerability is detected, and waiting for the next Genesis release is not an option. This can be done using the standard Gradle constraint syntax. Care should be taken to test the application with the new dependency setup. With every release of the Genesis platform, the platform is compiled and tested against its declared dependencies. Overwriting dependencies can introduce subtle bugs and linkage errors. Please read the release notes of the affected jars carefully for breaking changes.

Setting a minimum version

If a vulnerability exists in a dependency and a newer version without that vulnerability exists, the recommended approach is to set a minimum version. This can be done using the require() syntax and adding a reason in because().

For example, to set the minimum version of netty-handler to 4.1.100.Final and add a reference to a CVE, use:

dependencies {
    constraints {
        genesisRuntime("io.netty:netty-handler") {
            version { require("4.1.100.Final") }
            because("CVE-2022-1471")
        }
    }
}

This will set the minimum version for the dependency across the application. However, if after upgrading Genesis uses version 5.0.0, Gradle will use that version.

When the only option is to roll back

Sometimes a vulnerability exists and the only option is to roll back until a fix is available. In that case, a combination of reject, prefer and require should be used:

constraints {
    genesisRuntime("com.example:problem-lib") {
        version {
            require("1.2.3")
            reject("1.2.4", "1.2.5")
            prefer("1.2.6")
        }
        because("1.2.4–1.2.5 are broken; allow newer fixed releases")
    }
}

Overwriting using a BOM

In exceptional cases, a whole suite of dependencies might need to be overwritten. In that case, if a library provides a BOM, you can use enforcedPlatform. However, care should be taken to remove this overwrite once the platform is upgraded.

dependencies {
    // remove once Genesis platform version is upgraded
    // to cover CVE-2020-1234
    genesisRuntime(enforcedPlatform("com.fasterxml.jackson:jackson-bom:2.16.1"))
}

Please note that the same dependency resolution algorithm will be used when running a Genesis Application locally, using the IntelliJ plugin or Genesis Start.