ThingWorx Foundation Installer for Windows

Installation and Upgrade > Installing ThingWorx > ThingWorx Foundation Installer > ThingWorx Foundation Installer for Windows

A.) Prerequisites for Windows Installer with Azure PostgreSQL Flexible Server

If an existing installation is found during this process, the installer will upgrade ThingWorx Foundation. For more information, see Using the Installer to Upgrade ThingWorx Foundation.

It is not recommended to use spaces in file names for the ThingWorx Installer. The ThingWorx Installer will encounter issues if you attempt to install ThingWorx using a file path that includes space characters. If you must use spaces, Administrators should enable Windows support for 8dot3.

• You have reviewed the information and general prerequisites outlined in the ThingWorx Foundation Installer help topic.

• To run the ThingWorx Foundation Installer for Windows with Azure PostgreSQL Flexible Server, you must have the following. For more information about supported versions, see System Requirements.

◦ Java 11 installed

Java 11 is required for 9.2.0 and later.

• Set the Java_Home variable to use the Java 11 installation directory.

◦ Windows with Administrator access.

◦ ThingWorx database configured with connections allowed.

◦ Database user configured as the owner of the ThingWorx database with the following:

▪ All privileges granted to this user on the ThingWorx database.

▪ The can login property set to yes.

This database user will be entered as the ThingWorx database username in the installer.

The following table lists the applicable prerequisites:

Database Connection	Prerequisites
Remote	• Install the psql client that is compatible with your PostgreSQL version. • Add the installed psql to the PATH environment variable by following these steps: a. Download pgadmin4-4.1-x86.exe from PostgreSQL File Browser. b. Install the pgadmin client. c. Update the PATHenvironment variable to append to the path where the pgadmin client is installed.

B.) Prerequisites for Windows Installer with PostgreSQL

If an existing installation is found during this process, the installer will upgrade ThingWorx Foundation. For more information, see Using the Installer to Upgrade ThingWorx Foundation.

• You have reviewed the information and general prerequisites outlined in the ThingWorx Foundation Installer help topic.

• To run the ThingWorx Foundation installer for Windows with PostgreSQL, you must have the following. For information about supported versions, see System Requirements.

◦ Java 11 installed

Java 11 is required for 9.2.0 and later.

• Set the JAVA_HOME variable to use the Java 11 installation directory.

◦ Windows with Administrator access

◦ ThingWorx database configured with connections allowed and encoding set to UTF-8

▪ The database property Connection_LIMIT must be set to -1, which is the default value and allows unlimited connections to the database for all authenticated users.

◦ A database user configured as the owner of the ThingWorx database with the following:

▪ All privileges granted to this user on the ThingWorx database.

▪ The can login property set to yes.

This database user will be entered as the ThingWorx database username in the installer.

◦ A local or remote database connection. The following table lists the applicable prerequisites:

Database Connection	Prerequisities
Local	• PostgreSQL is installed, and the path to PostgreSQL/bin should be in the PATH environment variable. • Java JDK installed Ensure that java/bin is in the PATH environment variable. • Allowed connections to PostgreSQL from the ThingWorx Foundation host by updating the pg_hba.conf file. For example, if ThingWorx Foundation is installed on the same host as PostgreSQL, you can update the pg_hba.conf file to set the password authentication method to md5, password, or trust. However, we do not recommend setting it to trust. For more information about the pg_hba.conf file and password authentication methods, see the PostgreSQL.org Website. The following is an example of the pg_hba.conf file with password authentication set to md5: $ Edit pg_hba.conf for following: ... # "local" is for Unix domain socket connections only local all all md5 # IPv4 local connections: host all all 127.0.0.1/32 md5 # IPv6 local connections: host all all ::1/128 md5
Remote	• Install the psql client that is compatible with your PostgreSQL version. • Add the installed psql to the PATH environment variable. You can follow these steps: a. Download pgadmin4-4.1-x86.exe fromhttps://www.postgresql.org/ftp/pgadmin/pgadmin4/v4.1/windows/. b. Install the pgadmin client. c. Update the PATH environment variable to append to the path where pgadmin client is installed.

Database Connection

Prerequisities

Local

• PostgreSQL is installed, and the path to PostgreSQL/bin should be in the PATH environment variable.

• Java JDK installed

Ensure that java/bin is in the PATH environment variable.

• Allowed connections to PostgreSQL from the ThingWorx Foundation host by updating the pg_hba.conf file.

For example, if ThingWorx Foundation is installed on the same host as PostgreSQL, you can update the pg_hba.conf file to set the password authentication method to md5, password, or trust. However, we do not recommend setting it to trust. For more information about the pg_hba.conf file and password authentication methods, see the PostgreSQL.org Website.

The following is an example of the pg_hba.conf file with password authentication set to md5:

$ Edit pg_hba.conf for following:
...
# "local" is for Unix domain socket connections only
local all all md5
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5

Remote

• Install the psql client that is compatible with your PostgreSQL version.

• Add the installed psql to the PATH environment variable. You can follow these steps:

a. Download pgadmin4-4.1-x86.exe fromhttps://www.postgresql.org/ftp/pgadmin/pgadmin4/v4.1/windows/.

b. Install the pgadmin client.

c. Update the PATH environment variable to append to the path where pgadmin client is installed.

C.) Prerequisites for Windows Installer with SQL Server

If an existing installation is found during this process, the installer will upgrade ThingWorx Foundation. For more information, see Using the Installer to Upgrade ThingWorx Foundation.

• You have reviewed the information and general prerequisites outlined in the ThingWorx Foundation Installer help topic.

To run the ThingWorx Foundation installer for Windows with Microsoft SQL Server, you must have the following. For information about supported versions, see System Requirements.

• Java 11 installed

Java 11 is required for 9.2.0 and later.

• Set the JAVA_HOME variable to use the Java 11 installation directory.

• Windows with Administrator access

• A ThingWorx database configured with the following settings:

◦ Set the Collate property to Latin1_General_100_CS_AS_SC.

◦ Set the following properties to ON:

▪ READ_COMMITTED_SNAPSHOT

▪ ALLOW_SNAPSHOT_ISOLATION

• A login for Microsoft SQL Server with SQL Server Authentication

The password for this login is the ThingWorx Database Login Password.

◦ A database user for this login configured as the owner and within the public role.

This user should have a default schema of dbo, an owned schema of db_owner, and be a member of db_owner.

• A local or remote database connection. The following table lists the applicable prerequisites:

Database Connection	Prerequisites
Local	• The host on which ThingWorx Foundation is to be installed has access to Microsoft SQL Server. • A valid Microsoft SQL client (sqlcmd) is installed and is available in the PATH environment variable. • Java JDK installed. java/bin is in the PATH environment variable.
Remote	• sqlcmd is installed and available in the PATH environment variable.

D.) Prerequisites for Enabling SSL/TLS in the Installer: Creating a Keystore

On the Properties for ThingWorx Foundation screen in the installer, the Use SSL/TLS for a secure connection checkbox is selected by default. You can disable the use of SSL/TLS in the installer by clearing this checkbox. If you choose to keep the default setting and use SSL/TLS, you must generate a Java keystore (.jks) file before running the installer. The Java keystore (.jks) file must have the following security permissions:

• The keystore file must have the Read and Read & Execute permissions granted to the Network Service user profile on Windows.

There are a number of ways you can generate a keystore; one way is as follows:

1. Go to Java/bin.

2. To create the Tomcat Keystore File (.jks file), execute the following command: keytool -genkey -alias selfsigned -keyalg RSA -keystore keyStore.jks -keysize 2048 -storetype jks

3. Enter a password for the keystore. You will need this password later to configure the server.

Password cannot contain or be enclosed in single quotes ('), double quotes (''), or section(§).

4. Enter the other values, such as organizational unit and organization.

5. When prompted, enter the keystore password.

E.) Installing ThingWorx Foundation on Windows

1. Ensure that the prerequisites described in the above sections are met.

2. For PostgreSQL or Azure PostgreSQL Flexible server, from support.ptc.com under Download Software > Order or Download Software Updates > ThingWorx Foundation > Release <latest> > ThingWorx PostgreSQL > Most Recent Version, download ThingWorx-Platform-Foundation-Installer-x-x-x-Windows-postgres.

For Microsoft SQL Server, from support.ptc.com under Download Software > Order or Download Software Updates > ThingWorx Foundation > Release <latest> > ThingWorx Mssql > Most Recent Version, download ThingWorx-Platform-Foundation-Installer-x-x-x-Windows-mssql.

3. Extract the build.

4. For PostgreSQL or Azure PostgreSQL Flexible server, execute ThingWorxFoundationPostgres-9.x.x-x64.exe.

For Microsoft SQL Server, execute ThingWorxFoundationMSSQL-9.x.x-x64.exe.

5. Step through the installer screens.

On the Properties for ThingWorx Foundation screen, the Use SSL/TLS for a secure connection checkbox is selected by default. You can disable the use of SSL/TLS in the installer by clearing this checkbox. If you choose to use SSL/TLS, enter the keystore values as generated in the prerequisites noted above.

The SSL Mode parameter is required for the Azure PostgreSQL Flex server. 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.

6. On the last installer screen, the Open License Configurator checkbox is selected by default. If this checkbox is selected, the License Configurator opens after the installer completes and closes. If you deselect the Open License Configurator checkbox, the installer closes and the License Configurator does not automatically open.

a. Click Next on the Setup : Configure licensing for ThingworxFoundation for Postgres or Setup : Configure licensing for ThingworxFoundation for Mssql screen.

b. Use License Configurator to connect to the PTC license server or configure ThingWorx Foundation to use the pre-downloaded license.

c. Step through the license screens.

7. Your ThingWorx Foundation installation is complete.

For information about increasing memory for Tomcat after installation, see PTC Support Article CS306401.

F.) Enabling Content Security Policy (Manual Step)

If you are installing ThingWorx 5.0.1 and newer, you need to manually update platform-settings.json to support CSP. The ThingWorx Foundation installer does not support Enabling or Disabling CSP functionality. By default, CSP is disabled until enabled in platform-settings.json.

To manually update platform settings, 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
},

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.

G.) Connecting to the ThingWorx Foundation Server

1. Access the ThingWorx Foundation URL.

For example: https://<hostname>:<port>/Thingworx/Composer.

The ThingWorx Foundation URL will be different depending on your configuration of SSL/non-SSL and the ports used during setup. SSL is enabled by default; however, you can disable the use of SSL/TLS. See the Prerequisites for Enabling SSL/TLS in the Installer section above.

2. Provide user credentials.

The username is Administrator and the password is what was entered during setup.

H.) Additional Installer Functions and Troubleshooting

Starting/Stopping ThingWorx Foundation Services on Windows

1. Navigate to Services.msc.

2. Find the ThingWorx-Foundation service.

3. Start or stop it.

Locating Installer Log Files

• Installation logs:

◦ ${installdir}\installer\logs\ThingWorxFoundation_install.log

For example: C:\Program Files (x86)\ThingWorxFoundation\installer\logs\ThingWorxFoundation_install.log.

• Running logs:

◦ ${installdir}\ThingworxStorage\logs\

For example: C:\Program Files (x86)\ThingWorxFoundation\ThingworxStorage\logs\.

• For abort or failure:

◦ ${system_temp_directory}\ThingWorxFoundation_Failed_installs\

For example: C:\Users\vagrant\AppData\Local\Temp\ThingWorxFoundation_Failed_installs\.

• Uninstall logs:

◦ ${system_temp_directory}\bitrock_installer_(pid).log

The log file name has the prefix bitrock. For example: C:\Users\vagrant\AppData\Local\Temp\bitrock_installer_3008.log.

Uninstalling a ThingWorx Foundation Installer-based Installation

1. Navigate to the ThingWorx Foundation installation location.

2. Execute ThingWorxFoundation_uninstall.exe.

3. When prompted, click OK to confirm that you want to continue with the uninstallation.

4. When the uninstallation is complete, the setup is deleted.

Deleting the ThingWorx Database from PostgreSQL

1. From the command line in Windows, open a connection to the PostgreSQL database.

For example, enter psql -U admin -h dbhost.

2. If you are using the default database name, execute the DROP DATABASE thingworx; command.

Or, if you customized the database name, execute the DROP DATABASE <your database name>; command.

Deleting the ThingWorx Database from Microsoft SQL

1. From the command line in Windows, open a connection to the Microsoft SQL database.

For example, enter sqlcmd -U admin -s ‘dbhost\dbservicename,port’.

2. If you are using the default database name, execute the DROP DATABASE thingworx; GO; command.

Or, if you customized the database name, execute the DROP DATABASE <your database name>; GO; command.

Upgrading to Java 11 for ThingWorx 9.0 and 9.1

If you used the installer to install or upgrade ThingWorx 9.0.x or 9.1.x with Java 8 and want to use Java 11.0.8, follow the steps below:

1. Install Java 11.

2. Set the /bin directory in the PATH system variable.

3. Set the JAVA_HOME variable to use the Java 11 installation directory.

4. Verify that the location of the jvm.dll file is under the Java 11 installation directory. For example: C:\Program Files\Java\jdk-11.0.8\bin\server\jvm.dll.

Java 11 does not have a JRE directory. Therefore, the jvm.dll file will not be located under a JRE folder as in Java 8.

5. Stop the ThingWorx-Foundation service.

6. Run CMD as an administrator.

7. Navigate to the Tomcat /bin directory under the ThingWorx Foundation installation directory. For example: cd C:\Program Files (x86)\ThingWorxFoundation\tomcat\apache-tomcat-9.0.37\bin.

8. To edit the ThingWorx-Foundation service configuration, execute the following: tomcat9w.exe //ES//ThingWorx-Foundation.

The GUI application opens.

9. Navigate to the Java tab on the application and do the following:

a. For the Java Virtual Machine, point to the jvm.dll of the Java 11 installation. For example: C:\Program Files\Java\jdk-11.0.8\bin\server\jvm.dll.

b. Remove the following from Java Options:

-XX:+UseG1GC
-XX:+PrintGCTimeStamps
-XX:+PrintGCDetails
-Xloggc:${CATALINA_HOME}/logs/tomcat-twx-gc.log

${CATALINA_HOME} refers to the Tomcat directory.

c. Copy the installation directory path for ThingWorx Foundation. For example: C:\Program Files (x86)\ThingWorxFoundation.

d. Add the following to Java Options:

-Xlog:gc:file=C:\Program Files
(x86)\ThingWorxFoundation/tomcat/current/logs/gc.log:time,level,tags

10. Choose Apply.

11. Choose OK.

The application closes.

12. Update service parameters using tomcat9.exe by doing the following:

a. Run CMD as an administrator.

b. Execute the following:

tomcat9.exe //US//ThingWorx-Foundation --JavaHome=%JAVA_HOME%
tomcat9.exe //US//ThingWorx-Foundation --Environment="JRE_HOME='%JAVA_HOME%';THINGWORX_PLATFORM_SETTINGS='%THINGWORX_PLATFORM_SETTINGS%';PATH='%PATH%'"

13. Start the ThingWorx-Foundation service.

14. In the Application.log file, confirm that the Java version is 11:

[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ThingWorx System Environment Settings
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] OS: Windows Server 2019
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] OS arch: amd64
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] OS version: 10.0
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] Total Processors: 2
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] Default encoding: UTF-8
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] JAVA vendor: Oracle Corporation
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] JAVA version: 11.0.8
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] JAVA install location: C:\Program Files\Java\jdk-11.0.8
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] JVM Max Memory: 750 (MB)
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================

If you have trouble with the service configuration changes on Windows and would like to see more information, execute the following to log more information to the commons-daemon.log file under /tomat/current/logs/ directory: tomcat9w.exe //ES//ThingWorx-Foundation --LogLevel Debug.

Was this helpful?