Manual setup - IntegratedBreedingPlatform/Documentation GitHub Wiki

BMS Manual setup

This is a guide to build and run BMS from source.

Prerequisite Software

If you do not have any of the following installed, follow the instructions.

MySQL

Download and install MySQL Community Server 5.7.41

You will probably also want to install MySQL Workbench and MySQL Utilities to assist in working with your MySQL databases.

Tomcat

Download and extract version 9.0.74 of Tomcat.

JDK

Install the latest Java 8.x JDK and set the JAVA_HOME variable.

Maven

Install the 3.6.3 version of Maven and follow the installation instructions. Add maven bin directory on your command line path for direct access.

Git

Download latest version of Git for your OS and follow the installation instructions.

NodeJS

Install the 14.17 version of NodeJS and follow the installation instructions.

Project Code

Clone following BMS projects from GitHub:

git clone [email protected]:IntegratedBreedingPlatform/BMSConfig-v25.git BMSConfig
git clone [email protected]:IntegratedBreedingPlatform/Middleware
git clone [email protected]:IntegratedBreedingPlatform/Commons
git clone [email protected]:IntegratedBreedingPlatform/BMSAPI
git clone [email protected]:IntegratedBreedingPlatform/Fieldbook
git clone [email protected]:IntegratedBreedingPlatform/Workbench
git clone [email protected]:IntegratedBreedingPlatform/InventoryManager
git clone [email protected]:IntegratedBreedingPlatform/GDMS

Middleware is the data access layer library of the BMS.

Commons contain some common classes that are used by all BMS web applications. Fieldbook, Workbench and GDMS are the main web applications BMS ships with. Workbench is the front-end/launcher/portal for the BMS providing access to various tools and applications for the breeders (both native Windows and browser based apps). See the home page README.md on GitHub for each of the above projects for project specific details. Other third party applications are also integrated within BMS, but those will not be covered here.

Build the Projects

All project configuration must be done in the BMSConfig folder. Essentially each configuration only requires two property files i.e. application.properties and test.properties. See also Properties Based Configuration for the BMS

You can use an existing configuration or create a new folder with your own configuration. If you are creating a new configuration copy the existing template folder. Rename the copied folder and customise the application.properties and test.properties file for you needs.

Then to build all projects run:

mvn clean install -DskipTests -Duser.name=template

If your profile conf directory is the same as your system user name, you can omit the parameter.

mvn clean install -DskipTests

Middleware needs to be built first, and Commons second (as it depends on Middleware). The rest of the projects can be built in any order.

On successful build, .war files will be created in target folder under each web application project directory.

Leafnode team

Leafnode team keeps this configuration in a single repo: BMSConfig

Create DB Schema

To create DB Schema, please refer to this link: https://github.com/IntegratedBreedingPlatform/DBScripts/tree/master/setuputils#create-db-schema

Configuring Tomcat

Tomcat Port

Default tomcat port used by BMS applications is 48080. Configure the default tomcat Connector in TOMCAT_HOME/conf/server.xml to listen on 48080 instead of the default 8080.

VM Options

Create setenv.sh file into your TOMCAT_HOME/bin directory. This file probably does not already exist but if it does, add to it. Tomcat will pick this file up (check in catalina.sh if you like) when it starts.

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/tomcat/spring-instrument-3.2.11.RELEASE.jar"
JAVA_OPTS="$JAVA_OPTS -server -Xms756m -Xmx1592m"

(setenv.bat for Windows):

set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:C:\BMS4\spring-instrument-3.2.11.RELEASE.jar
set JAVA_OPTS=%JAVA_OPTS% -server -Xms756m -Xmx1592m

Liquibase

If you want to run liquibase (See Database change tracking and upgrades) you'll need to set development profile also:

CATALINA_OPTS="$CATALINA_OPTS -Dspring.profiles.active=development"

Load Time Weaving

This is one of Tomcat setting required to deal with Spring Load Time Weaving used by workbench.

  • Download spring-instrument-4.1.6.RELEASE.jar from Maven repository and save it to a known location.
  • Alter the -javaagent property in the CATALINA_OPTS variable in tomcat_settings/setenv.sh (setenv.bat for windows users) to be the location of spring-instrument-4.1.6.RELEASE.jar.

Install BMS and Start Tomcat

Copy the WAR files into TOMCAT_HOME/webapps directory.

Start tomcat by executing TOMCAT_HOME/bin/startup.sh.

Tomcat Manager Setup

Workbench uses the Tomcat Manager application to check the status of the web application before launching.

Make sure you have the Tomcat Manager application deployed (TOMCAT_HOME/webapps/manager folder should be non empty). If you downloaded the 9.0.74 zip distribution of Tomcat, the manager application comes with it.

Add following lines under your TOMCAT_HOME/conf/tomcat-users.xml under element:

<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<role rolename="manager-jmx"/>
<role rolename="manager-status"/>
<user username="tomcat" password="tomcat" roles="manager-gui,manager-script,manager-jmx,manager-status"/>

Following properties in workbench.properties file of the Workbench application relate to accessing the tomcat manager application:

tomcat.manager.url=http://localhost:18080/manager/text
tomcat.manager.username=tomcat
tomcat.manager.password=tomcat

Make sure whatever envConfig you are using for building, the pipeline folder for that config has the correct values for these three properties in workbench.properties. The above examples are from release config.

Disable session serialization

Uncomment following lines in TOMCAT_HOME/conf/context.xml to disable session serialization:

<Manager pathname="" />

Windows Only - Install BMS Windows tools

BMS utilizes some desktop Windows tools for some parts of the overall breeding management workflow. These tools are :

..and the following libraries which are dependencies of these tools:

Obtain a copy of these tools from IBP/Leafnode and put them under the ${misc.IBPInstallDir}/tools directory (where misc.IBPInstallDir is the directory you configured as the BMS installation home).