Preparation

This installation guide will help you get a local development environment up and running where you can edit the core code of the Nabu Platform. The article was originally written for an ubuntu 24.04 LTS edition but it has also been successfully run on a Mac.

Install java

Nabu should run on pretty much any java version between 8 and the current release. I tend to stick to the default jdk that ships with my system:

The version happens to be:

Install CLI tools

We need some basic CLI tools like git, maven and unzip:

Because the Nabu source code is hosted on github, we also need the github CLI to automate some things. Downloads are available on the releases page.

Once you have the github cli installed, you need to log in (don't worry, you can simply log in with your browser):

Install glue

The installation uses scripts written in Glue - the scripting language that also runs in Nabu itself.
This means you need a functional glue environment, check out the installation guide to get it up and running.

Get the scripts

Checkout the scripts:

Add the resulting scripts folder to the environment variable GLUEPATH, for example:

Depending on the environment, you can add this to your equivalent of ~/.bashrc.
Don't forget to run source ~/.bashrc to load it into the current session as needed.

Generate a keystore

Nabu artifacts should be signed, to this end we generate a keystore:

When you run the above command, it will prompt you for information:

• Keystore Password: Set a secure password for the keystore.
• Distinguished Name Fields, when prompted at the end if it is correct, it will only show [no]. Type "yes".
• * Your first and last name
• * Your organizational unit
• * Your organization
• * Your city or locality
• * Your state or province
• * Your country code (2-letter code)
• Key Password: Set a password for the key itself

Make sure you remember the passwords as you will need them to configure maven.

Configure maven

You need to add a settings.xml file to ~/.m2 folder (create it if it doesn't exist yet) to configure your maven enviromnent. This is mostly for registering the keystore.

Building the environment

Now we'll start to actually build the environment using the setup we have so far.
The first time you run any of the scripts you will be prompted for some initial configuration indicating the preferred file system layout. By default everything is stored in a nabu folder that is added to your home folder.

Clone everything

Clone all the current projects, this contains "java", "repository" (in the nabu repository), "web" and "pom" as types.

You can run the following command to clone only the java packages:

Build projects

This will loop over all the java projects and check if they need to be rebuilt based on the last modified timestamps:

You can also specify one or multiple projects:

You can force a build as well:

The build script will also automatically update the libraries both in the repository and installed applications you might have.

Packaging everything

The applications (integrator, developer, cli) are packaged using maven assemblies. The modules are simply maven packages. Both can be built using the mvn clean package command.
However, to make it somewhat easier, there is also a script. It will ensure that the parent poms are up to date and copy the resulting packaged artifacts into a dedicated build folder.

You can package both the modules and the applications using this script:

You can target a specific module, for instance:

And force it if needed

You can build only java applications or repository modules by providing a type:

Installing the applications

There are two ways to run the applications. One is to install them as an OS-agnostic zip file accompanied by the necessary scripts. The other is OS-specific installers.

The install script focuses on the first approach and it will create runnable versions of all three applications in the designated folder.

Run it using:

You can specify a particular application using:

The default options are "integrator", "developer" and "cli".

The install will by default only update the library folder leaving the other files intact. This allows you to configure for instance the server without having to worry that it will be overriden every time you update.

Creating OS-specific installers

To create OS-specific installers you can run:

Note that the first time you will be prompted for some additional configurations that need to happen. Currently the images have been tested on ubuntu (deb) and mac (dmg).

Install eclipse

To edit the java projects you can likely use any IDE you want. Historically I've used eclipse.

Download eclipse from https://www.eclipse.org/.
Choose the basic "java developer" edition when prompted.

You can make a project eclipse ready by running mvn eclipse:eclipse. A tiny wrapper script will run this over all projects:

Then start up eclipse, point it to the java workspace that resides on ~/nabu/workspaces/core.

At first the package explorer will still be empty but you can choose Import projects.... Choose General > Existing Projects into Workspace.
As root directory, select the same workspace directory. It should automatically select all the projects, hit Finish to complete the action.

If any projects remain in error, re-running the script with "force" should fix it:

Update repositories

To pull all the latest changes, run:

Building with older versions of javafx

When building for instance with java 11, you will notice that the current version (23) of the javafx libraries is not compatible.
Go to poms/core.xml and update the 4 javafx references from 23 to for example 11 to enable compilation for older clients.

Contributing

Develop on cloned repository

You can start a developer and point it to the repository that was checked out from github at ~/nabu/repositories/main.

You do this by creating a new profile, choosing protocol LOCAL and choosing Unmanaged repository. Once you choose that option, a directory picker will appear which allows you to select the folder in question.

Pull requests

Whether through developer, eclipse or a plain text editor. Once you have a changeset that you want to suggest as a contribution, you can create a pull request. Go to the folder of the project or module where you made the changes.

Commit your changes to a separate branch:

Once you have done this, you can create a pull request for that branch. The tool will automatically suggest that you create a fork of the repository to do this:

Note that once this is done, the remotes of the git repo will have changed. Origin is no longer the official repo but your own fork. The official repo is now moved to the "upstream" remote.

The pull script will recognize these upstream remotes if they exist and use those rather than origin. However you do need to be in the master branch for the pull to work, otherwise it will simply skip that project.