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
View full tip
