developer-guide.adoc

Smarti Developer Guide

Introduction

Smarti is a Java-Application based on the Spring Framework. The application uses MongoDB as database and Apache Solr as search engine. Installation packages are provided for Debian- and RedHat-based systems. Alternatively the application can be started by directly launching the executable jar:

$ java -jar smarti-${smarti-version}-exec.jar

Build and Run

This section explains how to checkout and build the Smarti application from its sources. By following these steps you will learn how to build, run and debug Smarti. Transfer these instructions on your local machine in order to start setting up your Software Development Environment (SDE).

In order to build & run Smarti the System requirements have to be fulfilled. How to achieve that heavily depends on your target environment. When creating this documentation all commands have been executed and tested with Ubuntu 16.04. LTS server running on Amazon EC2 instance (t2.large). Therefore and to keep it simple we decided to use Debian’s package manager apt-get for documentation purpose.

Note	If you have any trouble please have a look at Troubleshooting, maybe you’re not alone.

Warning

Be careful using copy & paste. The aim of this manual is to explain and not to provide scripts.

Prepare

1. Install Java

   $ sudo apt-get install openjdk-8-jdk

2. Install MongoDB (optional)

   $ sudo apt-get install mongodb-server

3. Install build components

   $ sudo apt-get install git maven ruby ruby-sass ruby-compass

Tip	For other operating systems check the installation manuals for the target platform: ✓ Git (git) ✓ Maven (maven) ✓ Ruby (ruby) and on top of ruby use its package manager gem to install sass and compass sudo gem install sass compass ✓ Sass (ruby-sass) ✓ Compass (ruby-compass)

Checkout

1. Create a source directory ${smarti-source}

   $ mkdir ${smarti-source}

2. Checkout Smarti source code from GitHub

   $ git clone https://github.com/redlink-gmbh/smarti.git ${smarti-source}

Build

1. Change into the source directory

   $ cd ${smarti-source}

2. Execute maven build

   $ mvn clean install [ -Pdeb | -Prpm ]

   Note	Installation packages can be built for Debian- and RedHat-based systems.

   Note	The build artifacts are finally placed in the ${smarti-source}/dist/target directory.

Run

1. Create a working directory

   $ mkdir ${smarti-work-dir} && cd ${smarti-work-dir}

   Note

   Working directory - If you launch smarti the first time the application.properties file is created inside the directory where java -jar is executed. When ever this documentation refers the ${smarti-work-dir}, the directory where the application.properties is located, is being meant. Since Smarti is a Spring boot application you can externalize the configuration as explained in the Spring docs.

2. Copy the executable jar into ${smarti-work-dir}

   $ mv ${smarti-source}/dist/target/smarti-${smarti-version}-exec.jar .

3. Launch smarti

   $ java -jar smarti-${smarti-version}-exec.jar

   Note	Stanford NLP - If you want to use Stanford NLP analysis, ensure that the required libraries are included in the class path. For more information and how to achieve this read section Enable Stanford NLP.

   Note	Common challenges - If this the first time you’re running Smarti, you may have been stepped into a pitfall and it does not work. We have picked up some common challenges that might be helpful. See sections Troubleshooting in any case of problems.

Debug

1. Launch smarti in debug mode

   To launch Smarti in debug mode create a shell script appending preferred options to the java-command like:

   start-smarti.sh

   #!/bin/bash
   java -Xmx4g -jar \
       -Xdebug -Xrunjdwp:transport=dt_socket,address=${smarti-debug-port},server=y,suspend=n\
       -Dspring.profiles.active=local\
       application/target/smarti-${smarti-version}-exec.jar\
       --solrlib.home=${solr-home}

2. Configure your IDE

   Create a debug configuration for the Remote Java Application and set the specified ${smarti-debug-port}.

   

---

Release

For a release, a release branch (based on develop) is created which represents the release candidate. If the candidate fulfills the requirements, the issues of the release are documented in the changelogs. Then the version number is set to the release number, the branch is merged into master and the master is tagged with the release number. Additionally, the version number of the develop branch is set to the new snapshot version.

Note	Now you are ready to start developing the next amazing feature for Smarti.

Caution

Read Additional Components section.