Running Stroom in an IDE

We tend to use IntelliJ as our Java IDE of choice. This is a guide for running Stroom in IntelliJ for the purposes of developing/debugging Stroom.

Prerequisites

In order to build/run/debug Stroom you will need the following:

• Java 8 JDK
• Git
• Gradle
• IntelliJ
• Docker CE
• Docker Compose

These instructions assume that all servcies will either run in the IDE or in Docker containers.

Environment variables

Stroom git repositories

To develop stroom you will need to clone/fork multiple git repositories. To quickly clone all of the Stroom repositories you can use the helper script described in stroom-resource (external link).

Database setup

Stroom requires a MySQL database to run. You can either point stroom at a MySQL server or preferably at a MySQL Docker containers.

MySQL in a Docker container

See the section below on stroom-resources.

Host based MySQL server

With an instance of MySQL server 5.5 running on your local machine do the following to create the stroom database:

# log into your MySQL server using your root credentials
mysql --user=root --password=myrootpassword

Then run the following commands in the MySQL shell:

drop database stroom;
create database stroom;
grant all privileges on stroom.* to stroomuser@localhost identified by 'stroompassword1';
quit;

Local configuration file

When running stroom in an IDE it is advisable to have a local configuration file to allow you to change settings locally without affecting the repository. The local configuration file is expected to live at ~/.stroom/stroom.conf. To create a default version of this file run the script stroom.conf.sh from within the root of the stroom git repository.

Add any properties from stroom.properties that you want different values for, e.g.

stroom-resources

As a minimum to develop stroom you will need clones of the stroom and stroom-resources git repositories. stroom-resources provides the docker-compose configuration for running the many docker containers needed.

Having cloned stroom-resources navigate to the directory stroom-resources/bin and run the script

./bounceIt.sh

On first run this will create a default version of the git-ignored file stroom-resources/bin/local.env which is intended for use by developers to configure the docker stacks to run.

This file is used to set a number of environment variables that docker compose will use to configure the various containers. The key environment variable in there is SERVICE_LIST. This is a space delimited list of the services for docker-compose to run. The services are all defined in stroom-resources/bin/compose/everything.yml and its dependencies. By default SERVICE_LIST runs a core stroom stack entirely in docker.

To run stroom in an IDE stroom needs to be removed from SERVICE_LIST, i.e. by commenting out the line SERVICE_LIST="${SERVICE_LIST} stroom" in local.env. Having done this run stroom’s core dependencies as follows:

./bounceIt.sh

Verify the Gradle build

Before trying to run Stroom in an IDE it is worth performing a Gradle build without the integration tests (as these take ~20mins to run) to verify the code compiles and all dependencies are present.

./gradlew clean build -x integrationTest

Sample Data

Some of the tests are dependant on some sample data and content being present in the database. This sample data/content can also be useful for manually testing the application in development. The sample data/content is generated by a class called SetupSampleData.java. This class assumes that the database being used for Stroom is completely empty.

First you need to create a run configuration for SetupSampleData.java

1. Click Run -> Edit Configurations…
2. Click the green + icon to add a new configuration
3. Select Application as the configuration type
4. In the Main Class field enter SetupSampleData
5. In the Use classpath of module field select stroom-integrationtest
6. If you have set the STROOM_TMP environment variable in your .bashrc / .zshrc then ignore this step. In the Environment variables field click the … icon and add STROOM_TMP = ~/tmp/stroom/ (or whatever directory you choose)
7. Click the OK button

Now run SetupSampleData

1. Click Run -> Run…
2. Select SetupSampleData

You should now have a database populated with tables and data, providing you with some predefined feeds, data, translations, pipelines, dashboards, etc.

Running Stroom from the IDE

The user interface for Stroom is built using GWT (see GWT Project for more information or GWT specific documentation). As a result Stroom needs to be started up with GWT Dev Mode. Dev Mode handles the compilation of the Java user interface source into JavaScript and the source map that links client JavaScript back to Java source for client side debugging.

Stroom is run from the main method in Startup.java. Before running this you need to setup the run configuration:

1. Click Run -> Edit Configurations…
2. Click the green + icon to add a new configuration
3. Select Application as the configuration type
4. In the Main class field enter Startup
5. In the Programme arguments field enter

-startupUrl stroom.jsp -logLevel INFO -war . -logdir . -gen . -extra . -workDir . stroom.app.AppSuperDevMode

1. In the Use classpath of module field select stroom-startup
2. If you have set the STROOM_TMP environment variable in your .bashrc / .zshrc then ignore this step. In the Environment variables field click the … icon and add STROOM_TMP = ~/tmp/stroom/ (or whatever directory you choose)
3. Click the OK button

Now run Startup

1. Click Run -> Run…
2. Select Startup

You should eventually see the GWT Dev Mode window appear.

Initially, some of the buttons shown above will not be visible as it is in the process of starting up. As soon as the Launch Default Browser button appears you are ready to open Stroom in a browser. You have two options:

• Click the Launch Default Browser button
• Open your preferred browser and enter the URL http://127.0.0.1:8888

NOTE: Stroom has been written with Google’s Chrome browser in mind so has only been tested on Chrome. Behaviour in other browsers may vary. We would like to improve cross-browser support so please let us know about any browser incompatibilities that you find.

In the browser you will initially see the following:

Starting Stroom

Initialising context…

Once the context has been initialised you will see the Stroom blue background and a spinner while GWT compiles the front-end code. Once the code has been compiled you will be presented with the Stroom login page. Stroom in development mode uses simple username/password authentication. Enter the following credentials:

• Username: admin
• Password: admin

Right click behaviour

Stroom overrides the defualt right click behaviour in the browser with its own context menu. For UI development it is often required to have access to the browser’s context menu for example to inspect elements. To enable the browser’s context menu you need to uncomment the following property in your stroom.conf file, e.g.

#Uncomment this to enable browser's right click menu for development
stroom.ui.oncontextmenu=