ThingWorx Foundation File Storage
For a standalone ThingWorx installation, there are typically three established file locations:
• /ThingworxPlatform
• /ThingworxStorage
• /ThingworxBackupStorage
In the /ThingworxStorage location, the initial file repository is created by default. For a clustering deployment, you must make changes and follow some rules.
/ThingworxPlatform
The ThingworxPlatform folder is maintained locally for each server instance and should not be shared. The folder contains the following required files that are read at startup of a ThingWorx instance:
• platform-settings.json
• keystore-password
• license_capability_response.bin (or variants of this file name)
The following content must be kept synchronized across all ThingWorx HA servers:
• platform-settings.json
• keystore-password
Once the files are built or generated, and anytime they are modified on one ThingWorx server, the content should be updated on all other ThingWorx servers in its HA configuration.
For the licensing content, each ThingWorx server must maintain both its own license file and the trust stores that are created on 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.
 |
In the platform-settings.json file, you must update the PlatformId setting to be a unique ID for each server. For more information, see Platform Settings for ThingWorx HA.
|
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 must be located on a shared file system volume where all ThingWorx servers have equal read/write access to it.
The keystore.pfx file is stored in this folder and contains secrets required by the platform. The file is linked to the keystore-password file. You should keep both files secure and backed up. If either file is lost, it will not be possible to decrypt information stored in the database.
Log files will contain all logs from all servers and will be identified by platformId in the log entries.
The location of /ThingworxStorage is managed in the BasicSettings section of platform-settings.json.
For Windows only, when the ThingWorx platform host and the host where the shared storage directory is located are not on a domain, complete the following steps:
|
|
Complete the following steps only if you’re using a local user account to run Apache Tomcat.
|
1. Create a local user account that exists on the ThingWorx Platform host and the host where the shared directory is located.
|
|
This user account must have the same password on both hosts.
|
2. Configure Apache Tomcat to run as the local user account from step 1.
a. Within Services, locate the Apache Tomcat service and select > .
b. Enter the local user account with the user password.
3. Grant the local user account Full Control permissions on the tomcat9.exe file under the Apache Tomcat folder to avoid a Platform Storage initialization failure error.
4. Share the network location with the local user account and grant Full Control permissions.
a. Right-click the network location and select Properties. Click the Share tab.
b. Locate the local user account and select Read/Write.
c. On the Security tab, ensure the local user account has Full Control permissions granted.
5. Set the value of the Storage key under BasicSettings within platform-settings.json to use the full UNC path of the network location. Include additional backslashes for each \ in the path. For example:
◦ Network share location: \\ShareHost\MyThingworxShare
◦ Storage value in platform-settings.json: \\\\ShareHost\\MyThingworxShare
6. Restart Apache Tomcat.
/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.
The location of the root file repository folder must be added to the system’s platform-settings.json. 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.
|
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.