Installing ThingWorx 7.4 1
Installing ThingWorx 7.4 1
4
Version 1.2
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.
User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively "PTC")
are subject to the copyright laws of the United States and other countries and are provided under a license
agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed
software user the right to make copies in printed form of this documentation if provided on software media, but only
for internal/personal use and in accordance with the license agreement under which the applicable software is
licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC.
Training materials may not be copied without the express written consent of PTC. This documentation may not be
disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly
available by any means without the prior written consent of PTC and no authorization is granted to make copies for
such purposes. Information described herein is furnished for general information only, is subject to change without
notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability
for any errors or inaccuracies that may appear in this document.
The software described in this document is provided under written license agreement, contains valuable trade secrets
and proprietary information, and is protected by the copyright laws of the United States and other countries. It may
not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for
in the software licenses agreement except with written prior approval from PTC.
UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND
CRIMINAL PROSECUTION.
PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of
PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available,
including public and private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring
technologies to obtain and transmit data on users of illegal copies of our software. This data collection is not
performed on users of legally licensed software from PTC and its authorized distributors. If you are using an illegal
copy of our software and do not consent to the collection and transmission of such data (including to the United
States), cease using the illegal version, and contact PTC to obtain a legally licensed copy.
Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of
your PTC software.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 1
Installing ThingWorx 7.4
Installing ThingWorx
Document Revision History........................................................................................................................... 1
Prerequisites ................................................................................................................................................. 4
Upgrading...................................................................................................................................................... 4
Database Options: PostgreSQL, Microsoft SQL Server, SAP HANA, or H2 .................................................... 4
High Availability Option ................................................................................................................................ 4
Installing ThingWorx for the First Time: H2 or PostgreSQL on Windows ..................................................... 5
Installing Oracle Java and Apache Tomcat (Windows) ............................................................................. 5
Installing and Configuring PostgreSQL (Windows) ................................................................................... 9
Installing PostgreSQL and Creating a New User Role in PostgreSQL (Windows).................................. 9
Configuring PostgreSQL Database Located on a Separate Server than Thingworx (Windows) ......... 10
Configuring and Executing the PostgreSQL Database Script (Windows) ............................................ 11
Configuring and Executing the Model/Data Provider Schema Script (Windows)............................... 13
Configuring platform-settings.json (Windows) ................................................................................... 14
Encrypting the PostgreSQL Password (Windows) ............................................................................... 15
Installing ThingWorx (Windows) ............................................................................................................. 16
Installing ThingWorx for the First Time: PostgreSQL or H2 on Ubuntu ...................................................... 16
Installing Oracle Java and Apache Tomcat (Ubuntu) .............................................................................. 16
Installing and Configuring PostgreSQL (Ubuntu) .................................................................................... 23
Installing PostgreSQL and Creating a New User Role in PostgreSQL (Ubuntu) .................................. 23
Configuring PostgreSQL Database Located on a Separate Server from Thingworx (Ubuntu) ............ 25
Enabling PostgreSQL to Listen for all Connections (Linux) ................................................................. 26
Configuring and Executing the PostgreSQL Database Script (Ubuntu) ............................................... 27
Configuring and Executing the Model/Data Provider Schema Script (Ubuntu) ................................. 28
Configuring platform-settings.json (Ubuntu)...................................................................................... 29
(OPTIONAL) Encrypting the PostgreSQL Password (Ubuntu) ............................................................. 29
Installing ThingWorx (Ubuntu) ................................................................................................................ 30
Installing and Configuring ThingWorx for the First Time: PostgreSQL or H2 on Red Hat Enterprise Linux
(RHEL) .......................................................................................................................................................... 32
Installing Oracle Java and Apache Tomcat (RHEL) .................................................................................. 32
Installing and Configuring PostgreSQL (RHEL) ........................................................................................ 38
Installing PostgreSQL and Creating a New User Role in PostgreSQL (RHEL) .......................................... 38
Configuring PostgreSQL Database Located on a Separate Server than ThingWorx (RHEL) ................ 41
Enabling PostgreSQL to Listen for all Connections (Linux) ................................................................. 42
(OPTIONAL) Encrypting the PostgreSQL Password (RHEL) ................................................................. 42
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 2
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 3
Installing ThingWorx 7.4
Prerequisites
Prerequisite software includes Apache Tomcat and Oracle Java. PostgreSQL is also required if you are
not using H2, MS SQL Server, or SAP HANA for your database. If you are installing ThingWorx for the first
time, this document provides step-by-step installation instructions for your environment.
Upgrading
If you are upgrading to a newer version, refer to the Upgrading ThingWorx guide.
NOTE: If you are not using PostgreSQL or H2 for your database, refer to the following guides for
additional installation and configuration information:
o SAP HANA: Getting Started with SAP HANA and ThingWorx Guide
o Microsoft SQL Server: Getting Started with MS SQL Server and ThingWorx Guide
For additional information on database options, see the Persistence Providers topic in the Help Center.
For detailed software and hardware requirements, refer to the ThingWorx System Requirements and
Compatibility Matrix document.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 4
Installing ThingWorx 7.4
NOTE: Refer to the System Requirements and Compatibility Matrix document for version
requirements.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 5
Installing ThingWorx 7.4
4. Click I Agree.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 6
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 7
Installing ThingWorx 7.4
Djava.library.path example:
-
Djava.library.path=C:\Prog
ram Files\Apache Software
Foundation\Tomcat
8.0\webapps\Thingworx\WEB-
INF\extensions
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 8
Installing ThingWorx 7.4
21. OPTIONAL STEP: If you want to NOTE: Increasing this setting improves
increase the default cache settings performance and avoids the following message
that affect static file caching, add the in Tomcat:
following line within the
<context></context> tags in the WARNING: Unable to add the resource
$TOMCAT_HOME/conf/context.xml at [/Common/jquery/jquery-ui.js] to
file: the cache because there was
<Resources insufficient free space available
cacheMaxSize="501200" after evicting expired cache
cacheObjectMaxSize="2048" entries - consider increasing the
cacheTtl="60000"/> maximum size of the cache
22. If you are not installing PostgreSQL, skip to the Installing ThingWorx section.
23. If you are using a database other than PostgreSQL and H2, refer to the following:
a. SAP HANA: Getting Started with SAP HANA and ThingWorx Guide
b. Microsoft SQL Server: Getting Started with MS SQL Server and ThingWorx Guide
NOTE: If you are including the HA layer to your implementation, refer to the ThingWorx High Availability
Administrator’s Guide.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 9
Installing ThingWorx 7.4
You will need to know where your PostgreSQL data directory resides for these steps. On Windows, the
default data folder is C:\Program Files\PostgreSQL\9.4\data This location will be referred to as
<PGDATA> in this guide.
Modify the <PGDATA>/pg_hba.conf file and add the following lines based on your desired
configuration:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 10
Installing ThingWorx 7.4
If you want to allow all IPv4 addresses to host all all 0.0.0.0/0 md5
connect:
If you want to allow only a specific IPv4 host all all <ipAddress>/32 md5
address to connect (Replace <ipAddress>
with the IP address of the machine making
the connection):
If you want to allow all IPv6 addresses to host all all ::0/0 md5
connect:
If you want to allow only a specific IPv6 host all all <ipv6Address>/128 md5
address to connect (Replace
<ipv6Address> with the appropriate
address)
Any other combination is possible by using additional allowance lines (individual IPs or ranges) or subnet
masks appropriate to the machines that require access to the PostgreSQL database.
Any change to this file requires a restart of the database service.
For additional information about configuring the pg_hba.conf file, see the Official PostgreSQL
Documentation (9.4).
NOTE: If you create with the -d<databasename> command, you do not have to use the
PostgreSQL user.
NOTE: You must specify the -l option to a path that exists. For example, -l
D:\ThingworxPostgresqlStorage. The script does not create the folder for you.
The folder must have appropriate ownership and access rights. The folder should be owned
by the same user who runs the PostgreSQL service, and have Full Control assigned to that user
- this user is generally NETWORK_SERVICE, but may differ in your environment.
Various parameters such as server, port, database, tablespace, tablespace location and
thingworxusername can be configured in the script, depending on your requirements.
Execute this script with the --help option for usage information.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 11
Installing ThingWorx 7.4
To set up the database and tablespace with a default PostgreSQL installation that has a
PostgreSQL database and a PostgreSQL user name, enter:
where <PostgreSQL user role name> is the user role name that you entered in
previous steps.
5. Execute the script. Once executed, this creates a new database and tablespace with a default
PostgreSQL installation in the PostgreSQL instance installed on the localhost.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 12
Installing ThingWorx 7.4
Various parameters such as server, port, database, username, schema, and option can be
configured in the script depending on the requirements. Execute this script with --help option
for usage information.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 13
Installing ThingWorx 7.4
2. Place the platform-settings.json file into the ThingworxPlatform folder. This file is available in
the software download.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 14
Installing ThingWorx 7.4
NOTE: If your PostgreSQL server is not the same as your ThingWorx server, and you are having
issues with your ThingWorx installation, review your Tomcat logs and platform-settings.json file.
The default installation assumes both servers are on the same machine.
1. Create a working directory where you will perform this process, such as
C:\<password_setup_location> (Windows), and copy the Thingworx.war to that location.
2. Unzip the Thingworx.war.
3. Open a command prompt, cd to your working directory, and set your CLASSPATH by doing the
following:
a. Go to Control Panel > System Properties > Environment Variables.
b. Create a new environment variable: PG_PW_UTIL
C:\<password_setup_location>\WEB-INF\lib\thingworx-platform-
common-<release-version>.jar;C:\password_setup\WEB-
INF\lib\slf4j-api-1.7.12.jar;C:\<password_setup_location>\WEB-
INF\lib\logback-core-
1.0.13.jar;C:\<password_setup_location>\WEB-INF\lib\logback-
classic-1.0.13.jar;C:\<password_setup_location>\WEB-
INF\lib\thingworx-common-<release-version>.jar
c. Add the variable to the CLASSPATH.
CLASSPATH
<don’t touch existing classpath>; %PG_PW_UTIL%
d. In your command shell, enter 'java -version'.
It should respond with a Java version.
4. Open /ThingworxPlatform/platform-settings.json and change the password value to
'encrypt.db.password'.
For example, "<your unique password>": "encrypt.db.password",
NOTE: Because the PostgreSQL admin password should not be in platform-settings.json, you
put in the string "encrypt.db.password" for the password. When the platform encounters
that value, it tries to look up the encrypted password in the keystore.
5. Create a directory named "\twx" that has the same parent directory as the
"\ThingworxPlatform" directory.
6. To create a key store with the PostgreSQL password encrypted inside, run the following
command: java
com.thingworx.platform.security.keystore.ThingworxKeyStore
encrypt.db.password <unique postgres_password>
In the second argument, enter your unique PostgreSQL password.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 15
Installing ThingWorx 7.4
7. Once you have created the encrypted password, remove the updates to the CLASSPATH.
2. Copy the Thingworx.war file and place it in the following location of your Tomcat
installation:
NOTE: Failure to place the license.bin in the ThingworxPlatform folder will result in
ThingWorx not starting after deployment.
NOTE: This version of ThingWorx has been tested with Ubuntu 14.04. Other versions are not supported
and may not work.
2. Install and Configure Network Time Protocol (NTP) settings for time synchronization:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 16
Installing ThingWorx 7.4
NOTE: The default configuration for NTP is sufficient. For additional configuration
information about NTP (beyond the scope of this documentation), refer to the following
resources:
Time Synchronization with NTP
How do I use pool.ntp.org?
4. Download the Java 8u92 JDK tar file from Oracle’s website, or run the following:
NOTE: This version of ThingWorx has been tested with Java 8 update 92. Other versions
are not supported and may not work.
9. Change owner:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 17
Installing ThingWorx 7.4
NOTE: “Nothing to configure” is a normal response to this command and is not an error.
$ java –version
NOTE: This should return something similar to the following (build specifics may be
different):
$ wget http://archive.apache.org/dist/tomcat/tomcat-
8/v8.0.33/bin/apache-tomcat-8.0.33.tar.gz
NOTE: This version of ThingWorx has been tested with Tomcat 8.0.33. Other versions are
not supported and may not work.
14. Create and change the owner for /usr/share/tomcat8 and move Tomcat to the following
location. Add user and group to the system:
$ export JAVA_HOME=/usr/lib/jvm/jdk1.8.0_92
$ export CATALINA_HOME=/usr/share/tomcat8/8.0.33
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 18
Installing ThingWorx 7.4
$ cd $CATALINA_HOME
17. Change owner and access permissions of bin/ lib/ and webapps/ :
Set the tomcat8 user password to the same as the keystore password
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 19
Installing ThingWorx 7.4
22. Modify the shutdown string and protocol used by the SSL Connector in
$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.0.33/conf/.keystore"
keystorePass="changeit" clientAuth="false" sslProtocol="TLS" />
<!--
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
-->
NOTE: In hosted and/or public-facing environments, use of the manager web application is
not recommended because it introduces a security risk. Similarly, the example web
applications included in /webapps should be removed as they may introduce unnecessary
security vulnerabilities into Tomcat.
$ id -u tomcat8
110
NOTE: The number returned may be different than this example. These examples use 110.
Change this to what was returned in the previous step.
0.0.0.0/0:1,1023
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 20
Installing ThingWorx 7.4
CATALINA_HOME=/usr/share/tomcat8/8.0.33
case $1 in
start)
/bin/su -p -s /bin/sh tomcat8 $CATALINA_HOME/bin/startup.sh
;;
stop)
/bin/su -p -s /bin/sh tomcat8 $CATALINA_HOME/bin/shutdown.sh
;;
restart)
/bin/su -p -s /bin/sh tomcat8 $CATALINA_HOME/bin/shutdown.sh
/bin/su -p -s /bin/sh tomcat8 $CATALINA_HOME/bin/startup.sh
;;
esac
exit 0
NOTE: This may already be installed on your system. If so, skip and go to the next step.
$ cd /usr/share/tomcat8/8.0.33/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 ../..
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 21
Installing ThingWorx 7.4
32. Open /etc/systemd/system/tomcat8.service in a text editor (as root) and paste in the
following:
[Unit]
Description=Apache Tomcat Web Application Container
After=network.target
[Service]
Type=forking
PIDFile=/var/run/tomcat.pid
Environment=CATALINA_PID=/var/run/tomcat.pid
Environment=JAVA_HOME=/usr/lib/jvm/jdk1.8.0_92
Environment=CATALINA_HOME=/usr/share/tomcat8/8.0.33
Environment=CATALINA_BASE=/usr/share/tomcat8/8.0.33
Environment=CATALINA_OPTS=
ExecStart=/usr/share/tomcat8/8.0.33/bin/jsvc \
-Dcatalina.home=${CATALINA_HOME} \
-Dcatalina.base=${CATALINA_BASE} \
-Djava.awt.headless=true -
Djava.net.preferIPv4Stack=true -Dserver -Dd64 -XX:+UseNUMA \
-XX:+UseConcMarkSweepGC -
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/tom
cat-juli.jar \
-user tomcat8 \
-java-home ${JAVA_HOME} \
-pidfile /var/run/tomcat.pid \
-errfile
${CATALINA_HOME}/logs/catalina.out \
-outfile
${CATALINA_HOME}/logs/catalina.out \
$CATALINA_OPTS \
org.apache.catalina.startup.Bootstrap
[Install]
WantedBy=multi-user.target
33. OPTIONAL STEP: If you want to increase the default cache settings that affect static file caching,
add the following line within the <context></context> tags in the
$TOMCAT_HOME/conf/context.xml file:
34. If you are not installing PostgreSQL, skip to the Installing ThingWorx section.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 22
Installing ThingWorx 7.4
NOTE: If you are including the HA layer to your implementation, refer to the ThingWorx High Availability
Administrator’s Guide.
In Ubuntu 14.4, the PostgreSQL repository can be added allowing the application to be
installed directly from the package manager::
NOTE: This version of ThingWorx has been tested with PostgreSQL versions 9.4.5 through
9.4.10. Other versions are not supported and may not work.
NOTE: PgAdmin III is an open source management tool for your databases that is included in
the PostgreSQL download. The tool features full Unicode support, fast, multithreaded query,
and data editing tools and support for all PostgreSQL object types.
4. Enter the password for the PostgreSQL user. You will use this password in later steps.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 23
Installing ThingWorx 7.4
6. Configure pgAdmin 3:
$ sudo pgadmin3
$ sudo pgadmin3
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 24
Installing ThingWorx 7.4
9. Click the plug icon to add a connection to a server in the top left corner:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 25
Installing ThingWorx 7.4
to listen for connections from other users (thingworx user, default is twadmin) and/or other machines
(ThingWorx installed on a separate server).
You need to know where your PostgreSQL data directory resides to perform these steps. On Linux, the
location of the data folder, or even the configuration files can change based on distribution and
installation method (download or package manager install).
On Ubuntu, when installed via apt-get, the configuration files are located at /etc/postgresql/9.4/main/
This location is referred to as <PGDATA> in this guide.
Modify the <PGDATA>/pg_hba.conf file and add the following lines based on your desired
configuration:
If you want to allow only a specific IPv4 host all all <ipAddress>/32 md5
address to connect (Replace
<ipAddress> with the IP address of the
machine making the connection)
If you want to allow all IPv6 addresses to host all all ::0/0 md5
connect:
If you want to allow only a specific IPv6 host all all <ipv6Address>/128 md5
address to connect (Replace
<ipv6Address> with the appropriate
address)
Any other combination is possible by using additional allowance lines (individual IPs or ranges) or subnet
masks appropriate to the machines that require access to the PostgreSQL database.
Any change to this file requires a restart of the database service.
For additional information about configuring the pg_hba.conf file, see the Official PostgreSQL
Documentation (9.4)
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 26
Installing ThingWorx 7.4
NOTE: You must specify the -l option to a path that exists. For example, -l
ThingworxPostgresqlStorage. The script does not create the folder for you.
As shown above, this folder needs have appropriate ownership and access rights. It should be
owned by the PostgreSQL user and have the read, write, and execute assigned to the owner.
NOTE: If you create with the -d<databasename>, you do not have to use the PostgreSQL user.
NOTE: This example uses the 7.4.0 download from the PTC site. If necessary, change the file
name to the version you are using.
Various parameters such as server, port, database, tablespace, tablespace location and
thingworxusername can be configured in the script, depending on the requirements. Execute
this script with the --help option for usage information.
To set up the database and tablespace with a default PostgreSQL installation that has a
PostgreSQL database and a PostgreSQL user name, enter:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 27
Installing ThingWorx 7.4
$ sudo sh thingworxPostgresSchemaSetup.sh
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 28
Installing ThingWorx 7.4
2. Copy the platform-settings.json file from the install package to the /ThingworxPlatform
folder. From the directory containing the JSON file:
The JSON file contains default settings. Refer to alternate configuration options in:
Appendix C: platform-settings.json Options and
Appendix B: platform-settings.json sample.
NOTE: If your PostgreSQL server is not the same as your ThingWorx server, and you are having
issues with your ThingWorx installation, review your Tomcat logs and platform-settings.json file.
The default installation assumes both servers are on the same machine.
Prerequisites
You must have Java installed and on your path.
You must have PostgreSQL installed and know the password.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 29
Installing ThingWorx 7.4
3. Open a command prompt, cd to your working directory, and set your CLASSPATH:
$ export CLASSPATH=WEB-INF/lib/thingworx-platform-common-<release-
version>.jar:WEB-INF/lib/slf4j-api-1.7.12.jar:WEB-INF/lib/logback-core-
1.0.13.jar:WEB-INF/lib/logback-classic-1.0.13.jar:./WEB-
INF/lib/thingworx-common-<release-version>.jar
For example:
5. Create a directory named "/twx" that has the same parent directory as
"/ThingworxPlatform":
6. To create a key store with the PostgreSQL password encrypted inside, run the following
command:
$ java com.thingworx.platform.security.keystore.ThingworxKeyStore
encrypt.db.password <unique postgres_password>
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 30
Installing ThingWorx 7.4
The location of the ThingworxPlatform folder varies, as it is determined per your initial
set up.
NOTE: Failure to place the license.bin in the ThingworxPlatform folder will result in
ThingWorx not starting after deployment.
6. Start Tomcat to deploy the ThingWorx web application:
7. You should now be able to connect to ThingWorx Composer through a web browser at
https://localhost/Thingworx
Username: Administrator
Password: admin
NOTE: When using a self-signed certificate, it is normal to get a security warning when
accessing ThingWorx. In most browsers, clicking on the advanced options will allow
you to set an exception for your private certificate. Setting up a security certificate
through a signing authority will allow secure connections without having to set an
exception.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 31
Installing ThingWorx 7.4
NOTE: This version of ThingWorx has been tested on RHEL 7.1. Other RHEL versions are not supported
and may not work.
6. Change Owner:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 32
Installing ThingWorx 7.4
$ sudo rm /usr/java/latest
$ sudo ln -s /usr/lib/jvm/jdk1.8.0_92 /usr/java/latest
$ sudo ln -s /usr/lib/jvm/jdk1.8.0_92/bin/keytool /usr/bin/keytool
NOTE: This may return a ‘File Exists’ error. If so, ignore and continue.
$ sudo alternatives --config keytool
$ java -version
java version "1.8.0_92"
Java(TM) SE Runtime Environment (build 1.8.0_92-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.45-b02, mixed mode)
$ wget https://archive.apache.org/dist/tomcat/tomcat-8/v8.0.33/bin/apache-
tomcat-8.0.33.tar.gz
$ cd /usr/share/tomcat8/8.0.33
14. Change owner and access permissions of bin/ lib/ and webapps/:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 33
Installing ThingWorx 7.4
18. Uncomment the Manager element in context.xml to prevent sessions from persisting across
restarts.
Open /usr/share/tomcat8/8.0.33/conf/context.xml in a text editor (as root) and remove the ‘<!—
‘ before ‘<Manager pathname="" />’ and the ‘-->’ after
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 34
Installing ThingWorx 7.4
20. Modify the shutdown string and protocol used by the SSL Connector in server.xml:
<Connector executor="tomcatThreadPool"
port="80" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
-->
<Connector port="443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https"
secure="true"
keystoreFile="${user.home}/8.0.33/conf/.keystore"
keystorePass="changeit" clientAuth="false"
sslProtocol="TLS" />
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 35
Installing ThingWorx 7.4
$ cd /usr/share/tomcat8/8.0.33/bin/
$ sudo tar xvfz commons-daemon-native.tar.gz
$ cd commons-daemon-*-native-src/unix
$ sudo ./configure --with-java=$JAVA_HOME
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 36
Installing ThingWorx 7.4
Open /usr/lib/systemd/system/tomcat.service in a text editor (as root) and paste in the following:
[Unit]
Description=Apache Tomcat Web Application Container
After=network.target
[Service]
Type=forking
PIDFile=/var/run/tomcat.pid
Environment=CATALINA_PID=/var/run/tomcat.pid
Environment=JAVA_HOME=/usr/lib/jvm/jdk1.8.0_92
Environment=CATALINA_HOME=/usr/share/tomcat8/8.0.33
Environment=CATALINA_BASE=/usr/share/tomcat8/8.0.33
Environment=CATALINA_OPTS=
ExecStart=/usr/share/tomcat8/8.0.33/bin/jsvc \
-Dcatalina.home=${CATALINA_HOME} \
-Dcatalina.base=${CATALINA_BASE} \
-Djava.awt.headless=true -
Djava.net.preferIPv4Stack=true -Dserver -Dd64 -XX:+UseNUMA \
-XX:+UseConcMarkSweepGC -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 \
-java-home ${JAVA_HOME} \
-pidfile /var/run/tomcat.pid \
-errfile ${CATALINA_HOME}/logs/catalina.out \
-outfile ${CATALINA_HOME}/logs/catalina.out \
$CATALINA_OPTS \
org.apache.catalina.startup.Bootstrap
[Install]
WantedBy=multi-user.target
Note: This will allow the user to control the Tomcat service with the following commands:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 37
Installing ThingWorx 7.4
You should now be able to connect to the Tomcat server by entering https://localhost in a browser.
29. If you are not installing PostgreSQL, skip to the Installing ThingWorx section.
NOTE: This guide assumes a version of RHEL with a GUI (X11) and an active account with access to the
RHEL software repositories.
If you are working without a GUI, skip installing PgAdmin 3 and refer to this support article for alternate
instructions. If you do not have access to the official RHEL software sources, you can set up a free open
source repository from the EPEL team. (this site is not provided or controlled by PTC).
NOTE: If you are including the HA layer to your implementation, refer to the ThingWorx High Availability
Administrator’s Guide.
NOTE: This version of ThingWorx has been tested with PostgreSQL 9.4. Other versions
are not supported and may not work.
2. Install PgAdmin 3:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 38
Installing ThingWorx 7.4
NOTE: The <unique password> value is the same as in the previous step.
7. If the PostgreSQL database is not located on the same server as ThingWorx, then refer
to the section Configuring PostgreSQL Database Located on a Separate Server than
Thingworx (Ubuntu) and skip the next two steps.
$ sudo pgadmin3
Open /var/lib/pgsql/9.4/data/postgresql.conf
Put a check next to listen addresses and port
-The default settings of localhost and 5432 are usually sufficient.
Save and close
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 39
Installing ThingWorx 7.4
$ sudo pgadmin3
Click the plug Add a connection to a server in the top left corner.
Fill out the following:
Name: PostgreSQL 9.4
Host: localhost
Port: 5432
Service: <blank>
Maintenance DB: postgres
Username: postgres
Password: <password as set in step above>
Store password: Checked
Group: Servers
Click OK
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 40
Installing ThingWorx 7.4
14. Download the ThingWorx installer from the PTC downloads page:
https://support.ptc.com/appserver/auth/it/esd/index.jsp
$ sh thingworxPostgresSchemaSetup.sh
NOTE: When prompted, enter the password that you entered in previous steps.
NOTE: If your PostgreSQL server is not the same as your ThingWorx server, and you are
having issues with your ThingWorx installation, review your Tomcat logs and platform-
settings.json file. The default installation assumes both servers are on the same
machine.
You need to know where your PostgreSQL data directory resides to perform these steps. On Linux, the
location of the data folder, or even the configuration files can change based on distribution and
installation method (download or package manager install).
On RHEL, when installed via apt-get, the configuration files are located at /var/lib/pgsql/9.4/data/ This
location is referred to as <PGDATA> in this guide.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 41
Installing ThingWorx 7.4
Modify the <PGDATA>/pg_hba.conf file and add the following lines based on your desired configuration:
If you want to allow all IPv4 addresses to host all all 0.0.0.0/0 md5
connect
If you want to allow only a specific IPv4 host all all <ipAddress>/32 md5
address to connect (Replace
<ipAddress> with the IP address of the
machine making the connection)
If you want to allow all IPv6 addresses to host all all ::0/0 md5
connect
If you want to allow only a specific IPv6 host all all <ipv6Address>/128 md5
address to connect (Replace
<ipv6Address> with the appropriate
address)
Any other combination is possible by using additional allowance lines (individual IPs or ranges) or subnet
masks appropriate to the machines that require access to the PostgreSQL database.
Any change to this file requires a restart of the database service.
For additional information about configuring the pg_hba.conf file, see the Official PostgreSQL
Documentation (9.4)
Prerequisites
You must have Java installed and on your path.
You must have PostgreSQL installed and know the password.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 42
Installing ThingWorx 7.4
$ export CLASSPATH=WEB-INF/lib/thingworx-platform-common-<release-
version>.jar:WEB-INF/lib/slf4j-api-1.7.12.jar:WEB-
INF/lib/logback-core-1.0.13.jar:WEB-INF/lib/logback-classic-
1.0.13.jar:./WEB-INF/lib/thingworx-common-<release-version>.jar
4. Open /ThingworxPlatform/platform-settings.json and change the password value to
'encrypt.db.password'.
For example, "<unique password>": "encrypt.db.password",
5. Create a directory named "/twx" that has the same parent directory as
"/ThingworxPlatform":
$ sudo mkdir /twx
6. To create a key store with the PostgreSQL password encrypted inside, run the following
command:
$ java com.thingworx.platform.security.keystore.ThingworxKeyStore
encrypt.db.password <unique postgres_password>
Change your working directory to the installer folder in the unzipped ThingWorx
download package and run these commands:
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 43
Installing ThingWorx 7.4
NOTE: Failure to place the license.bin in the ThingworxPlatform folder will result in
ThingWorx not starting after deployment.
NOTE: The password, which should not be easily guessed or a known, common
password, should be at least 14 characters in length and include a mix of uppercase
and lowercase letters, numbers, and special characters.
1. Follow the steps outlined in the Amazon RDS installation guide. The steps below provide
supplemental guidance when you are ready to configure the Specify DB Details page in AWS.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 44
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 45
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 46
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 47
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 48
Installing ThingWorx 7.4
where <user role name> is the user role name you created in previous steps and
<admin user name> is the administrator account created during RDS installation.
4. Execute the script. Once executed, this creates a new database in the Amazon RDS
PostgreSQL instance.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 49
Installing ThingWorx 7.4
where <user role name> is the user role name you created in previous steps and
<admin user name> is the administrator account created during RDS installation.
4. Execute the script. Once executed, this creates a new database in the Amazon RDS
PostgreSQL instance.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 50
Installing ThingWorx 7.4
NOTE: The values listed in the Configuration column reflect the example deployment in the
reference architecture, but can be modified for your environment. For many of the settings in
the table below, links are provided to help you determine the configuration values for your
environment. RDS specific information can be found at -
http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonD
BATasks.html
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 51
Installing ThingWorx 7.4
Windows
Ubuntu
RHEL
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 52
Installing ThingWorx 7.4
Setting Description
-server Explicitly tells the JVM to run in server mode. This is
true by default when using 64-bit JDK, but it is best
practice to declare it.
-d64 Explicitly tells the JVM to run in 64-bit mode. The
current JVM automatically detects this, but it is best
practice to declare it.
XX:+UseG1GC Tells the JVM to use the Garbage First Garbage
Collector.
-Dfile.encoding=UTF-8 Tells the JVM to use UTF-8 as the default character set
so that non-Western alphabets are displayed
correctly.
-Djava.library.path Specifies the path to the native library .
Tells the JVM to allocate a minimum of 3072MB of
-Xms3072m (for a system with 4GB of memory to the Tomcat process. This should be set to
memory) 75% of the available system memory.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 53
Installing ThingWorx 7.4
Setting Description
-Dcom.sun.management.jmxremote Notifies the JVM that you plan to remote
monitor it via JMX
-Dcom.sun.management.jmxremote.port=22222 The port the JVM should open up for
monitoring.
-Dcom.sun.management.jmxremote.ssl=false No SSL usage.
-Dcom.sun.management.jmxremote.authenticate=false No authentication required.
-Djava.rmi.server.hostname=<host or IP> The hostname or IP that the underlying
RMI client connection will use.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 54
Installing ThingWorx 7.4
"HASettings": {
"CoordinatorConnectionTimeout": 15000,
"CoordinatorHosts": "127.0.0.1:2181",
"CoordinatorMaxRetries": 3,
"CoordinatorRetryTimeout": 1000,
"CoordinatorSessionTimeout": 60000,
"LoadBalancerBase64EncodedCredentials":
"QWRtaW5pc3RyYXRvcjphZG1pbg=="
}
},
"MssqlPersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 3,
"acquireRetryDelay": 10000,
"checkoutTimeout": 1000000,
"driverClass":
"com.microsoft.sqlserver.jdbc.SQLServerDriver",
"fetchSize": 5000,
"idleConnectionTestPeriod": 60,
"initialPoolSize": 5,
"jdbcUrl":
"jdbc:sqlserver://localhost:1433;databaseName=thingworx;applicationNam
e=Thingworx;",
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 300,
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 55
Installing ThingWorx 7.4
"maxPoolSize": 100,
"maxStatements": 100,
"minPoolSize": 5,
"numHelperThreads": 8,
"password": "Password@123",
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0,
"username": "msadmin"
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 10000,
"maximumQueueSize": 500000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000
}
}
}
}
"PersistenceProviderPackageConfigs": {
"H2PersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 30,
"acquireRetryDelay": 1000,
"checkoutTimeout": 2000,
"idleConnectionTestPeriod": 6,
"initialPoolSize": 10,
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 36000,
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 56
Installing ThingWorx 7.4
"maxPoolSize": 100,
"maxStatements": 0,
"maxStatementsPerConnection": 50,
"minPoolSize": 10,
"numHelperThreads": 6,
"tableLockTimeout": 10000,
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumWaitTime": 10000,
"maximumQueueSize": 500000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000
}
},
"NeoPersistenceProviderPackage": {
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"scanRate": 5,
"sizeThreshold": 1000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 500000,
"maximumWaitTime": 10000,
"scanRate": 5,
"sizeThreshold": 1000
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 57
Installing ThingWorx 7.4
}
},
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"acquireIncrement": 5,
"acquireRetryAttempts": 3,
"acquireRetryDelay": 10000,
"checkoutTimeout": 1000000,
"driverClass": "org.postgresql.Driver",
"fetchSize": 5000,
"idleConnectionTestPeriod": 60,
"initialPoolSize": 5,
"jdbcUrl":
"jdbc:postgresql://localhost:5432/thingworx",
"maxConnectionAge": 0,
"maxIdleTime": 0,
"maxIdleTimeExcessConnections": 300,
"maxPoolSize": 100,
"maxStatements": 100,
"minPoolSize": 5,
"numHelperThreads": 8,
"password": "password",
"testConnectionOnCheckout": false,
"unreturnedConnectionTimeout": 0,
"username": "twadmin"
},
"StreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 250000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
"sizeThreshold": 1000
},
"ValueStreamProcessorSettings": {
"maximumBlockSize": 2500,
"maximumQueueSize": 500000,
"maximumWaitTime": 10000,
"numberOfProcessingThreads": 5,
"scanRate": 5,
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 58
Installing ThingWorx 7.4
"sizeThreshold": 1000
}
}
}
}
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 59
Installing ThingWorx 7.4
platform-settings.json Options
Setting Default Description
Core Platform Settings
BackupStorage /ThingworxBackupStor The directory name where all
age backups are written to.
DatabaseLogRetentionPolicy 7 The number of days that database
logs are retained.
EnableBackup true Determines whether backups are
retained.
EnableHA false Determines whether ThingWorx can
be configured for a highly available
landscape.
EnableSystemLogging false Determines whether system logging
is enabled. NOTE: DO NOT TURN
THIS ON UNLESS INSTRUCTED BY
THINGWORX SUPPORT.
HTTPRequestHeaderMaxLength 2000 The maximum allowable length for
HTTP Request Headers values.
HTTPRequestParameterMaxLength 2000 The maximum allowable length for
HTTP Request Parameter values.
Storage /ThingworxStorage The directory where all storage
directories are created/located
(excluding Backup Storage).
HA Settings
Settings specific to a PostgreSQL HA landscape configuration. All are optional, and are ignored if the
EnableHA setting above is set to false.
CoordinatorConnectionTimeout 15000 How long to wait (in milliseconds)
for a connection to be established
with process/server used to
coordinate ThingWorx leadership.
CoordinatorHosts 127.0.0.1:2181 A comma-delimited list of server IP
addresses on which the processes
used to coordinate ThingWorx
leadership exist (e.g.
"127.0.0.1:2181, 127.0.0.2:2181").
CoordinatorMaxRetries 3 The maximum allowable number of
retries that will be made to establish
a connection with the
process/server used to coordinate
ThingWorx leadership.
CoordinatorRetryTimeout 1000 How long to wait (in milliseconds)
for each retry attempt.
CoordinatorSessionTimeout 60000 How long ThingWorx waits (in
milliseconds) without receiving a
"heartbeat" from the process/server
used to coordinate ThingWorx
leadership.
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 60
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 61
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 62
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 63
Installing ThingWorx 7.4
jdbc:postgresql://<DBServer>:<DBP
ort>/<databasename>?currentSche
ma=mySchema
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 64
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 65
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 66
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 67
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 68
Installing ThingWorx 7.4
Windows
PostgreSQL client comes along with PgAdmin lll. Follow the same instructions for installation.
Ubuntu
sudo apt-get install postgresql-client
RHEL
sudo yum install postgresql94.x86_64
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 69
Installing ThingWorx 7.4
The following error message is received when attempting Remove -Djava.library.path from
to undeploy ThingWorx: Tomat’s Java configuration before
undeployment.
FAIL - Unable to delete [<path to
Tomcat>\webapps\Thingworx]. The
continued presence of this file
may cause problems.
Due to FlxCore64.dll (<path to
Tomcat>\webapps\Thingworx\WEB-
INF\extensions\FlxCore64.dll)
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 70
Installing ThingWorx 7.4
Copyright © 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 71