ThingWorx Tutorials: ThingWorx 8.4 Installer for RHEL 7.5

[#1]

Contents:

• Introduction
• Prerequisites
• Installing Java
• Installing PostgreSQL
• Running the Installer
• Post Installation Steps
• Troubleshooting tips

Introduction:

Starting with ThingWorx 8.4, PTC released a new way to install a fresh ThingWorx environment.  This installer takes care of all the permissions, database scripts, credential encryption, and tomcat options that previously needed to be done manually.  More information on the installer can be found in the ThingWorx Help Center

NOTE: This is different than the Docker installer we have available in earlier releases.

As of right now, the installation guide has very basic instructions for the installer.  The purpose of this post is to show you from start to finish what the process looks like.  For this example, I chose to deploy PostgreSQL 10 on the local system to keep things simple.

Prerequisites:

• Download the latest Java 8 SE JDK RPM for RHEL
• Get your database ready:
• If you're accessing a remote PostgreSQL instance, make sure PSQL is installed and working on your ThingWorx Server
• Download the appropriate installer from support.ptc.com
• Ensure the RHEL user that will be executing the installer has SUDO privileges

NOTE: There are pieces of the manual installation guide that I had to reference in order to get JAVA and PostgreSQL properly configured.

Installing Java:

• Per Page 83, I downloaded the latest Linux x64 RPM for Java 8 SE JDK (201) and followed steps 2-8 to configure Java.
• For step 5, I needed to use the -f parameter listed in the guide under NOTE
• Step 7 make sure you don't accidentally select OpenJDK if it was preinstalled

Installing PostgreSQL:

• I'm following along with the Version 10 download instructions found on https://www.postgresql.org/download/linux/redhat/
  • NOTE: this needs root access, so run all the commands with SUDO
• Install the client packages Postgresql10
• I will Install the optional server packages postgresql10-server since this is a local PostgreSQL instance
• Complete step 7 to enable automatic start. 
• We need to set the postgres password so our ThingWorx installer is able to create our thingworx user and the database.  This can be done with the following command:
  • NOTE: Since this is the master user for your database, it is highly recommended to use a password that has a combination of case, numbers, letters, and symbols
• Sudo passwd postgres
• Although, this may be redundant, I also run the following command to update the password used in PostgreSQL :
  • sudo -u postgres psql -c "ALTER ROLE postgres WITH password '<password from above>'"

• Navigate to /var/lib/pgsql/10/data and open pg_hba.conf for editing
• Review page 91 of the Installation guide to determine which setting best applies to your business needs
• In the same directory open postgresql.conf
• Scroll down to "listen_addresses" line and un-comment it. 
• This would  be the place to make changes if you expect remote connections to access the database.  If it is local, then the default of localhost is fine
• Restart PostgreSQL to apply these changes:
• Sudo service postgresql-10 restart

Running the Installer:

Everything should be in place now to run our installer. 

• Extract the ThingWorxFoundationPostgres-1.2.0-SNAPSHOT.run file to the ~ (home) directory
• Execute the .run file:
  • NOTE: If it doesn't let you execute the file, it may not have extracted as an executable.  Run the below command to make it executable then try again:
  • Chmod -x ThingWorxFoundationPostgres-1.2.0-SNAPSHOT.run
• Sudo ./ThingWorxFoundationPostgres-1.2.0-SNAPSHOT.run

At this point you'll be going through text to setup your installation settings.  I'll briefly list out the order you'll see them below:

• Terms and conditions and whether you agree
• Where you want ThingWorx deployed (/opt by default)
• NOTE: this folder will contain ThingworxStorage/ ThingworxPlatform/ tomcat/ etc…
• Installation Configuration user (twxfoundation by default).  This step creates a user in RHEL that will have ownership of Tomcat, various ThingWorx directory's, etc
• ThingWorx Administrator Password.  Used to login to ThingWorx Composer.
• WRITE THIS DOWN SOMEWHERE!  You cannot retrieve this password, and most likely will require you to do a fresh installation if you forget it
• Tomcat Port http (8080)
• Tomcat SSL port (8443)
• Use SSL
• For simplicity, I chose not to use it for this exercise
• PostgreSQL information
• Host Name : mine is local, so localhost
• Port (5432)
• Administrator Username (Administrator) : use postgres here, since that's the DB user password we updated above
• Admin password : use the postgres password
• ThingWorx Database login username (twadmin).  This user will be created in PostgreSQL and be tied to our ThingWorx database
• ThingWorx database login password:
• NOTE There's no place to re-enter your password, so make sure you write this down.

Unexpected issue:

For this particular install, I kept running into a failure saying "Warning: Failed to validate the PostgreSQL connection.  Check the information you entered".  I opened another putty connection and, as root, navigated to /var/lib/pgsql/10/data/log and opened the postgresql log to find the following:

2019-02-28 17:10:30.678 UTC [93377] LOG:  could not connect to Ident server at address "::1", port 113: Connection refused

2019-02-28 17:10:30.678 UTC [93377] FATAL:  Ident authentication failed for user "postgres"

2019-02-28 17:10:30.678 UTC [93377] DETAIL:  Connection matched pg_hba.conf line 84: "host    all             all             ::1/128                 ident"

The solution for me was to go into the pg_hba.conf and change the IPv6 local connections from ident to md5.  Again, make sure you are reading through the PostgreSQL documentation and adjusting these properties in a way that meets both your security and business needs.

Once the change was made, I restarted postgresql, and switched back over to my Putty instance that had the installer going.

• A summary pops up for a few items, and then it asks if you're ready to continue
• NOTE: The progress bar goes to 100% pretty quickly, and doesn't appear to move.  Just let it sit for a few minutes while it finishes up
• Copy the Thingworx Device ID for future reference
• To check if ThingWorx is running, run 'sudo service Thingworx-Foundation status' in your command line
• If it is active (running) try to access it with a remote browser:
  • More information around the command Firewalld can be found here 
• http://<thingworxurl>:<tomcatport>/Thingworx
• NOTE: If it just hangs, check your firewall to make sure the port is open for external communication

Post Installation Steps:

Licensing:

• Navigate to /opt/ThingWorxPostgres-1.2.0-SNAPSHOT/licensingconfigurator and run the twx-licensing-configurator.run as SUDO
• Choose whether or not you want PTC to store your credentials and download the license for you, or if you want to manually download the license yourself from http://support.ptc.com -> Manage Licenses (bottom right)
• For this example, I manually downloaded the license
• Move the license file over to the ThingWorx Server
• Since you're running the licensingconfigurator as SUDO, don't put this file into your user's home directory.  Instead, put it into /tmp
• NOTE: Change the downloaded filename to license_capability_response.bin.  Otherwise the file will not be recognized
• Then it will ask for your ThingWorx Administrator password
• This appears to be used for verification after the license is in place, and it sees if it can successfully log into your system
• Once it has completed, and assuming it says "Setup has finished configuration licensing for ThingWorx", open up a web browser and login as Administrator -> Monitor -> Subsystems -> Licensing Subsystem and verify that your licensing information looks correct on the system

Extensions:

• Extra security has been added as of 8.4 around importing Extensions.  More details can be found in the Help Center
• In short, adding extensions is disabled by default, and you need to add some lines into your /ThingworxPlatform/platform-settings.json under the "PlatformSettingsConfig" section.
• For example, here is what I added:

 "PlatformSettingsConfig": {

                "BasicSettings": {

                        "BackupStorage": "/opt/ThingWorxPostgres-1.2.0-SNAPSHOT/ThingworxBackupStorage",

                        "DatabaseLogRetentionPolicy": 7,

                        "EnableBackup": true,

                        "EnableHA": false,

                        "EnableSystemLogging": true,

                        "HTTPRequestHeaderMaxLength": 2000,

                        "HTTPRequestParameterMaxLength": 2000,

                        "InternalAesCryptographicKeyLength": 128,

                        "Storage": "/opt/ThingWorxPostgres-1.2.0-SNAPSHOT/ThingworxStorage"

                },

                "ExtensionPackageImportPolicy": {

                       "importEnabled": true,

                       "allowJarResources": true,

                       "allowJavascriptResources": false,

                       "allowCSSResources": false,

                       "allowJSONResources": false,

                       "allowWebAppResources": false,

                       "allowEntities": true,

                       "allowExtensibleEntities": false

}

        }

• Make sure you set the appropriate items above to true based on what your extensions require

Troubleshooting:

If things backfire, depending on where you are in the setup process, the following logs should be looked at for clues on the failure:

• Installation:
  • /tmp/bitrock_installer.logs
  • I believe the installation directory (default /opt/ThingWorxPostgres-1.2.0-SNAPSHOT) will contain a log file if the installer fails
  • /opt/ThingWorxPostgres-1.2.0-SNAPSHOT/ThingworxStorage/logs/ (need root access)
  • /opt/ThingWorxPostgres-1.2.0-SNAPSHOT/tomcat/apache-tomcat-<version>/logs
• PostgreSQL
  • (requires root): /var/lib/pgsql/10/data/log
• LicensingConfigurator :
  • /opt/ThingWorxPostgres-1.2.0-SNAPSHOT/licensingconfigurator