Bundle Tomcat in Your BitRock InstallBuilder installer

Published on

If you develop a Java Web Application, you may want to create an installer and redistribute Tomcat together with your software. This allows your users to avoid the time-consuming process of installing and configuring Tomcat in order to use your software and guarantees that the optimal version is used. In this article, we explain how to bundle Tomcat into a BitRock installer. We also provide the code so you can start with that and create an installer that not only installs your software but also configures the Tomcat server according to your requirements.

Product Details

We are going to create a demo installer for installing Tomcat. Of course, you can develop more advanced functionality than what we’ll show today, but in this installer we’ll focus on the basics. First, we are going to configure the Product Details of our installer. The License File will be shown at the beginning of the installation. The user must agree to it to be able to proceed with the installation process.

At the end of the installation process, an option to view the Readme file will appear if we provide a Readme File field in the Product Details section.

Check installation requirements

For this installer, we want to require the user to have a valid version of Java installed in the system to be able to continue the installation. For this, we will add an action to the pre-installation action list to look for Java in the system. The Autodetect Java action allows us to specify the minumum Java version required, vendor and if a JDK is required or if a JRE will also work.

Screen and validations (I)

Once we ensure that the user’s machine has the required software installed, we will ask the user for some information for the installation. We use the Parameters section for this.

We will prompt the user for:

  • Installation directory

  • Tomcat HTTP port

  • Tomcat Shutdown port

We will also add validation rules to check that the information provided by the user is correct.

Screen and validations (II)

Installation Directory

This parameter is created by default as it is used in most installations.

Screen and validations (III)

Tomcat Configuration

Next, we will ask the user which ports we should use for Tomcat. We want to prompt the user for the HTTP port and the Shutdown Port. To minimize the number of screens in the installation process, we will group these ports in a Parameter Group, which will ask for all parameters on one screen.

The internal name that we will use for this screen will be tomcat_configuration and the title will be ‘Tomcat Configuration’.

Screen and validations (IV)

We will use two String parameters. Each one will represent one of the ports that we want to configure.

We’ll focus on the tomcat_http_port. The steps for the tomcat_shutdown_port will be very similar. You will just need to change the default value and the description.

Screen and validations (V)

In order to ensure the application starts correctly once it is installed, we will check that the selected ports are free and can be used for the Tomcat configuration.

In the Validation Action for each port, we will add a Throw Error action. A Throw Error action usually exits the installer. However, the behavior is a bit different when it is used in a Validation Action context; after showing the error message, the installer will return to the screen allowing the user to re-enter the parameters.

In the Throw Error action we will configure the text that we want to show in case the selected port is already taken.

Screen and validations (VI)

In order to throw the error only if the port is not free, we will add a Port Test rule in the Throw Error action. The error will only be thrown if the condition ‘cannot bind to selected port’ is true. The port selected by the user is stored (according to the rest of the document) in the variable tomcat_http_port. We want to check its value, so in Port we will enter ${tomcat_http_port}.

The same steps are valid for the tomcat_shutdown_port.

Folders and Files (I)

The next step in the installation process will be to copy the Tomcat files to the user’s machine.

As Tomcat is a Java application, the same files will run on Windows and Linux. We’ll create a new InstallBuilder folder which will be installed in the installation directory selected by the user, ${installdir}. That will be installed in ‘All Platforms’ and we’ll add the Tomcat directory that we want to pack.

Folders and Files (II)

To make it easier for the user to start and stop Tomcat, we have created some start/stop scripts.

These scripts differ for each platform, so we’ll add two new folders: one setting Linux as platform and the other setting Windows as platform.

You can set the description and shortname you prefer for each folder. In both cases the destination of these scripts will be ${installdir}.

Folders and Files (III)

Now you will need to add the script files for each platform: .sh for the Linux folder and .bat for the Windows folder.

Windows Start Menu Entries (I)

In the File section we can also configure the Start Menu entries for our application.

We’ll add entries for:

  • Start Tomcat: This will be an ‘application’ type shortcut pointing to the start .bat script we are including.

  • Stop Tomcat: This will be an ‘application’ type shortcut pointing to the stop .bat script we are including.

  • Uninstall Tomcat: This will be an ‘application’ type shortcut pointing to the uninstaller.

  • Launch Tomcat application: This will be a ‘url’ type shortcut pointing to the url where the Tomcat application can be accessed.

Windows Start Menu Entries (II)

Windows Start Menu Entries (III)

Post Installation Actions (I)

Once the files are copied to the user system, we need to implement some additional configuration steps:

  • Configure Tomcat to use the ports selected by the user.

  • Set the right executable permissions for the Tomcat binaries on Linux.

  • Get JAVA_HOME in order to configure the startup and stop scripts to use the correct Java version.

  • Configure the start and stop scripts to use the right JAVA_HOME.

  • On Linux, set the correct permissions for the start and stop scripts.

Post Installation Actions (II)

The main Tomcat configuration file is server.xml. In this file we can configure the ports Tomcat is using. We will use substitution actions for this.

By default, server.xml contains hard-coded references to 8080 and 8005. These ports represent the http port and the shutdown port respectively.

With the substitution actions, we will replace 8080 with the value of the port selected by the user for the HTTP request and 8005 with the value of the port selected by the user for the Shutdown port. In our example, these values are stored in ${tomcat_http_port} and ${tomcat_shutdown_port}.

Post Installation Actions (III)

Post Installation Actions (IV)

Now, we will add write permissions to the Tomcat executable files in the bin folder. Note that this action will only take effect in Unix platforms so we don’t need to add a rule for not executing it on Windows.

Post Installation Actions (V)

At the beginning of the installation, we detected Java. InstallBuilder will create an internal variable named java_executable. However, according to the Tomcat documentation, we need to set the JAVA_HOME variable.

We’ll use a regular expression for getting the right value of JAVA_HOME.

Post Installation Actions (VI)

Previously, when we created the start/stop scripts, we used patterns that will be replaced during the installation process with the correct value. We will now replace those patterns with the path to CATALINA_HOME and the path to JAVA_HOME. This is also valid for both Linux and Windows.

Post Installation Actions (VII)

Finally, we will give executable permissions to the start and stop scripts on Linux. With this, we finish with the post installation configuration steps.

Final Page

Once the installation is complete, we will offer the user the option of starting Tomcat. If the user opts to do so, on Linux we will execute the start.sh script, while on Windows we will execute the start.bat script. When the Tomcat server has been started, we will open the browser and show the user that Tomcat is working.

Build

Now we can build our multiplatform installers and give them a try. By default, the installers will be created in your InstallBuilder directory, in the ‘output’ folder.

Resources