Deploy BuildVu with Jetty

Table of contents

1. Download or Build the WAR file
   1. Download the WAR file
   2. Build the WAR file
2. Deploying the web app
3. Usage
4. Storing the conversion state externally
   1. Setting up a datasource
      1. Installing the database Driver
      2. Configuring the datasource
      3. Configure the microservice

Download or Build the WAR file

Before getting started you need the WAR file which you can either download or build yourself.
This WAR file is required for the BuildVu service to work.

Download the WAR file

For trial users:

1. If you haven’t already, sign up for BuildVu trial.
2. Open the email you receive when you signed up.
3. Follow the download link found in the Docker section.

For customers:

1. Visit the Customer download page.
2. Click on ‘Download Latest Customer WAR’.
3. Submit your username and password.

Build the WAR file

Build a copy of our BuildVu Microservice Example project.
Instructions can be found on the GitHub page.

Deploying the web app

1. Download and install the latest version of Jetty 10 (Please note Jetty 11 and above is not supported due to their move to using Jakarta).
2. Create a new environment variable called JETTY_HOME for the Jetty home directory.
3. Create a directory to hold the jetty base content and enter that directory.
4. Set up the required modules using the following command.
   java -jar JETTY_HOME/start.jar --add-module=server,http,deploy,jsp
5. Move the war file into the webapps folder created in your jetty base directory.
   The name of the war file will be the base of your web app. For example, if the webserver is hosted at localhost:8080, buildvu-microservice.war will be deployed at localhost:8080/buildvu-microservice.
6. Start the Jetty server and navigate to the admin console in your browser.
   java -jar start.jar will start the server on localhost:8080

You can check if the web app has successfully deployed by navigating to its URL in your browser - you should see a blank white page with BuildVu Microservice Example written in the centre.

Usage

You can interact with the BuildVu Microservice Example using the REST API (See the GitHub page for details).

For specific languages, see our tutorials.

Storing the conversion state externally

In some cases you may want to store the state of the program externally in a database, for example you may want to preserve the program’s state in the event of a server failure.

In order to do this, you must create a datasource on Jetty and add it’s JNDI name to the microservice config.

Setting up a datasource

Installing the database Driver

First we need to install the database driver jar into $JETTY_HOME/lib/ext so it can be used as a datasource.

To load the driver and make it available to our servlet, we will have to start the jetty server with the modules: ext and plus.

• plus is needed as it contains the logic for JNDI to work (the feature that allows the microservice to find the datasource)
• ext loads all the jars in $JETTY_HOME/lib/ext onto the classpath, thus enables jetty to find the database driver.

These can be enabled by adding

--add-module=plus,ext

as a command line argument when running Jetty

Configuring the datasource

Open $JETTY_HOME/etc/jetty.xml, go to the bottom of the file (still within the Configure tag), and add:

<New id="ID" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg><Ref refid="wac"/></Arg>
  <Arg>JNDI_NAME</Arg>
  <Arg>
    <New class="DATASOURCE_CLASS">
      <Set name="url">JDBC_URL</Set>
    </New>
  </Arg>
</New>

JNDI_NAME is the JNDI Name to put in config, this typically starts with jdbc/, for example: jdbc/myDatabase.

JDBC_URL is the URL used to access the database. You should be able to find what this needs to look like in your database driver jar’s documentation, for SQLite, this would be jdbc:sqlite:/PATH/ON/DISK.db.

DATASOURCE_CLASS is the fully qualified class name of the driver’s Datasource class in the database driver jar, you should also be able to find this in your database driver jar’s documentation, for SQLite, this would be org.sqlite.SQLiteDataSource.

This <New class="DATASOURCE_CLASS"> element can also contain extra <Set> elements used to configure the driver, these can contain parameters such as the username and password. These are driver dependant, so you’ll find what options you have in your database driver’s documentation.

Configure the microservice

Finally, add the resource name you set in the previous step to the microservice config.