Purpose
Single VM installation is usually used for small to average loads when a single VM can handle all incoming requests and when the system redundancy to increase the system reliability is not necessary.
Such installations usually comprise of a single VM which has all necessary components installed on it. For security purpose it is best to use SSL for the AppBase web-site.
Most AppBase developer environments also use Single VM AppBase installation usually with AppBase web-site not protected by SSL because such VMs are usually only are exposed to internal networks and are not available to the Internet.
Checklist
Download and fill out the Single VM Installation Checklist: AppBase Single VM 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 Single VM Installation Checklist GA SP1.xlsx
For AppBase 6.5 GA release please download this checklist instead: AppBase Single VM 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\Single VM" directory to the directory of your choice.
Please make sure none of the directories you use for the substitution files or the installation scripts has spaces (" ") in its path.
These files will be your new substitution configuration files after you update few values in the _all_substitutions_common.liquid configuration file
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
| Placeholder Name | Description | Valid Values | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| SSLMode | Refer to your Checklist
| None, 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 path 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 | Optional. Refer to the value "BaseRuntimeDirectory" from the Checklist. If you do not want to override this value remove or comment out it. Base directory for solution configuration and runtime data on local drive or provided by customer NAS, etc, (e.g. \\server1\AppBaseDev). This can be file share anywhere on network with rights granted to the account configured in AppBaseServicesUsername placeholder. You can use local drive if you never plan to convert this installation to the Clustered VM configuration. You can remove this from your file or comment it out so that we would use the value you specified for "AppBaseRootDirectory" placeholder | Valid directory | ||||||||
| 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 windows 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 windows 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): If no user with sysdba role is available please use password for the user specified in "AppBase Tenant 1" from the Checklist | Valid database user password | ||||||||
| DBAPrivilege | No longer necessary. When using previous AppBase 6.5 GA release use this instruction instead. If the user used for DBAUser placeholder does not have sys dba role then you need to make AppBase remove DBAPrivilege from connection string it builds for some operations using DBAUser placeholder or else the AppBase will fail to connect to the database due to requesting DBA privilege during making a connection to the database when the user it uses to connect in fact does not have such privilege. To clear the privilege you need to uncomment DBAPrivilege placeholder and make sure it has an empty value: <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. Removed from the substitution or commented out to use the default value or empty value when the user used instead of DBA user in fact does not have DBA privilege
| ||||||||
| 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 | ||||||||
| 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 |
Advanced Configuration
The above configuration allows easy deployment of the most common AppBase configuration. The default AppBase configuration may not always fit all situations that is why AppBase can be customized to suit most of the situations.
External Redis Installation
By default the installation scripts install local Redis during installation and configure AppBase to use it. Under some configurations it is more beneficial to use external Redis installation. In this case few configuration placeholders must be added to _all_substitutions_common.liquid configuration file:
<RedisMode>External</RedisMode> <RedisServerHost>@RedisServerHost@</RedisServerHost> <RedisServerPort>@RedisServerPort@</RedisServerPort>
Either uncomment the above placeholders in _all_substitutions_common.liquid file or copy-paste it from here.
Then you need to provide values for the required placeholders.
Refer to the table below:
| Placeholder Name | Description | Valid Values |
|---|---|---|
| RedisServerHost | Refer to the value "Redis Host" from the Checklist | Valid Redis host |
| RedisServerPort | Refer to the value "Redis Port" from the Checklist | Valid Redis port |
External ActiveMQ Installation
By default the installation scripts install local ActiveMQ during installation and configure AppBase to use it. Under some configurations it is more beneficial to use external ActiveMQ installation. In this case few configuration placeholders must be added to _all_substitutions_common.liquid configuration file:
<ActiveMQMode>External</ActiveMQMode> <QueueServerHost>@QueueServerHost@</QueueServerHost> <QueueServerPort>@QueueServerPort@</QueueServerPort>
Either uncomment the above placeholders in _all_substitutions_common.liquid file or copy-paste it from here.
Then you need to provide values for the required placeholders.
Refer to the table below:
| Placeholder Name | Description | Valid Values |
|---|---|---|
| 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 |
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