Purpose
Clustered AppBase installation is usually used for moderate to large loads when a single VM can NOT handle all incoming requests and when the system redundancy to increase the system reliability is necessary.
Such installations usually comprise of a multiple Windows VMs with AppBase installed on them and one or few Linux VMs to host Redis, ActiveMQ, Load Balancer and shared data components.
For security purpose it is best to use SSL for the AppBase web-site. We recommend to terminate SSL on the Load Balancer.
Usual best practices is to use the Clustered AppBase installation for QA, UAT and Production environments. While the Production environments may have more VMs in the setup, QA and UAT environments are required to have at least 2 Windows VMs for each QA and UAT environments and they must be configured as close as possible to the Production environment to accommodate proper Change Control procedures.
Checklist
Download and fill out the Clustered Installation Checklist: AppBase Clustered Installation Checklist GA SP1 Update 2.xlsx
For AppBase 6.5 GA SP1 and AppBase 6.5 GA SP1 Update 1 please download this checklist instead: AppBase Clustered Installation Checklist GA SP1.xlsx
For previous AppBase 6.5 GA release please download this checklist instead: AppBase Clustered Installation Checklist GA.xlsx
Loading
Substitution Files Configuration
Download and mount AppBase "ISO image":
Scripts.2.zip archive can be found inside AppBase Installation files directory on the ISO image:
For previous AppBase 6.5 GA release please use this instruction instead:
Download and extract Scripts.2.zip archive with the installation scripts from the Download page: Downloads. The Scripts.2.zip archive is downloaded via "6.5. GA Installation Scripts" url:
If you use AppBase Installation ISO instead then the Scripts.2.zip archive can be found inside AppBase Installation files directory on the ISO image:
Unblocking the downloaded files
You need to unblock the downloaded files no matter which download format you have chosen. This step is necessary for both "Loose files" and "ISO image" formats.
For "ISO image" you need unblock the ISO file and Scripts.2.zip archive you copied from the "ISO image".
Unblock the downloaded files recursively with Powershell command:
Get-ChildItem "PATH_TO_DOWNLOADED_PACKAGES_DIRECTORY" -recurse | Unblock-File
You need to be sure you have unblocked the installation scripts otherwise you may encounter problems the installation scripts failing to load some of the dlls which come with the installation scripts package.
To start PowerShell you need to press "Win+R" keys on your keyboard and type "powershell" in the popup window:
Copy the files from "Templates\Clustered" directory to the directory of your choice. These files will be your new substitution configuration files after you update few values in the _all_substitutions_common.liquid configuration file
Please make sure none of the directories you use for the substitution files or the installation scripts has spaces (" ") in its path.
Open _all_substitutions_common.liquid file and modify the settings from the table below. You need to refer to your Checklist to configure the substitution values
Please read carefully the information below. Even if you are familiar with some of the placeholder values due to your configuration of the Single VM substitution placeholders you still need to read the information carefully because some of the placeholders here may have additional values or difference in application form the way they are used in Single VM installation configuration
Substitution Placeholders
| Placeholder Name | Description | Valid Values | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| SSLMode | Refer to your Checklist
| None, LB, IIS | ||||||||
| SSLCertificatePath | This is only required when placeholder SSLMode = IIS. In this case you need to uncomment both SSLCertificatePath and SSLCertificatePassword and provide them with a full path to the SSL certificate path in pfx format and the certificate password. Only pfx certificates can be installed automatically. If you use DigeCert or other unsupported certificate please use empty values for both SSLCertificatePath and SSLCertificatePassword placeholders and install the certificates manually into IIS after the AppBase installation finishes. | Full patch to the certificate file or empty value | ||||||||
| SSLCertificatePassword | Password or empty value | |||||||||
| DatabaseBrand | Refer to the value "Database Brand and Version". Please use Oracle for Oracle or SqlServer for MS Sql Server | Oracle, SqlServer | ||||||||
| AppBaseRootDirectory | Refer to the value "AppBase Root Directory" from the Checklist. The root directory for all AppBase installation files, for example: D:\AppBase - this is the directory where the installation files will reside and where the AppBase will be installed to | Valid directory | ||||||||
| SharedDirectoriesRoot | Refer to the value "BaseRuntimeDirectory" from the Checklist. Base directory for solution configuration and runtime data on a network share (e.g. \\server1\AppBaseDev). This can be a file share anywhere on network with rights granted to the account configured in AppBaseServicesUsername placeholder to manage this directory and the AppBase must be able to access this share. AppBase does not require Full Control right on that share but it require other management rights to create/read/update/delete any file or subdirectory in this directory. | Valid shared directory accessible to all AppBase VMs | ||||||||
| EffectiveUrlPort | Refer to the value "Effective Port" from the Checklist | Valid port | ||||||||
| EffectiveUrlHost | Refer to the value "Effective HostName" from the Checklist | Valid hostname | ||||||||
| NoReplyEmail | Refer to the value "Noreply Email" from the Checklist. AppBase will use it as a sender when sending notifications to users | Valid email | ||||||||
| AdminEmail | Refer to the value "Admin Email" from the Checklist. AppBase will be sending system related emails to this address | Valid email | ||||||||
| SmtpHost | Refer to the value "Smtp Host" from the Checklist. | Valid smtp host | ||||||||
| SmtpPort | Refer to the value "Smtp Port" from the Checklist. | Valid smtp port | ||||||||
| CryptoProtocol | Refer to the value "Use SSL / TLS" from the Checklist. If you specified "none" then use 0. If you specified "ssl" then use 1. If you specified "tls" then use 2 | 0,1,2 | ||||||||
| SmtpUsername | Refer to the value "Smtp Username" from the Checklist. | Valid smtp user or empty value | ||||||||
| SmtpPassword | Refer to the value "Smtp Password" from the Checklist. | Valid smtp password or empty value | ||||||||
| AppBaseServicesUsername | Refer to the value "Service Username" from the Checklist. | Valid Active Directory user | ||||||||
| AppBaseServicesPassword | Refer to the value "Service Password" from the Checklist. For AppBase 6.5 GA SP1 Update 2 release and above you can use non-alphanumeric characters, for example <, > or & but you need to encode them for substitution files. Below is a table with example for encoding characters.
| Valid Active Directory user password | ||||||||
| AppBaseDatabaseConnectionIdentifier | Use the value provided for "Oracle TNS Alias" in the checklist. AppBase versions preceding "AppBase 6.5 GA SP1 Update 2" does not have this feature and this placeholder. | Empty string or valid "Oracle TNS Alias" known to all AppBase VMs | ||||||||
| OracleTnsAdminPath | Empty string when "Oracle TNS Alias" is not used (when "AppBaseDatabaseConnectionIdentifier" is empty).
AppBase versions preceding "AppBase 6.5 GA SP1 Update 2" does not have this feature and this placeholder. | Empty string when "Oracle TNS Alias" is empty, otherwise valid path to the TNS admin directory (the directory must contain valid tnsnames.ora file that have the "Oracle TNS Alias" registered) | ||||||||
| DatabaseServer | Refer to the value "Database Server Host" from the Checklist. The placeholder can be left empty when placeholder "AppBaseDatabaseConnectionIdentifier" is not empty When using AppBase versions preceding "AppBase 6.5 GA SP1 Update 2" release use this instruction instead (this field is required for all version before SP1 Update 2): Refer to the value "Database Server Host" from the Checklist. | Valid server host/ip | ||||||||
| DatabasePort | Refer to the value "Database Server Port" from the Checklist. The placeholder can be left empty when placeholder "AppBaseDatabaseConnectionIdentifier" is not empty When using AppBase versions preceding "AppBase 6.5 GA SP1 Update 2" release use this instruction instead (this field is required for all version before SP1 Update 2): Refer to the value "Database Server Host" from the Checklist. | Valid server port | ||||||||
| DatabaseSID | Refer to the value "Database SID / Service Name" from the Checklist. The placeholder can be left empty when placeholder "AppBaseDatabaseConnectionIdentifier" is not empty When using AppBase versions preceding "AppBase 6.5 GA SP1 Update 2" release use this instruction instead (this field is required for all version before SP1 Update 2): Refer to the value "Database Server Host" from the Checklist. | Valid SID | ||||||||
| DatabaseTablespace | Refer to the value "Database Tablespace" from the Checklist. | Valid tablespace | ||||||||
| DBAUser | Optional. DBA user name. Usually this is empty for most installation. In such case some DBA level features are not available. For example AppBase will not be able to create a database schema via its installation scripts or Create Environment user interface. Most of the AppBase installation have this placeholder empty and requires DBA personal intervention to facilitate the schemas for AppBase. Some development environment with dedicated test database servers use provide DBA user for AppBase to speed up development process. Cloud AppBase installations that require automatic tenant registrations requires the DBA user too. When using previous AppBase 6.5 GA release use this instruction instead (this field is required for 6.5 GA without service pack): If no user with sysdba role is available please use value "AppBase Tenant 1" from the Checklist | Valid database user | ||||||||
| DBAPassword | Optional. This is only required if you use DBAUser (if the DBAUser placeholder is not empty) When using previous AppBase 6.5 GA release use this instruction instead (this placeholder is required for 6.5 GA without service pack): | Valid database user password | ||||||||
| DBAPrivilege | No longer necessary. When using previous AppBase 6.5 GA release use this instruction instead. <DBAPrivilege></DBAPrivilege> If the user specified in DBAUser placeholder has the DBA privilege then you need to remove or comment out DBAPrivilege making the AppBase use the default value for this placeholder which is DBA Privilege=SYSDBA; | No longer necessary. When using previous AppBase 6.5 GA release use this instruction instead. | ||||||||
| DatabaseServerVersion | Must be actual database version of your Oracle or MS Sql Server database. Solutions use this value to provide version optimized experience | Valid Values: database server version in format "12.2.0.1.0". | ||||||||
| RegistryDatabaseUser | Refer to the value "AppBase Tenant Registry" from the Checklist. | Valid database user | ||||||||
| RegistryDatabasePassword | Use password for the user specified in "AppBase Tenant Registry" from the Checklist | Valid database user password | ||||||||
| RedisServerHost | Refer to the value "Redis Host" from the Checklist | Valid Redis host | ||||||||
| RedisServerHost | Refer to the value "Redis Port" from the Checklist | Valid Redis port | ||||||||
| QueueServerHost | Refer to the value "ActiveMQ Host" from the Checklist | Valid ActiveMQ host | ||||||||
| QueueServerPort | Refer to the value "ActiveMQ Port" from the Checklist | Valid ActiveMQ port | ||||||||
| ConnectionStringSIDName | Use value specified in "Database Connection Service Type" from the Checklist. The checklist for previous 6.5 GA release does not have this value. In this case please use this instruction - you need to specify one of two valid values: SID, SERVICE_NAME. This value controls how AppBase connects to the schemas via SID identifier or SERVICE_NAME identifier. | SID or SERVICE_NAME |
Capture Service Configuration
Capture service is very important AppBase component that provides ability to capture items of different types via pre-configured by solutions capture channels.
Current AppBase version supports only one instance of capture service.
In clustered setup AppBase configuration we have enabled Capture Service on the first VM by default.
If you need to change it then you need to disable Capture Service on the first VM first and then enable Capture Service on the VM of your choosing.
To disable the Capture Service you need to add explicit substitution placeholder to the first VMs second perimeter substitution - if you used the provided with AppBase templates and naming conventions then the name for the substitution file is Substitution.i02.srv01.appbase.xml
Please ensure you have this placeholder in that file to disable Capture Service on that VM:
<CaptureWinServiceEnabled>false</CaptureWinServiceEnabled>
Having this placeholder with value false is necessary because our configuration scripts configure this placeholder's default value to true to a substitution that has AppBase server Id "srv01.appbase" (placeholder name AppBaseServerId) and AppBase instance Id "i02" (placeholder name AppBaseInstanceId). This is how our installation scripts identify correct substitution for VM1.
Now after you have disabled Capture Service for VM1 you can enable it on the VM of your choosing.
To do so please modify the substitution file for the VM you want to enable Capture Service for and ensure you have this placeholder:
<CaptureWinServiceEnabled>true</CaptureWinServiceEnabled>
For example, if you want to enable Capture Service on the second VM you will need to modify file Substitution.i02.srv02.appbase.xml
Having more than one instance of Capture service running may lease to unpredicted results
Initialize Substitution Files
The last step to finalize the substitution files configuration is to run special installation scripts command to add some special placeholders to the substitution files. Examples of such automatically generated placeholders are machine keys and installation id.
You need to initialize the substitution files only once. Do not run this command again after the AppBase is installed unless you are required to do so by the support
The Scripts.2 archive which you have downloaded has AppBase installation scripts for you AppBase version. You will use the scripts to initialize the substitution files.
You need to run the initialization command in the directory where your substitution files are located. You will need also to start cmd.exe under Administrative user account
To initialize the installation substitution files run the command below:
PATH_TO_EXTRACTED_SCRIPTS2\InstallerMain.bat -Command Installation-InitializeSubstitutions -ServerFile server.appbase.xml