Getting Started with ThingWorx > Installing and Upgrading ThingWorx > Ubuntu Installation > H2/Azure SQL > Install Java and Apache Tomcat (Ubuntu)
Install Java and Apache Tomcat (Ubuntu)
In the steps below, replace xx or xxx with the build number you are using.
1. Update Ubuntu packages:
$ sudo apt-get update
2. Install and Configure Network Time Protocol (NTP) settings for time synchronization:
$ sudo apt-get install ntp
The default configuration for NTP is sufficient. For additional configuration information about NTP (beyond the scope of this documentation), refer to the following resources:
3. Edit AUTHBIND properties to allow Tomcat to bind to ports below 1024:
$ sudo apt-get install authbind
4. Download the appropriate Java JDK tar file from Oracle’s website.
Refer to the System Requirements document for version requirements.
5. Extract tar file:
$ tar -xf jdk-8uxxx-linux-x64.tar.gz
6. Create the directory by moving the JDK to /usr/lib/jvm:
If the directory is not empty, a warning message will display.
$ sudo mkdir -p /usr/lib/jvm
$ sudo mv jdk1.8.0_xxx/ /usr/lib/jvm/
7. Add alternatives to the system:
$ sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.8.0_xxx/bin/java" 1
$ sudo update-alternatives --install "/usr/bin/keytool" "keytool" "/usr/lib/jvm/jdk1.8.0_xxx/bin/keytool" 1
8. Change access permissions:
$ sudo chmod a+x /usr/bin/java
$ sudo chmod a+x /usr/bin/keytool
9. Change owner:
$ sudo chown -R root:root /usr/lib/jvm/jdk1.8.0_xxx/
10. Configure master links:
$ sudo update-alternatives --config java
$ sudo update-alternatives --config keytool
Nothing to configure is a normal response to this command and is not an error. Additional executables in /usr/lib/jvm/jdk1.8.0_xxx/bin/ can be installed using the previous set of steps.
11. Verify Java version:
$ java -version
This should return something similar to the following (build specifics may be different):
java version "1.8.0_xxx"
Java(TM) SE Runtime Environment (build 1.8.0_xxx-bxx)
Java HotSpot(TM) 64-Bit Server VM (build 24.75-bxx, mixed mode)
12. Download Apache Tomcat:
This steps in this process use Tomcat 8.5.xx, where xx is replaced with the version you are using.
$ wget
Best practice includes verifying the integrity of the Tomcat file by using the signatures or checksums for each release. Refer to Apache’s documentation for more information.
13. Extract tar file:
$ tar -xf apache-tomcat-8.5.xx.tar.gz
14. Create and change the owner for /usr/share/tomcat8.5 and move Tomcat to the following location. Add user and group to the system:
$ sudo mkdir -p /usr/share/tomcat8.5
$ sudo mv apache-tomcat-8.5.xx /usr/share/tomcat8.5/8.5.xx
$ sudo addgroup --system tomcat8.5 --quiet -force-badname
$ sudo adduser --system --home /usr/share/tomcat8.5/ --no-create-home --ingroup tomcat8.5 --disabled-password --force-badname --shell /bin/false tomcat8.5
$ sudo chown -R tomcat8.5:tomcat8.5 /usr/share/tomcat8.5
15. Define environment variables in /etc/environment:
$ export JAVA_HOME=/usr/lib/jvm/jdk1.8.0_xxx
$ export CATALINA_HOME=/usr/share/tomcat8.5/8.5.xx
16. Change directory to $CATALINA_HOME:
17. Change owner and access permissions of bin/, lib/, and webapps/:
$ sudo chown -Rh tomcat8.5:tomcat8.5 bin/ lib/ webapps/
$ sudo chmod 775 bin/ lib/ webapps/
18. Change owner and access permissions of conf/:
$ sudo chown -Rh root:tomcat8.5 conf/
$ sudo chmod -R 650 conf/
19. Change access permissions of logs/, temp/, and work/:
$ sudo chown -R tomcat8.5:adm logs/ temp/ work/
$ sudo chmod 760 logs/ temp/ work/
20. Create self-signed certificate:
$ sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat8.5 -keyalg RSA -keystore $CATALINA_HOME/conf/.keystore
21. Follow the instructions to complete the certificate creation process.
Set the keystore password.
Follow the prompts to set up your security certificate.
Set the tomcat8.5 user password to the same as the keystore password:
$ sudo chown root:tomcat8.5 $CATALINA_HOME/conf/.keystore
$ sudo chmod 640 $CATALINA_HOME/conf/.keystore
22. Uncomment the Manager element in $CATALINA_HOME/conf/context.xml to prevent sessions from persisting across restarts:
<Manager pathname="" />
23. Comment out the following non-SSL Connector:
sudo vi $CATALINA_HOME/conf/server.xml

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
If you receive an error that the directory doesn’t exist, use the following commands to ensure port 443 works:
sudo touch /etc/authbind/byport/443
sudo chmod 700 /etc/authbind/byport/443
sudo chown tomcat8.5:tomcat8.5 /etc/authbind/byport/443
24. Modify the shutdown string and protocol used by the SSL Connector in server.xml by pasting in the following information below the code that was commented out in the previous step. Enter your <keystore password> that was previously set:
sudo vi $CATALINA_HOME/conf/server.xml
<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
keystoreFile="${user.home}/8.5.xx/conf/.keystore" keystorePass="<keystore password> " clientAuth="false" sslProtocol="TLS" />
25. Define a user in $CATALINA_HOME/conf/tomcat-users.xml:
sudo vi $CATALINA_HOME/conf/tomcat-users.xml
<user username="<Tomcat user name> " password="<Tomcat password> " roles="manager"/>
26. Determine uid of tomcat8.5 user:
$ id -u tomcat8.5
27. Using this number, create an ID file in /etc/authbind/byuid/:
Change the <uid> to the number that was returned in the previous step.
$ sudo touch /etc/authbind/byuid/<uid>
sudo vi /etc/authbind/byuid/<uid>
28. Edit the file from the step above and paste in the following:,1023
29. Change owner and access permissions of /etc/authbind/byuid/<uid>:
$ sudo chown tomcat8.5:tomcat8.5 /etc/authbind/byuid/<uid>
$ sudo chmod 700 /etc/authbind/byuid/<uid>
30. Modify $CATALINA_HOME/bin/ to always use authbind:
sudo vi $CATALINA_HOME/bin/
Comment the following in the file:
#exec "$PRGDIR"/"$EXECUTABLE" start "$@"
31. Add the following to the end of the file:
exec authbind --deep "$PRGDIR"/"$EXECUTABLE" start "$@"
32. In /etc/init.d, create tomcat8.5 file:
$ sudo touch /etc/init.d/tomcat8.5
33. Edit the file and enter the following contents:
$ sudo vi /etc/init.d/tomcat8.5


case $1 in
/bin/su -p -s /bin/sh tomcat8.5 $CATALINA_HOME/bin/

/bin/su -p -s /bin/sh tomcat8.5 $CATALINA_HOME/bin/

/bin/su -p -s /bin/sh tomcat8.5 $CATALINA_HOME/bin/
/bin/su -p -s /bin/sh tomcat8.5 $CATALINA_HOME/bin/

exit 0
34. Change access permissions of etc/init.d/tomcat8.5 and create symbolic links:
$ sudo chmod 755 /etc/init.d/tomcat8.5
$ sudo ln -s /etc/init.d/tomcat8.5 /etc/rc1.d/K99tomcat
$ sudo ln -s /etc/init.d/tomcat8.5 /etc/rc2.d/S99tomcat
35. Set up Tomcat as a service to start on boot. First, build JSVC:
This may already be installed on your system. If so, skip and go to the next step.
$ sudo apt-get install gcc
36. Set up the Tomcat service on boot:
$ cd /usr/share/tomcat8.5/8.5.xx/bin/
$ sudo tar xvfz commons-daemon-native.tar.gz
$ cd commons-daemon-*-native-src/unix
$ sudo ./configure --with-java=$JAVA_HOME
$ sudo apt-get install make
$ sudo make
$ sudo cp jsvc ../..
37. Create the Tomcat service file:
sudo touch /etc/systemd/system/tomcat8.5.service
38. Open /etc/systemd/system/tomcat8.5.service in a text editor (as root):
sudo vi /etc/systemd/system/tomcat8.5.service
39. Paste the following in the Tomcat service file:
Description=Apache Tomcat Web Application Container


ExecStart=/usr/share/tomcat8.5/8.5.xx/bin/jsvc \
-Dcatalina.home=${CATALINA_HOME} \
-Dcatalina.base=${CATALINA_BASE} \
-Djava.awt.headless=true -Dserver -Dd64 -XX:+UseNUMA \
-XX:+UseG1GC -Dfile.encoding=UTF-8 \
-Djava.library.path=${CATALINA_BASE}/webapps/Thingworx/WEB-INF/extensions \
-cp ${CATALINA_HOME}/bin/commons-daemon.jar:${CATALINA_HOME}/bin/bootstrap.jar:${CATALINA_HOME}/bin/tomcat-juli.jar \
-user tomcat8.5 \
-java-home ${JAVA_HOME} \
-pidfile /var/run/ \
-errfile ${CATALINA_HOME}/logs/catalina.out \
-outfile ${CATALINA_HOME}/logs/catalina.out \

40. Create a new file in the tomcat /bin file named
sudo touch
sudo vi
CATALINA_OPTS=$CATALINA_OPTS -Djava.library.path="/usr/share/tomcat8.5/8.5.xx/webapps/Thingworx/WEB-INF/extensions"
41. In the location of the Tomcat installation, open CATALINA_HOME/conf/web.xml. Replace the default error page (default is stacktrace) by adding the following into the web.xml file. Place the following within the web-app tag (after the welcome-file-list tag ). A well-configured web application will override this default in CATALINA_HOME/webapps/APP_NAME/WEB-INF/web.xml so it won't cause problems.
42. Remove all Tomcat example apps located in /<path_to_tomcat>/webapps/examples/.
These apps should be removed to prevent unnecessary access to Tomcat, specifically in the context that would allow users to view other users cookies.
43. (OPTIONAL STEP) To increase the default cache settings that affect static file caching, add the following line within the <context></context> tags in the $CATALINA_HOME/conf/context.xml file:
<Resources cacheMaxSize="501200" cacheObjectMaxSize="2048" cacheTtl="60000"/>
Increasing this setting improves performance and avoids the following message in Tomcat:
WARNING: Unable to add the resource at [/Common/jquery/jquery-ui.js] to the cache because there was insufficient free space available after evicting expired cache entries - consider increasing the maximum size of the cache
44. H2/Azure SQL only: Go to Install ThingWorx.
45. PostgreSQL only: Go to Install and Configure PostgreSQL.