Tutorial: WOOL Web Service - Installation

This tutorial was last updated on November 16, 2021.

The WOOL Web Service is a JAVA Spring Boot Application that can be deployed as a web service. It acts as a wrapper around the WOOL Core Library, offering an API that allows you to create client-server dialogue applications.

In this tutorial you will learn how to set up the WOOL Web Service on a local machine with your own user account and dialogues.

As of the writing of this tutorial there are no official releases of the WOOL Web Service. This tutorial is based on the latest source code in our GitHub WOOLPlatform page.

1. Prerequisites

Before you get started, make sure you have the following tools installed:

  • Java (OpenJDK 16+)

  • Apache Tomcat (8.5 or 9.0)

Below we explain how to set up Java and Tomcat. If you’re already have these tools, you can skip ahead to the "Download and Configure" step.

1.1. Java

The web service was tested with OpenJDK 16.

1.1.1. Windows

  • Download the ZIP file of the latest version of the Java OpenJDK from the Archived OpenJDK General-Availability Releases page.

  • Extract the .zip archive and move it to somewhere easy to locate, e.g.: C:\apps\jdk-16.0.1

  • Set an Environment Variable JAVA_HOME to this directory (e.g. C:\apps\jdk-16.0.1).

  • Add the bin directory to your path (e.g. C:\apps\jdk-16\bin).

You should now be able to run Java from the command prompt. Check to see if the version matches the one you installed, e.g.:

> java -version
If you need help setting Environment Variables in Windows, see e.g. the official Java help pages.

1.1.2. MacOS

Install OpenJDK using homebrew with the following command:

brew install openjdk
If you don’t have homebrew or need help setting it up, please visit the official homebrew site.

1.2. TOMCAT

The web service was tested with Tomcat 8.5 and Tomcat 9.0.

The WOOL Web Service is, as of yet, not compatible with Tomcat 10.0.

1.2.1. Windows

  • Visit the Apache Tomcat Downloads page and download the latest version of Tomcat. Choose the 32-bit/64-bit Windows Service Installer.

  • Run the installer (e.g. apache-tomcat-9.0.55.exe), pay attention to the following:

    • When asked to "Choose Components", make sure to include the following:

      • Check the box next to Tomcat > Service Startup so Tomcat is started automatically when the computer is started.

      • Check the box next to Host Manager. This is needed to deploy web applications from the Gradle build file.

    • On the next screen, we should configure some items:

      • At Tomcat Administrator Login fill in a user name (for example "admin") and a secure password.

      • Set "Roles" to: admin-gui,manager-gui,admin-script,manager-script. The additional script roles are needed to support automatic deployment of web services through a Gradle script.

    • On the next screen, provide the directory where your Java JDK is installed (e.g. C:\apps\jdk-16).

    • Finally, choose an installation folder for Tomcat, e.g. C:\apps\Tomcat 9.0.

Next, we do some final configuration of the JDK location, Java options and Memory Size:

  • From the Windows start menu, open Monitor Tomcat. If you get a permission error, you may need to open the Tomcat folder in Windows Explorer first, e.g. C:\apps\Tomcat 9.0. The Tomcat monitor opens in the notification area of the task bar.

  • Open the Tomcat monitor from the task bar.

  • Open the tab Java.

  • Make sure the Initial memory pool and Maximum memory pool are set to some reasonable amount (e.g. 512 and 2048). If this is too low, the Java process may run out of memory while executing the WOOL Web Service. Click Apply and close the configurator.

webservice setup tutorial 0 tomcatproperties
Figure 1. The Tomcat Monitor - Java settings tab on Windows.

Verify the installation by opening a Web Browser and visiting http://localhost:8080/. You should see a webpage that says "If you’re seeing this, you’ve successfully installed Tomcat. Congratulations!". Now, click on Host Manager and login using the admin credentials set earlier. You should be able to login and see the Tomcat Virtual Host Manager.

1.2.2. MacOS

  • Type brew install tomcat@9 to install the latest version of Tomcat 9 on your device.

  • Locate the tomcat configuration files (by default in /usr/local/etc/tomcat@9).

  • Edit the tomcat-users.xml file and define an admin user, e.g.

    <user username="admin" password="<must-be-changed>" roles="admin-gui,manager-gui,admin-script,manager-script"/>
  • Restart tomcat using the brew services restart tomcat@9 command.

Verify the installation by opening a Web Browser and visiting http://localhost:8080/. You should see a webpage that says "If you’re seeing this, you’ve successfully installed Tomcat. Congratulations!". Now, click on Host Manager and login using the admin credentials set earlier. You should be able to login and see the Tomcat Virtual Host Manager.

2. Download and Configure

Once you have Java and Tomcat installed, we can proceed to downloading, and configuring the WOOL Web Service.

  • Clone the wool repository to your local machine, e.g.: <GITDIR>\wool\

The web service is configured with this file that needs to be created:

<GITDIR>\wool\java\WoolWebService\gradle.properties

The folder contains a sample properties file, which you can rename to "gradle.properties", and edit it:

<GITDIR>\wool\java\WoolWebService\gradle.sample.properties

First, set the woolConfigBaseUrl to reflect our local deployment, e.g.:

woolconfigBaseUrl=http://localhost:8080/wool

In order to set an appropriate value for the woolconfigJwtSecretKey you can use the key generator available in the BuildTools folder.

  • Start a Windows Powershell (Windows) or a Terminal (Mac/Linux) and navigate to the following folder: <GITDIR>\wool\java\BuildTools\BuildTools-1.0.0\.

  • Enter the following command: > ./keygenerator -t base64 -s 1024

  • The output is a secure base64 key with a length of 1024 bits, e.g:

    woolconfigJwtSecretKey=Gz/QP51QcE694/ehuppfV4vSt3L9OfXtcl6WHy/8agce44DyzUoqoOJSI+gGEPusfYsMMK6TJTsL8z1/ADK232Jh9QE9tSVp1aDMduo3v8j1vrAgYTHq+whSJkl6uQfYIQF92FqgyJk9CMUC6SAw1h7EvdDaaRx9dmMXpsIRToo=

Next, define the woolconfigDataDir, which is a directory where certain configuration files for the WOOL Web Service should be placed, and where log data is stored, e.g.

woolconfigDataDir=/users/username/wool/web-service/data

Only authenticated users can access the WOOL Web Service API. The usernames and passwords are loaded from an XML file that should be placed in this configured data dir (<DATADIR>\users.xml).

An example users.xml file can be found in <GITDIR>\wool\java\WoolWebService\config\users.xml. Change the default user and password, or add any additional users as you see fit.

3. Deploying the Web Service

Make sure that Tomcat is running before proceeding with this step.

3.1. Gradle Configuration

The web service is deployed with Gradle task cargoRedeployRemote. This Gradle task allows you to deploy the WOOL Web Service to a (local or remote) Tomcat server that has the Host Manager feature enabled. For now we will deploy to our locally running Tomcat server, which requires us to set the following parameters in gradle.properties:

  • tomcatDeployPath=wool - The path where the web service will run, make sure this matches the setting for woolConfigBaseUrl.

  • remoteTomcatHost=localhost - The tomcat host address, for now we will deploy to our local machine, so you can keep it as is. If you have an external server where you want to deploy to, you can change this host address.

  • remoteTomcatPort=8080 - Choose the port as configured during the Tomcat installation. If you followed this tutorial, you can leave this as is.

  • remoteTomcatUser=admin - The administrator username for Tomcat Host as configured during the Tomcat installation.

  • remoteTomcatPassword=SECRET - The administrator password for Tomcat Host.

3.2. Deploying

After completing this configuration, open a Terminal/Command Prompt in <GITDIR>\wool\java\WoolWebService and enter this command:

> .\gradlew build cargoRedeployRemote

If you want to make a clean build and deploy, then enter:

> .\gradlew clean build cargoRedeployRemote

Logging is done using Logback (http://logback.qos.ch/). This is configured in <GITDIR>\wool\java\WoolWebService\src\main\resources\logback.xml. With this configuration, log files are written to the directory that you set in woolconfigDataDir in gradle.properties.

After deploying you can access the Swagger interface at: http://localhost:8080/wool/, which should look something like this:

webservice setup tutorial 1 swagger
Figure 2. If deployed correctly, this is what you should be seeing - the Swagger API Documentation of the WOOL Web Service.

3.3. Troubleshooting

If you cannot access the Swagger interface or the deployment showed errors, perform the following checks:

  • If the deployment did not show any errors:

  • If the deployment did show errors:

    • Is your Tomcat running? If it is, going to http://localhost:8080/manager/html should result in a request for a username and password.

    • Are your Tomcat username and password correct? You can verify this by logging into the manager window at the URL in the previous step.

    • Check if your gradle.properties file has been configured correctly. (See notes above.)

4. What’s next?

Now that you have the WOOL Web Service running, it’s time to start using it. As a next step we recommend checking the Getting Started Tutorial.

If you found errors or have questions about this tutorial, please consider reporting an issue at https://github.com/woolplatform/wool-documentation or sending an email to info@woolplatform.eu. Thank you!