Manual Installation
Windows Installation
Install Java, Apache Tomcat, and ThingWorx
Install Java and Apache Tomcat
1. Refer to the ThingWorx System Requirements for Java version requirements.
2. Download and install the required version of Java.
◦ 9.0: Java
▪ Unzip the downloaded file (for example, openjdk-11 zip) and copy the jdk-<xxx> folder from the un-zipped folder. Paste the jdk folder in the following location: C:\\Program Files\Java.
3. Ensure the Java environment variable is configured properly:
a. Locate your Java installation directory and copy the path. The default path is C:\Program Files\Java\jdk_<version number>.
b. From the Windows start menu, navigate to Advanced System Properties. Your path to these properties will vary based on your version of Windows. For example, for Windows 10, search for Environment Variables then select Edit the system environment variables.
c. Click Environment Variables.
d. In the System variables section, click New.
e. In the Variable name field, enter JAVA_HOME.
f. In the Variable value field, enter the path to your Java installation as defined in step a.
g. Edit the Path variable and add a new value of %JAVA_HOME%\bin.
h. Click OK.
4. Refer to the ThingWorx System Requirements for Apache Tomcat version requirements.
5. Visit the Apache Tomcat website to download the 32-bit/64-bit Windows Service Installer (pgp, sha1, sha512).
 |
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.
|
6. The Apache Tomcat Setup Wizard launches. Click Next.
7. Click I Agree.
8. In the Choose Components section, use the default settings. Click Next.
9. In the HTTP/1.1 Connector Port field, type 80 (or other available port).
10. In the Tomcat Administrator Login fields, you must enter a Tomcat user name and a unique, secure password for Tomcat administration. In ThingWorx it is required, not optional.
11. Click Next.
12. Click Next.
13. Click Install.
14. Click Finish.
15. Launch Tomcat. Click Configure Tomcat. In the Configure Tomcat window, click the Java tab.
16. In the Java Options field, add the following to the end of the options field:
-Dserver -Dd64
-XX:+UseG1GC
-Dfile.encoding=UTF-8
-Duser.timezone=UTC
-Djava.library.path=<path to Tomcat>\webapps\Thingworx\WEB-INF\extensions
-Dlog4j2.formatMsgNoLookups=true
-XX:+UseG1GC
-Dfile.encoding=UTF-8
-Duser.timezone=UTC
-Djava.library.path=<path to Tomcat>\webapps\Thingworx\WEB-INF\extensions
-Dlog4j2.formatMsgNoLookups=true
|
|
Djava.library.path example:
-Djava.library.path=C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\Thingworx\WEB-INF\extensions
|
|
|
For more information on these options and for additional options for hosted and/or public-facing environments, refer to the Apache Tomcat Java Option Settings.
|
17. Set the Initial memory pool and Maximum memory pool fields to 75% of the available OS memory (for example, 12GB for a 16GB RAM system). Refer to JVM Tuning for additional information.
18. Click OK
19. In the location of the Tomcat installation, open 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 webapps/APP_NAME/WEB-INF/web.xml so it won't cause problems.
|
<error-page><exception-type>java.lang.Throwable</exception-type><location>/error.jsp</location></error-page>
20. In the location of the Tomcat installation, open conf/server.xml. Add the following inside the <Host> </Host> tags:
<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false" />
 |
For security reasons, it is critical that you disable the AJP connector, if not already done so by default, by performing the following step.
|
21. In the location of the Tomcat installation, open conf/server.xml and search for the following line. If found, comment it out and save the file:
<Connector port ="8009" protocol="AJP/1.3" redirectPort="8443"/>
|
|
In Apache Tomcat 9.0 and later, the rejectIllegalHeader attribute defaults to true. Manually modifying the conf/web.xml file to set this attribute to false is not recommended or supported by PTC.
|
22. Remove all Tomcat example webapps (docs, examples, host-manager, manager, ROOT) located in /<path_to_tomcat>/webapps/. Removing these apps prevents unnecessary access to Tomcat, specifically in the context that can allow users to view other users' cookies.
23. If your application requires a specific cipher suite, refer to the following documentation for configuration information:
24. PTC strongly recommends the use of TLS when running ThingWorx. For detailed instructions on setting up TLS, refer to this technical support article.
25. (OPTIONAL STEP) To increase the default cache settings that affect static file caching, add the following line within the <Context></Context> tags in the /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
because there was insufficient
free space available after evicting expired cache entries -
consider increasing the maximum size of the cache
Installing ThingWorx
1. Create folders named ThingworxPlatform and ThingworxStorage at the root of the drive where Tomcat was installed.
|
|
If you want to create the folders at a different location, refer to the steps here.
|
|
|
These folders must have appropriate ownership and access rights. They should be owned by the same user who runs the Tomcat service and should have full control assigned to that user. This user is generally NETWORK_SERVICE but may differ in your environment. Without these permissions, the server will fail to start.
|
2. Obtain the appropriate Thingworx.war file for the database you are using. The latest ThingWorx downloads are posted at support.ptc.com under Download Software > Order or Download Software Updates > ThingWorx Foundation > Release X.X > ThingWorx PostgreSQL, ThingWorx Mssql, ThingWorx H2, or ThingWorx AzureSql > Most Recent Version > ThingWorx-Platform-<database type>-<version>.
3. Place the platform-settings.json in the ThingworxPlatform folder.
|
|
If you are using H2, you must create the platform-settings.json file, as it is not included in the download.
|
4. Configure the Administrator password.
Add the following AdministratorUserSettings section (in PlatformSettingsConfig) to your platform-settings.json file with a password that is at least 14 characters long. Refer to platform-settings.json Configuration Details for more information on placement. Refer to Passwords for additional information on setting passwords.
|
|
Do not copy and paste the sample below, as it may cause bad formatting in your platform-settings.json. Instead, click here and copy from the file.
|
{
"PlatformSettingsConfig": {
"AdministratorUserSettings": {
"InitialPassword": "changeme"
}
}
}
|
|
If Tomcat fails to start and reports the error message: Check the InitialPassword setting in the AdministratorUserPassword section in platform-settings.json..., check the following:
• The password setting exists in platform-settings.json.
• The password is valid (14 or more characters by default).
• The platform-settings.json file is formatted correctly. Bad formatting could lead to errors.
|
5. If you are installing ThingWorx 5.0.1 and newer, configure Content Security Policy (CSP).
a. Add "EnableContentSecurityPolicyFilter": false, to platform-settings.json under BasicSettings as follows.
{
"PlatformSettingsConfig": {
"BasicSettings": {
"BackupStorage": "/ThingworxBackupStorage",
"DatabaseLogRetentionPolicy": 7,
"DatabaseWriteRetryAttempts": 10,
"EnableBackup": true,
"EnableClusteredMode": false,
"EnableContentSecurityPolicyFilter": false,
"EnableSystemLogging": false,
"EnableSSO": false,
"FileRepositoryRoot": "/ThingworxStorage",
"FileTransferLockType" : "LOCAL"
"HTTPRequestHeaderMaxLength": 2000,
"HTTPRequestParameterMaxLength": 2000,
"InternalAesCryptographicKeyLength": 128,
"MetricsLoggingFrequency": 30,
"MetricsLoggingLevel": "WARN",
"MetricsReportingEnabled": true,
"NonceKeyTimeout": 15,
"SessionUpdateDelay": 60,
"Storage": "/ThingworxStorage",
"ScriptTimeout": 30,
"MaxSearchItems": 100000
},
"PlatformSettingsConfig": {
"BasicSettings": {
"BackupStorage": "/ThingworxBackupStorage",
"DatabaseLogRetentionPolicy": 7,
"DatabaseWriteRetryAttempts": 10,
"EnableBackup": true,
"EnableClusteredMode": false,
"EnableContentSecurityPolicyFilter": false,
"EnableSystemLogging": false,
"EnableSSO": false,
"FileRepositoryRoot": "/ThingworxStorage",
"FileTransferLockType" : "LOCAL"
"HTTPRequestHeaderMaxLength": 2000,
"HTTPRequestParameterMaxLength": 2000,
"InternalAesCryptographicKeyLength": 128,
"MetricsLoggingFrequency": 30,
"MetricsLoggingLevel": "WARN",
"MetricsReportingEnabled": true,
"NonceKeyTimeout": 15,
"SessionUpdateDelay": 60,
"Storage": "/ThingworxStorage",
"ScriptTimeout": 30,
"MaxSearchItems": 100000
},
|
|
CSP will be disabled in the new installation if the above flag is not added or is specifically set to false. Setting the flag to true will enable CSP. For more information about CSP, see Content Security Policy.
|
6. Enable extension import. By default, extension import is disabled for all users.
Add the following to the platform-settings.json file under PlatformSettingsConfig. Update the following ExtensionPackageImportPolicy parameters to true to allow extensions to be imported. Refer to Importing Extensions for best practices on controlling extension import.
"ExtensionPackageImportPolicy": {
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
7. Skip this step if you are not using H2 as a database. Add a username and password for H2 in the platform-settings.json file. See platform-settings.json Configuration Details for more information.
|
|
ThingWorx connections to the H2 database require a username and password defined by the user, or the server will not start. This design fully mitigates any potential vulnerability represented by CVE-2018-10054.
|
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<addsecurepassword>",
"username": "twadmin"
}
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<addsecurepassword>",
"username": "twadmin"
}
},
8. Skip this step if you are not using Azure SQL or Azure PostgreSQL Flexible Server as a database. If you are using Azure SQL, open the platform-settings.json file and add the following Azure SQL persistence provider parameters:
"PersistenceProviderPackageConfigs": {
"AzuresqlPersistenceProviderPackage": {
"ConnectionInformation": {
"driverClass": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
"jdbcUrl": "jdbc:sqlserver://<server name>:<port>;databaseName=thingworx;applicationName=Thingworx;",
"password": "<database password>",
"username": "twadmin"
}
}
}
"AzuresqlPersistenceProviderPackage": {
"ConnectionInformation": {
"driverClass": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
"jdbcUrl": "jdbc:sqlserver://<server name>:<port>;databaseName=thingworx;applicationName=Thingworx;",
"password": "<database password>",
"username": "twadmin"
}
}
}
If you are using Azure PostgreSQL Flexible Server, open the platform-settings.json file and add the following Azure PostgreSQL Flexible Server persistence provider parameters:
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"jdbcUrl": "jdbc:postgresql://<server name>:<port>/<database name>",
"password": "<password>",
"username": "<username>",
"sslMode": "require",
"sslRootCert": "<certificate path>"
}
}
"ConnectionInformation": {
"jdbcUrl": "jdbc:postgresql://<server name>:<port>/<database name>",
"password": "<password>",
"username": "<username>",
"sslMode": "require",
"sslRootCert": "<certificate path>"
}
}
For more information about different SSL modes, see PostgreSQL Documentation.
|
|
sslRootCert is required for verify-ca and verify-full SSL modes. For more information about secure communication with Azure PostgreSQL Flex Server and to download the certificate, see Encrypted connectivity using TLS/SSL in Azure Database for PostgreSQL — Flexible Server.
|
9. If you are not using H2 for your database, go to Database Installation and Configuration to set up your database. Return to the next step after your database is configured. If you are using H2, proceed to the next step.
10. Configure licensing:
◦ Open the platform-settings.json file and add the following to the PlatformSettingsConfig section (refer to platform-settings.json Configuration Details for more information on placement.)
|
|
If you are performing a disconnected installation (no internet access), you do not need to add licensing information to the platform-settings.json file. Refer to Licensing for ThingWorx Platform for disconnected sites, and skip this step.
|
{
"PersistenceProviderPackageConfigs": {
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"jdbcUrl": "jdbc:postgresql://localhost:5432/thingworx",
"password": "<password>",
"username": "<username>"
}
}
},
"PlatformSettingsConfig": {
"LicensingConnectionSettings": {
"username":"<PTC_support_portal_username>",
"password":"<PTC_support_portal_password>"
}
}
}
"PersistenceProviderPackageConfigs": {
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"jdbcUrl": "jdbc:postgresql://localhost:5432/thingworx",
"password": "<password>",
"username": "<username>"
}
}
},
"PlatformSettingsConfig": {
"LicensingConnectionSettings": {
"username":"<PTC_support_portal_username>",
"password":"<PTC_support_portal_password>"
}
}
}
◦ Stop Tomcat.
◦ Copy the Thingworx.war file and place it in the following location of your Tomcat installation:
<Tomcat_Install_Location>\webapps
◦ Start Tomcat.
◦ Verify that a license file (successful_license_capability_response.bin) is created in the ThingworxPlatform folder.
|
|
If the settings are filled out incorrectly or if the server can’t connect, a License Request text file (licenseRequestFile.txt) is created in the ThingworxPlatform folder. In this scenario, a license must be created manually. (If it is not created, ThingWorx will start in limited mode. Limited mode does not allow you to persist licensed entities to the database. Licensed entities are Things, mashups, masters, gadgets, users, and persistence providers).
More information on obtaining a ThingWorx disconnected site license through our License Management site can be found in the Licensing for ThingWorx Platform for disconnected sites (no connection to PTC Support portal). In this situation, if the license file is manually generated, it must be renamed to license_capability_response.bin and placed in the ThingworxPlatform folder.
|
|
|
For licensing troubleshooting, refer to this support article.
|
11. Encrypt the license server password by following the steps in Encrypting Passwords.
12. If you are using Azure SQL as your database, follow these steps to download the JDBC driver. Skip this step if you are not using Azure SQL.
a. Go to the Azure portal and navigate to your ThingWorx database.
b. Select Connection strings.
c. Select the JDBC tab.
d. Select Download Microsoft JDBC Driver for SQL Server.
e. Select Microsoft JDBC Driver 6.0 for SQL Server.
f. Extract and copy the downloaded binary in your ThingWorx VM to your Tomcat lib directory.
13. Restart Tomcat.
14. To launch ThingWorx, go to http://<servername>:<port>/Thingworx in a Web browser.
15. Change the initial Administrator password.
a. In Composer, select Administrator >.
b. In the Change Password window, enter Current Password, New Password, and Confirm Password.
| | The password, which should not be easily guessed or a known, common password, should be at least 14 characters in length and should include a mix of uppercase and lowercase letters, numbers, and special characters. |
c. Delete the initial Administrator password from the platform-settings.json file.
16. Select Done.
17. (OPTIONAL STEP) To determine the status of your license, open the Monitoring>Subsystem>Licensing Subsystem Settings in Composer to confirm the list of features (licensed entities) included with the license. If there are no licensed entities present, you are in limited mode.