Server tooling - Genesis IntelliJ plugin

The Genesis Intellij Plugin enables you to run the full stack of a Genesis application locally within IntelliJ, so you can check and test your development work as you progress.

Installation

1. To install, click on the button below:

2. After installing the plugin, The Tool window bars and buttons will be visible once you open a Genesis Project.

tip

If the tool window does not appear in a Genesis project, please make sure that you have opened the correct folder. The plugin will expect your project to have a folder called server; it checks the settings.gradle.kts file in that folder for Genesis dependencies:

my project/
├─ client/
├─ server/
│  ├─ setting.gradle.kts

Sometimes, especially when opening a project extracted from a zip file, there might be a nested project folder:

my project/     <-- don't open this folder
├─ my project/  <-- open this folder
│  ├─ client/
│  ├─ server/
│  │  ├─ setting.gradle.kts

3. For MacOs specifically, you need to install LMDB locally to start a Genesis data server.

Installing LMDB for MacOs

info

This is not required for developers that use Windows locally.

1. Install lmdb using brew:

brew install lmdb

2. Create a symlink to make LMDB accessible through Java:

ln -s /opt/homebrew/opt/lmdb/lib/liblmdb.dylib /Users/<your.username>/Library/Java/Extensions/liblmdb.dylib

Please note that processes might not be showing at this point.

important

That's the end of the installation process. If you have come here from the Quick Start guide, you can go back now.

Getting help

The Genesis Documentation is available straight from the tool window.

First-time set-up

Once the Genesis tool window is visible you are ready for the first-time set-up.

Before you can start any services, there are a few things you need to do:

1. Configure your database.
2. Run remap.
3. Load some stock data.

info

If you see the message below when you start the plugin:

...this means that you are using a deployed set-up. You need to run the install process before running remap.

Database configuration

Unless your project is configured to use H2 out of the box, you need to configure the plugin to use a supported database.

Below, you will find example configurations for the following databases:

• Postgres
• MS Sql Server
• H2

To configure the database in the plugin, go to the Genesis Tool Window and click on Open Genesis Settings.

Postgres

For a local PostgreSQL installation using the docker run command below, your settings should look like this:

To run postgres using docker or rancher desktop, use the following command:

docker run -tid -p 5432:5432 -e POSTGRES_PASSWORD=docker -e PGDATA=/tmp postgres:12.6-alpine -c shared_buffers=80MB -c max_connections=250

Once the container is set up, use the following database configuration in the plugin:

Option	Setting
DbLayer	SQL
DbHost	jdbc:postgresql://localhost:5432/
DbUsername	postgres
DbPassword	docker

MS SQL Server

For a local PostgreSQL installation MS SQL Server using a docker or rancher desktop, use the following command:

docker run -d --name sql1 --hostname sql1 -p 1433:1433 -e ACCEPT_EULA=1 -e MSSQL_SA_PASSWORD=G3n3s1sGl0bal -e MSSQL_PID=Developer  mcr.microsoft.com/azure-sql-edge

Once the container is set up, use the following database configuration in the plugin:

Option	Setting
DbLayer	SQL
DbHost	jdbc:sqlserver://localhost;trustServerCertificate=true
DbUsername	SA
DbPassword	G3n3s1sGl0bal

H2

H2 is the easiest database to run locally. There is no need to install anything, as H2 uses a local file to store the database. While H2 is not supported for production, it does help developers start quickly locally.

Option	Setting
DbLayer	SQL
DbHost	jdbc:h2:file:~/genesis-local-db/{{appName}}/h2/test;DB_CLOSE_DELAY=-1;NON_KEYWORDS=VALUE,KEY;AUTO_SERVER=TRUE

Run remap

With the Genesis Framework, remap manages the database schema. Whenever tables are added, modified or removed, you need to run remap to sync these changes. This includes when you run your project for the first time.

The remap icon looks like a database with green refresh arrows in the bottom right corner. Once you start remap, at first it will run a sync, and then remap appears as a tab in the run Window:

At this point, you need enter y in the screen and press Enter. Remap then applies the changes and exits:

important

Remap cannot be run while other processes are running.

We cannot use the database and update it at the same time.

If processes are running when you start remap, the plugin warns you and gives you the option to stop all processes before proceeding.

Loading data

Most projects require some data or sample data in CSV files; you can load the data directly from IntelliJ.

Right-click on a CSV file, a number of selected CSV files, or on a folder containing CSV files, then select Import CSV(s) to Genesis.

This imports the data using SendIt. Alternatively, you can use SendIt directly from the terminal.

Using the Genesis IntelliJ plugin

Once you have completed the steps above, you are ready to start your application. The Genesis Tool Window is the main entry point:

Starting the front and back ends

To run your Genesis application locally, you can use these two buttons:

• To start all services, click on the double green triangles (Start All Services).
• To start the UI, click on the globe with the green triangle.

tip

Starting all processes at once in large projects can take some time. By default, a separate run window is opened for each process. To clean up the UI, use the Services window for better organisation (only available in IntelliJ Ultimate Edition).

Starting the back end

To start all services, click on Start All Services. You can start specific services from the mon Window, and from the Intellij Run Config list:

Once the process has started, the log file will be attached to the process:

Filtering processes

To start only selected processes when clicking on Start All Genesis Services, you can enable the processes filter, by unticking Enable All Processes in the settings:

Once this setting is unticked, you can filter which processes to start:

When a process is unticked, it will no longer be started via any start server command, either from the terminal or the start server button. However, processes that are not ticked, can still be started manually.

To re-enable the process, simply check the box and click on start server again.

Note that Start All Process does not attempt to start any processes that are already running, so you can safely re-enable processes and click on start server again.

Filtering the Process Log files

By default, IntelliJ filters the log file and shows only log entries of level WARN or ERROR. To change that, hover your mouse in the top right of the log file to display the following menu:

Click on the funnel, to see the options available (below). From there, select all to display the unfiltered log.

Starting processes

Processes can be started using the Start All Genesis Services button mentioned above. You can also be started from the mon window.

Additionally, you can control processes from the terminal using these commands:

• startProcess {process name} - start a process
• killProcess {process name} - kills a process
• startServer - run Start All Genesis Services
• killServer - stops all running services

Debugging processes

It is possible to debug Genesis processes and step through code. This includes any GPAL files. As long as the source is available, you should be able to debug.

Starting the UI

To start your application's UI, click the Start UI button mentioned above.

This first runs the bootstrap NPM task.

It then runs the dev:intellij NPM task, which by default does not have an explicit API_HOST value set; this allows the plugin to pass the correct host value.

If there is no dev:intellij task defined, the dev task is used as a fallback.

This builds your front-end codebase and starts the webpack webserver in development mode. After this, it launches a browser tab showing your application's login screen.

When running through the IntelliJ plugin, the back end is available on 'ws://localhost:9064'.

In production environments, it is typically available through NGINX on 'wss://host-name/gwf'. This is controlled by setting the API_HOST environment variable. If your front-end project has the 'dev:intellij' NPM task, the API_HOST will be set automatically. However, if your project only has the 'dev' task, then you need to make sure the API_HOST is set to 'ws://localhost:9064' to ensure that the front end is able to connect to the back end.

info

Note that we are using GENESIS_ROUTER as our API_HOST; its default port is 9064. Therefore, your router port in the settings should be:

Depending on your edition and version of IntelliJ, the following NPM tasks will run:

• On the Ultimate Edition - the plugin uses the built-in NPM run configuration
• On the Community Edition - the plugin uses the built-in shell run configuration to run NPM when available:
  • MacOs - any version
  • Windows - IntelliJ version 2023.3 and after
  • Windows - any IntelliJ version, if the "SHELL" env variable is set to 'powershell.exe'
• Else it will run the front end from the Build screen

NPM run configurations

When available, the plugin uses the built-in NPM run configurations. This uses the IntelliJ-configured Node interpreter.

In this mode, the plugin generates a UI and a bootstrap run configuration.

You can trigger these configurations either from the Genesis Tool Window or directly from IntelliJ.

Shell run configuration

On community editions of IntelliJ, this is the preferred option. With this run configuration, the plugin uses whichever node interpreter is available on the terminal. It creates a UI-script and an npm bootstrap run configuration.

You can trigger both of these from either the Genesis Tool Window or directly from IntelliJ.

In most cases, picking up npm from the path will be sufficient. However, when using the community edition, there is an NPM location setting in Genesis Settings that you can use.

If this does not resolve the issue, use the build screen starter by selecting Use legacy UI starter from settings.

Starting from the build screen

If the script run config is not available, or if the legacy ui starter is selected, the UI starter is shown in the build screen. This can only be started from the Genesis Tool Window.

The mon window

The Mon tab mirrors the mon command on the server.

From here you are able to:

• see the available processes
• start, restart and stop processes
• see the health status of each process
• monitor the CPU and memory usage of each process
• filter which processes are started on Start Server

Showing and hiding columns

You can configure which columns are displayed in the window with the following settings:

If you have less space available for the window, you could disable the CPU and Memory columns to give the others more space:

info

You must have at least one column displayed. If you hide all columns, the process name column will still appear; this is the default.

Disabled columns persist to the project settings, so they stay disabled between restarts.

OpenAPI

The plugin can contact the router to provide an openapi spec. To do this, the plugin asks for a username and password to log in to your application. It then requests the openapi spec and shows a dialog to save it into your project.

To start this process, click on the Genesis menu and then on Generate OpenApi Spec:

This triggers a username and password dialog.

After supplying the details, you are asked to save the spec, and the app should open automatically.

Using the terminal

The Genesis Plugin integrates directly into IntelliJ's terminal. Most commands supported on the server can be run straight from there. Supported commands are highlighted in green.

You can run these using CTRL+ Enter on Windows, or Command + Enter on MAC.

For example:

Or:

Useful commands

These are some of the commonly used commands in the plugin:

• DbMon - the Genesis Database client
• DumpIt - export CSV data from the database
• SendIt - send CSV data to the database
• LogLevel - dynamically adjust log levels of running processes

There is a full list of Genesis commands in our documentation.

Resource daemon

The resource daemon provides information about locally running processes. This provides the information shown in the mon window in the plugin and the mon command on the server.

The plugin can automatically start the daemon when needed.

If you find the daemon starting too often, you can disable it by unticking Enable Resource Daemon Auto Start in the menu.

If process information is not showing in the mon window, you can start the daemon from the menu:

However, regardless of this setting, the resource daemon will be started whenever you start any back-end service.

Keeping your local Genesis Home in sync

Every Genesis application, whether deployed to a server, or running locally, needs a home folder. This folder is the installation location; it includes all dependencies and configuration needed to run the application.

There are two ways that this is managed from within the plugin:

• For the initial release of the plugin, you have to manage this; this is Deployed mode.
• For later releases, we have included a gradle plugin that adds a genesisSync task for this purpose; this is Gradle mode.

To check which mode the plugin is running in, click on the Get Help section of the plugin, then select Check Plugin Mode:

Gradle mode

In Gradle mode, the plugin ensures that the Genesis Home folder is synchronised. Before running any other task, the genesisSync gradle task is triggered:

This task builds local modules, copies the configuration of any dependencies, and runs genesisInstall.

The benefits of the Gradle mode over the Deploy mode are:

• automatic synchronisation of the genesis home folder
• dependencies are loaded from the gradle cache, rather than installed in the home folder - speeding things up
• integration into gradle task avoidance system means that this task will do no more than necessary.
• easier management of genesis dependencies for your project

Deploy mode

important

Deployed mode is still supported, but we recommens that you migrate your project to Gradle mode. This will greatly simplify the user experience in the plugin.

When using the Deploy mode, you are responsible for ensuring the Genesis Home folder is kept up-to-date. The first time you open a project with the plugin enabled, you must create your genesis home folder.

Click on the Install Genesis button on the Tool window.

Whenever the home folder needs to be updated, select the Prepare Local Genesis Application task:

This runs a full Gradle build and a genesisInstall. (If you run this task in Gradle mode, it triggers the genesisSync task.)

Changing dependencies

After dependencies have been added, you might need to do different things to keep your project up to date. The steps to take depend on which mode the plugin is running in.

It also depends on whether you are adding or changing a Genesis or Business Component dependency.

The procedure is the same, whether adding or removing a dependency, or even when changing a version.

Changing a dependency in Deploy mode

In Deploy mode, click on the Prepare Local Genesis Application button.

• If you are adding a normal JVM dependency, syncing gradle in this way will be sufficient.
• If you are adding or changing a Business Component dependency, also run Remap.

Changing in Gradle mode

If you are changing a Genesis or Business Component dependency:

1. Click on the Prepare Local Genesis Application button.
2. Run remap.