ThingWorx Foundation Installer for Linux

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

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

If an existing installation is found during this process, the installer will upgrade ThingWorx Foundation. Fore 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 Linux with Azure PostgreSQL Flexible 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.

◦ Red Hat Enterprise Linux (RHEL) with Administrator access.

RHEL 8.2 has enhanced security hardening. Installations of ThingWorx Foundation on RHEL 8.2 using the installer should be in the /opt directory to avoid issues with permissions. You can choose to install in a directory of your choice under the /optdirectory.

◦ Java JDK installed

Append the java/bin in the PATH environment variable.

◦ PostgreSQL database

◦ The following table lists the applicable prerequisites:

Database Connection	Prerequisites
Remote	Install the psql client that is compatible with your PostgreSQL version. You can run the following command to install the psql client: yum install rh-postgresql96-postgresql-syspaths

B.) Prerequisites for Linux 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 Linux 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.

◦ Red Hat Enterprise Linux (RHEL) with Administrator access

◦ Java JDK installed

Append the java/bin in the PATH environment variable.

◦ PostgreSQL database

◦ 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 must have access to a PostgreSQL server. • You must have PostgreSQL installed, and the path to PostgreSQL/bin should be in the PATH environment variable. • 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. • You allow 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. You can run following command to install the psql client: yum install rh-postgresql96-postgresql-syspaths

Database Connection

Prerequisites

Local

• The host on which ThingWorx Foundation is to be installed must have access to a PostgreSQL server.

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

• 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.

• You allow 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. You can run following command to install the psql client:

yum install rh-postgresql96-postgresql-syspaths

C.) Prerequisites for Linux 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.

To run the ThingWorx Foundation installer for Linux 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.

• Red Hat Enterprise Linux (RHEL) with Administrator access

• Java JDK installed

Append the java/bin in the PATH environment variable.

• Microsoft SQL Server database

• 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.

• The host on which ThingWorx Foundation is to be installed must have access to Microsoft SQL Server.

• A valid Microsoft SQL client is installed (sqlcmd) and is available in the PATH environment variable.

• A Microsoft SQL user with administrator rights.

• Install sqlcmd.

For installation instructions, see https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-2017#RHEL.

After installation, run the following:

ln -s /opt/mssql-tools/bin/sqlcmd /usr/bin/sqlcmd

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 Read & Write & Execute permissions granted to the owner and group of the Administrator user (for example, the root user).

The keystore file must also be accessible based on the permissions of its parent directories. The directory containing the keystore file must have Execute permission for other users, which allows users besides the owner and group profiles to access folders and their files. The Execute permission on the directory allows Tomcat to access the files and folders, so Tomcat can read the keystore file.

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. When prompted, enter the domain name for the server. For example, myserver.mycompany.com.

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

6. When prompted, enter the keystore password.

E.) Prerequisites for Running the Installer Over Red Hat Enterprise Linux 9.0

• PTC recommends the following dimensions to view the complete installer window.

◦ Font: Canterell Regular

◦ Size: 11

◦ Screen Resolution: 1920:1080

• When the installer is executed in GUI mode over Red Hat 9.0, you must have dependencies installed to support the installer’s graphical interface. Before executing the installer, verify that the gtk2 package is installed on the environment. To verify whether the package exists on the operation system, execute the following command:

$ rpm -q gtk2

If the package is installed, the output should be the package name installed. If the package is not installed on the environment, the output will be the following:

"package gtk2 is not installed"

F.) Installing ThingWorx Foundation on Linux

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

If installing ThingWorx on an Azure VM, see section G, Additional Installer Functions and Troubleshooting.

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-Linux-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-Linux-mssql.

3. Extract the build.

4. For PostgreSQL or Azure PostgreSQL Flexible server, execute ThingWorxFoundationPostgres-x.x.x-x86_64.run.

For Microsoft SQL Server, execute ThingWorxFoundationMSSQL-x.x.x-x86_64.run.

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.

If you try to install ThingWorx Foundation outside of the /opt directory, the install may not succeed. RHEL enforces security restrictions for operating systems, which are outside of the control of the installer. If this happens, you should install in the /opt directory.

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 screen 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 and you can now use ThingWorx Foundation.

G.) 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.

H.) 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.

I.) Additional Installer Functions and Troubleshooting

Starting/Stopping ThingWorx Foundation Services on Linux

1. Log in to the ThingWorx host as a user with administrative rights (execute sudo).

2. To start the services, enter sudo systemctl start ThingWorx-Foundation.

3. To stop the services, enter sudo systemctl stop ThingWorx-Foundation.

Installer Log Files

◦ Installation logs:

▪ ${installdir}/installer/logs/ThingWorxFoundation_install.log

For example: /opt/ThingWorxFoundation/installer/logs/ThingWorxFoundation_install.log.

◦ Running logs:

▪ ${installdir}/ThingworxStorage/logs/

For example: /opt/ThingWorxFoundation/ThingworxStorage/logs/.

◦ For abort or failure:

▪ ${system_temp_directory}/ThingWorxFoundation_Failed_installs/

For example: /tmp/ThingWorxFoundation_Failed_installs/.

◦ Uninstall logs:

▪ ${system_temp_directory}/bitrock_installer_(pid).log

The log file name has the prefix bitrock. For example: /tmp/bitrock_installer_3008.log.

Uninstalling a ThingWorx Foundation Installer-based Installation

1. Navigate to the ThingWorx Foundation installation location.

2. Execute ThingWorxFoundation_uninstall.dat.

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 Linux, 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 Linux, 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. Copy the path of the Java 11 installation directory under the location of the Java executable.

You can execute alternatives --display java | grep 'family java-11' | cut -d' ' -f1. The output should show the Java executable location, for example: /usr/lib/jvm/java-11-openjdk-11.0.8.10-0.el8_2.x86_64/bin/java. Here, you copied /usr/lib/jvm/java-11-openjdk-11.0.8.10-0.el8_2.x86_64, which is used to configure the ThingWorx-Foundation service.

3. Stop the ThingWorx-Foundation service using systemctl stop ThingWorx-Foundation.service.

4. Back up ThingWorx-Foundation service. For example: /etc/systemd/system/ThingWorx-Foundation.service.backup.

5. To edit the ThingWorx-Foundation service configuration, edit the ThingWorx-Foundation.service environment as follows:

a. In JAVA_HOME, point to the Java 11 installation directory. For example: Environment='JAVA_HOME=/usr/lib/jvm/java-11-openjdk-11.0.8.10-0.el8_2.x86_64'.

b. From CATALINA_OPTS, remove the following:

-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: /opt/ThingWorxFoundation.

d. To CATALINA_OPTS, add the following:

-Xlog:gc:file=/opt/ThingWorxFoundation/tomcat/current/logs/gc.log:time,level,tags

Make sure that you do not have spaces in the parameter string, or else Tomcat will fail to use Java.

6. Execute the following:

# systemctl daemon-reload

7. Start the ThingWorx-Foundation service using systemctl start ThingWorx-Foundation.service.

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

[L: INFO] [O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================
[L: INFO] [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: Linux
[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: 4.18.0-193.6.3.el8_2.x86_64
[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: N/A
[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: /usr/lib/jvm/java-11-openjdk-11.0.8.10-0.el8_2.x86_64
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] JVM Max Memory: 2048 (MB)
[O: c.t.s.ThingWorxServer] [I: ] [U: SuperUser] [S: ] [P: ] [T: main] ========================================

9. Remove the backup ThingWorx-Foundation.service.backup.

Installing ThingWorx on an Azure VM

For users preparing to install ThingWorx on an Azure VM, you may encounter the following error:

Script stderr:
Errors during downloading metadata for repository 'rhel-8-for-x86_64-baseos-eus-rhui-rpms':
- Curl error (56): Failure when receiving data from the peer for https://rhui-3.microsoft.com/pulp/repos/content/eus/rhel8/rhui/8.2/x86_64/baseos/os/repodata/repomd.xml [OpenSSL SSL_read: error:14094415:SSL routines:ssl3_read_bytes:sslv3 alert certificate expi red, errno 0]
- Curl error (56): Failure when receiving data from the peer for https://rhui-1.microsoft.com/pulp/repos/content/eus/rhel8/rhui/8.2/x86_64/baseos/os/repodata/repomd.xml [OpenSSL SSL_read: error:14094415:SSL routines:ssl3_read_bytes:sslv3 alert certificate expi red, errno 0]
- Curl error (56): Failure when receiving data from the peer for https://rhui-2.microsoft.com/pulp/repos/content/eus/rhel8/rhui/8.2/x86_64/baseos/os/repodata/repomd.xml [OpenSSL SSL_read: error:14094415:SSL routines:ssl3_read_bytes:sslv3 alert certificate expi red, errno 0]
Error: Failed to download metadata for repo 'rhel-8-for-x86_64-baseos-eus-rhui-rpms': Cannot download repomd.xml: Cannot download repodata/repomd.xml: All mirrors were tried

If you do, you must first disable the lookup of the package metadata before running the installation by executing the following command:

dnf update --disablerepo=* --enablerepo='*microsoft*' rhui-azure-rhel8-eus

PostgreSQL RPM Repository GPG Key Update

For RedHat Enterprise Linux, PostgreSQL users may see the following error during ThingWorx installation:

Errors during downloading metadata for repository 'epel-cisco-openh264':
Errors during downloading metadata for repository 'pgdg15':
- Curl error (37): Couldn't read a file:// file for file:///etc/pki/rpm-gpg/RPM-GPG-KEY-PGDG [Couldn't open file /etc/pki/rpm-gpg/RPM-GPG-KEY-PGDG]
Error: Failed to retrieve GPG key for repo 'pgdg15': Curl error (37): Couldn't read a file:// file for file:///etc/pki/rpm-gpg/RPM-GPG-KEY-PGDG [Couldn't open file /etc/pki/rpm-gpg/RPM-GPG-KEY-PGDG]

PostgreSQL published new repository RPMs with new GPG keys. For more information, see PostgreSQL RPM repository GPG key update - 3 January 2024.

This causes an error for users on Red Hat 9 and Red Hat 8. Follow either of the following resolutions suggested by PostgreSQL:

1. For RedHat 9, execute the following command:

dnf --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

For RedHat 8, execute the following command:

dnf --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

2. Rename the repository file. The new repository file will be created with the .rpmnew suffix. Rename it using the file name after making the same changes in the previous configuration file. For example,

mv pgdg-redhat-all.repo.rpmnew pgdg-redhat-all.repo

Was this helpful?