File Storage for ThingWorx HA
For a standalone ThingWorx installation, there are typically three established file locations: /ThingworxPlatform, /ThingworxStorage, and /ThingworxBackupStorage. And within the /ThingworxStorage location, the initial file repository is created by default. For the HA deployment, there are a few rules and changes to be made.
/ThingworxPlatform Folder
The ThingworxPlatform folder contains required files that are read upon startup of a ThingWorx instance. These files are:
• platform-settings.json
• keystore-password
• license_capability_response.bin (or variants of this file name)
For a ThingWorx HA configuration, each ThingWorx server should maintain a local /ThingworxPlatform folder. The primary reason is to maintain separate licensing content.
The following content needs to be kept synchronized across all ThingWorx HA servers. Once the file is built or generated, and anytime they are modified on one ThingWorx server, the content should be propagated to all other ThingWorx servers in its HA configuration.
• platform-settings.json
• keystore-password
For the licensing content, each ThingWorx server must maintain both its own license file and the trust stores that are created upon initial activation.
You can use the following process to establish these files in /ThingworxPlatform of each ThingWorx server:
1. Create /ThingworxPlatform on all ThingWorx servers. The folder structure must be the same on all ThingWorx servers in the HA configuration.
2. Build the platform-settings.json to suit the system environment and save it to /ThingworxPlatform of the initial ThingWorx server (the first ThingWorx server to be started in the HA configuration).
3. Start the initial ThingWorx server and ensure that it is fully operational and can use all expected licensed functions. At this point, there should be three files within /ThingworxPlatform:
◦ platform-settings.json
◦ keystore-password
◦ successful_license_capability_response.bin
4. Shutdown the initial ThingWorx server.
5. Copy the three files from the initial server to the /ThingworxPlatform folder of the other server or servers.
6. In the other servers, rename the license file from successful_license_capability_response.bin to license_capability_response.bin.
7. Start, test, and stop the other ThingWorx servers one at a time to ensure that all licensed functionality is available.
The default location for the ThingworxPlatform folder is /ThingworxPlatform. You can set a non-default location through the environment variable THINGWORX_PLATFORM_SETTINGS. The variable must be established in the Tomcat operating system user environment before Tomcat with ThingWorx is started. Ensure that the folder referenced by THINGWORX_PLATFORM_SETTINGS exists and that the Tomcat operating system user has read/write permissions to it.
/ThingworxStorage
The /ThingworxStorage folder should be maintained separately on each ThingWorx server. The primary reason for this is to maintain separate logs for each ThingWorx server.
In this case, the keystore.jks file needs to be distributed to all ThingWorx servers to ensure they are using the same key. The process to accomplish this is:
1. Create /ThingworxStorage on all ThingWorx servers. The folder structure must be the same on all ThingWorx servers in the HA configuration.
2. Have ThingWorx fully operational on the leader.
3. Copy /ThingworxStorage/keystore.jks from the leader and install it in /ThingworxStorage for the Standby server or servers.
The location of /ThingworxStorage is managed in the BasicSettings section of platform-settings.json.
/ThingworxBackupStorage
The primary use of /ThingworxBackupStorage is to back up the H2 database. As H2 is not supported for ThingWorx HA configurations, this location is not used. However, its existence is still expected at runtime.
• It is sufficient to create this location on each ThingWorx server to avoid any logged errors.
• Set the "EnableBackup": false in the platform-settings.json file avoid unnecessary processing in a HA environment.
The location of /ThingworxBackupStorage is managed in platform-settings.json. The folder structure must be the same on all ThingWorx servers.
Root File Repository
The root file repository must be located on a shared file system volume where all ThingWorx servers have equal read/write access to it.
File share considerations:
• A Network Attached Storage (NAS) offering or the cloud equivalent is a common solution to providing a shared file system.
• The NAS offering should have its own High Availability solution to support this ThingWorx HA implementation.
• The volume must be mounted to the server before a ThingWorx instance is started.
• The operating system user running Tomcat services on each ThingWorx server must have read/write permissions to the file share location where the repository is established.
• The mount location must be the same on each ThingWorx server.
The location of the root file repository folder must be added to the system’s platform-settings.json discussed earlier. The parameter FileRepositoryRoot and a shared file location should be added to the BasicSettings section. The value should list the folder location where the repository is to be established. For example, if the initial repository folder is to be established at /ThingworxFileRepository/repository, then the addition to platform-settings.json should be:
"FileRepositoryRoot":"/ThingworxFileRepository"
 |
If the FileRepositoryRoot parameter is not specified in the platform-settings.json file, the default repository location (/ThingworxStorage) will be used.
|
|
|
If the location defined in FileRepositoryRoot is not available for any reason, ThingWorx will abort at startup.
|