Setup development environment on Linux (Ubuntu 22.04.1)

The following instructions use ~/dev/ as a project folder and require superuser privileges (sudo)

Most instructions/explanations are copied from the MacOS page

Install Git

Likely already installed, but if not:

sudo apt update

sudo apt install git

Install Java

Install Java JDK (Java 8 is required, and there may be problems with 9 and upwards)

sudo apt install openjdk-8-jdk

Configure the JAVA_HOME environment variable, add the following line to /etc/environment:

JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64"

Log out and back in to have the change take effect

Install Maven

sudo apt install maven

Install Tomcat

(Don’t use apt! I learned the hard way – see Troubleshooting at the bottom)

I downloaded the latest .tar.gz from this website: https://tomcat.apache.org/download-90.cgi

I referred to this link for installation steps https://www.rosehosting.com/blog/how-to-install-tomcat-on-ubuntu-22-04/

A summary:

1. Extract files to /opt/tomcat

   1. In the directory with the tar file, run sudo -u tomcat tar -xzvf <tomcat9>.tar.gz --strip-components=1 -C /opt/tomcat

2. Create a systemd service file for Tomcat

   1. sudo vim /etc/systemd/system/tomcat.service

   2. Paste the following

      1. [Unit] Description=Apache Tomcat After=network.target [Service] Type=forking User=tomcat Group=tomcat Environment=JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-amd64 Environment=CATALINA_PID=/opt/tomcat/tomcat.pid Environment=CATALINA_HOME=/opt/tomcat Environment=CATALINA_BASE=/opt/tomcat Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC" ExecStart=/opt/tomcat/bin/startup.sh ExecStop=/opt/tomcat/bin/shutdown.sh ExecReload=/bin/kill $MAINPID RemainAfterExit=yes [Install] WantedBy=multi-user.target

          

   3. Save the file and exit

3. Make systemd aware of the new file

   1. sudo systemctl daemon-reload

   2. sudo systemctl start tomcat

   3. sudo systemctl status tomcat

   4. Visit http://localhost:8080/ and you should see a confirmation page

4. I also followed the steps to create a web manager user, but I don’t believe it’s necessary to continue

5. Make sure to stop Tomcat before you try running it with IntelliJ later!

   1. sudo systemctl stop tomcat

Install stand-alone version of STEP

Go to https://www.stepbible.org/downloads.jsp and select “Linux (.deb)” under “Operating system”. Download, navigate to the directory, and install with the following command:

sudo dpkg -i stepbible_2_1_49.deb (or whatever the exact filename is)

Installing the stand-alone version of STEP will install a few Bible modules (ESV, SBLG, OHB, ...) which is required to run STEP. If you do not install the stand-alone version of STEP, you will not have any Bible modules and the development environment will not start.

Clone repositories

JSword: https://github.com/STEPBible/jsword

STEP: https://github.com/STEPBible/step

In ~/dev/, run

git clone git@github.com:STEPBible/step.git

git clone git@github.com:STEPBible/jsword.git

We are not using the “master” branch for JSword , so you will need to switch branches:

cd jsword

git checkout jsword-stepbible-2022

Build the code

Build JSword source code first!

cd ~/dev/jsword

mvn clean install -DskipTests=true

Then build STEP

cd ~/dev/step

mvn clean install -DskipTests=true

Install IntelliJ IDEA Community Edition

The Community Edition is free and seems to have all the Java development functions.  The Community Edition cannot debug jsp files but we rarely change our jsp files. 

Download the .tar.gz file from here: http://www.jetbrains.com/idea/download/

Extract it to /opt

sudo tar -xzf -C /opt/

There is a file /opt/idea-IC-223.8617.56/Install-Linux-tar.txt with instructions from the InteliiJ team. What I did was:

1. Run ./idea.sh for first-time launch

2. Click Tools > Create Desktop Entry so you have a clickable launcher

Import JSword as a project into IntelliJ

1. File > New > Project from Existing Sources

2. Find and select the JSword directory (in my case, ~/dev/jsword)

3. Select “Import project from external model” as “Maven”

4. Click “Create”

Import STEP as a module into IntelliJ

1. File > New > Module from Existing Sources

2. Find and select the STEP directory (in my case, ~/dev/step)

3. Select “Import project from external model” as “Maven”

4. Click “Create”

Configure IntelliJ’s SDK to Java 1.8

1. File > Project Structure > Platform Settings > SDKs

2. Select Java 1.8

Install Smart Tomcat plugin

1. File > Settings > Plugins

2. Search for “Smart Tomcat” and install it

Create a Run/Debug configuration with data loading

This will load data and create search indexes, will take some time.

1. Run > Run … > Edit configurations > “+” (top left) > Smart Tomcat

2. Change Name to “Step - data load” and Context path to “/”

3. Click “Configure…” for Tomcat server and a new window pops up

4. Click “+” and find the Tomcat folder (/opt/tomcat)

   1. You will first need to give the current user permissions to view the folder!

   2. sudo usermod -aG tomcat <USERNAME>

   3. Log out and back in to have the group membership change take effect

   4. You will also need to change permissions on /opt/tomcat/conf and its contents

   5. sudo chmod g+rx /opt/tomcat/conf

   6. sudo find /opt/tomcat/conf -maxdepth 1 -type f -exec sudo chmod g+r {} \;

5. Click “OK”, and in the original window select the Tomcat server you just identified

6. Add VM options: -XX:ReservedCodeCacheSize=64m -Dstep.loader=true -Dstep.skipBookInstallation=true -Dstep.setup.password=P@ss0rd2o14T0pl@dyLuthe3 -Djava.awt.headless=true -XX:+UseG1GC -Dfile.encoding=UTF-8 -Xms512M -Xmx512M

7. Click “Apply” then “Run”

If everything works, a link should appear in the console and STEP should now be running at http://localhost:8080/?debug

Create a Run/Debug configuration without data loading

This will restart STEP without creating/refreshing all your search indexes.

1. Run > Run … > Edit configurations

2. Select “Step - data load” and click the copy icon above it

3. Make the following changes

   1. Name: “Step - no data load”

   2. VM options: -XX:ReservedCodeCacheSize=64m -Dstep.development=true -Dstep.skipBookInstallation=true -Dstep.setup.password=P@ss0rd2o14T0pl@dyLuthe3 -Djava.awt.headless=true -XX:+UseG1GC -Dfile.encoding=UTF-8 -Xms512M -Xmx512M

4. Click “Apply” and “Run”

Troubleshooting tips (that I had to discover and use myself)

IntelliJ run failure, “Address already in use”

• Stop the tomcat (sudo systemctl stop tomcat9) before hitting “Run”

I want to reset and re-import my repository because I messed stuff up

• Close the project and remove it from “Recent Projects” (File > Recent Projects > Manage Projects > Gear Icon)

• Delete the .idea/ directory in the repository

• Now re-add it. You maybe prompted to re-build the project because of the missing directory

java.lang.UnsupportedClassVersionError: org/eclipse/jdt/internal/compiler/env/INameEnvironment has been compiled by a more recent version…

• I originally installed tomcat9 via apt, but it seems like I hit a known bug (

  • https://bugs.launchpad.net/ubuntu/+source/tomcat9/+bug/1972829

  • https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1006647

• The workaround in the first link didn’t work for me… So I re-traced my steps

  • (undoing the workaround)

    • sudo apt remove libecj-java

    • sudo unlink /var/lib/tomcat9/lib/ecj.jar

  • (undoing another workaround for Smart Tomcat, if you used apt)

    • sudo unlink /usr/share/tomcat9/conf

  • (removing tomcat via apt)

    • sudo apt purge tomcat9 tomcat9-admin (purge removes config files too)

  • (remove user and group automatically added by apt)

    • sudo userdel tomcat

    • sudo groupdel tomcat