Deploy BuildVu with Tomcat

Table of contents

1. Download or Build the WAR file
   1. Download the WAR file
   2. Building the WAR file
2. Deploying the web app
3. Usage
4. Storing the conversion state externally
   1. Create a datasource

---

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

Download the buildvu-microservice.war file.

Trial users can find the war download in the Docker section after trial signup.

Building 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 Tomcat. (Versions tested: 8.5.x, 9.0.x, 10.0.x)
2. Copy the built .war file into the apache-tomcat-x.x.x/webapps/ directory (apache-tomcat-x.x.x/webapps-javaee/ for Tomcat 10¹).
3. Tomcat will then automatically deploy the application upon startup, using the name of the .war file as the context path.
4. Open a command line/terminal window and navigate to apache-tomcat-x.x.x and run the command bin/startup which will start the server on port 8080.
   • Check the RUNNING.txt file supplied with Tomcat for detailed instructions.
5. You can check if the web app has successfully deployed by navigating to its URL in your browser e.g. http://localhost:8080/buildvu-microservice. The page displayed should be blank white with BuildVu Microservice Example written in the centre.

¹ Tomcat 10 has moved from Java EE 8 to Jakarta EE 9. Upon startup Tomcat 10 will then automatically convert war files in webapps-javaee to a Jakarta web application and deploy it, using the name of the .war file as the context path.

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.

Note: Viewing / downloading the converted output may not work on the first try - this is usually because Tomcat has not yet registered the new directories created by the web app. To fix this, simply restart your Tomcat server.

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 Tomcat and add it’s JNDI name to the microservice config.

Create a datasource

1. First put the database driver jar into $CATALINA_HOME/lib so tomcat is able to use it.
2. Next edit $CATALINA_HOME/conf/context.xml and add at the bottom (but still within the context tags):

   <Resource name="JNDI_NAME" auth="Container" type="javax.sql.DataSource"
         url="JDBC_URL"
         driverClassName="DRIVER_CLASS"/>
   

   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.

   DRIVER_CLASS is the fully qualified class name of the main driver 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.JDBC.

   This resource element can also contain extra attributes used to configure your 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.

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

---