1 Summary
The page contains information about installing new AppBase. For the information on how to update existing AppBase installation please see Updating AppBase
2 Download Software
AppBase installation & script files are available on the downloads page: Downloads.
You need to download AppBase GA SP1 package and we also recommend you to apply the latest patch to ensure you have all latest security improvements and bug fixes.
ISO image download
To download the ISO image please use "6.5 GA SP1 Installation ISO" link in "Release Download(s)" column:
The ISO image has both AppBase Installation files and AppBase installation scripts.
AppBase Installation files are in the root directory of the ISO image:
AppBase Installation scripts can be found inside AppBase Installation files subdirectory:
For previous AppBase 6.5 GA release please use this instruction instead:
The GA package download comes in two formats: "Loose files" and "ISO image". Chose the format which works best for you.
Loose files download
To download AppBase Installation files please use "6.5 GA Installation Packages" link in "Release Download(s)" column.
To download AppBase installation scripts please use "6.5 GA Installation Scripts" link in "Release Download(s)" column.
ISO image download
To download the ISO image please use "6.5 GA Installation ISO" link in "Release Download(s)" column:
The ISO image has both AppBase Installation files and AppBase installation scripts.
AppBase Installation files are in the root directory of the ISO image:
AppBase Installation scripts can be found inside AppBase Installation files subdirectory:
Unblocking the downloaded files
You need to unblock the downloaded files. Make sure you have unblocked the installation ISO and any files you have copied from it before unblocking the ISO
Unblock the downloaded packages using PowerShell 3.0 snippet:
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:
3 Prepare AppBase Installation folders
Create AppBase folder structure on your server (we recommend to use non-system disk)
Please make sure none of the directories you use for the substitution files or the installation scripts has spaces (" ") in its path.
You can use the table below as an example
| Folder | Description |
|---|---|
| C:\AppBase | Root AppBase Installation folder |
| C:\AppBase\Install | |
| C:\AppBase\Install\Configuration | |
| C:\AppBase\Install\Configuration\training.com | Contains AppBase Configuration Files for specific AppBase Installation (training.com in our example) |
| C:\AppBase\Install\Scripts.2 | Contains AppBase Installation Scripts |
| C:\AppBase\_NuGetpackages | Contains AppBase Installation Files (packages). If the runtime shared directory root is different from Root AppBase Installation folder which is common for clustered configurations then put the packages to the runtime shared directory. For example, if you have configured placeholder SharedDirectoriesRoot as <SharedDirectoriesRoot>E:\AppBaseData</SharedDirectoriesRoot> then you need to put the packages to E:\AppBaseData\_NuGetpackages preserving the version name subdirectory.
If done right then the directory E:\AppBaseData\_NuGetpackages\6.5.35.15 will have inside it subdirectories with the packages:
You may have a different AppBase version (if you install patches you may have a greater AppBase version) so replace 6.5.35.15 in the path with you AppBase version. When copying the files from AppBase ISO or downloading the loos files you should already have correct root directory for _NuGetpackages:
For previous AppBase 6.5 GA release please use this instruction instead: If done right then the directory E:\AppBaseData\_NuGetpackages\6.5.32.10 will have inside it subdirectories with the packages:
You may have a different AppBase version so replace 6.5.32.10 in the path with you AppBase version. When copying the files from AppBase ISO or downloading the loos files you should already have correct root directory for _NuGetpackages:
|
| C:\AppBase\_InstLocalCache | Contains AppBase Installation Files (unpacked). If the runtime shared directory root is different from Root AppBase Installation folder which is common for clustered configurations then the packages will be unpacked to the runtime shared directory |
AppBase Installation Files
AppBase Installation files downloaded on previous step must be placed to the directory "_NuGetpackages".
NOTE: this location can be overridden in your substitution files by overriding placeholder AppBaseNuGetPackagesDirectory, please refer to 6.5 Configuring AppBase for more details.
AppBase Installation Scripts
AppBase Installation scripts must be placed to the directory "Scripts.2". In this example, it would look like this:
AppBase Configuration Files
AppBase Configuration files (substitution fies and server.appbase.xml) created on AppBase Installation Planning step must be placed to C:\AppBase\Install\Configuration\<Installation Name> folder.
Usually we create "Configuration\@AppBase_installation_name@" directory inside "Install" directory. We substitute @AppBase_installation_name@ with name to identify your installation for your own records and unique enough for you to distinguish it from other installation.
In our example, we use "training.com" as installation name.
4 Open Command Prompt (Run As Administrator)
Start Command Prompt (cmd.exe) as administrator by right clicking it and selecting “Run as administrator”:
For easier log monitoring you can change command prompt properties after it was started:
Change current directory to the directory where you put the substitution files, for example:
5 Configure AppBase Installation
All commands examples are prepared under assumption that they are run from the directory where the substitution files are located. Please run all installation commands from that directory.
Documentation about installation commands can be found in a Readme.txt file, that is located in the "Scripts.2" directory.
cd C:\AppBase\Install\Configuration\training.com |
Run following command
..\..\Scripts.2\InstallerMain.bat -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-Configure
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase).
In our example, command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-Configure
Please review the log messages to make sure the configuration has finished successfully:
In case of any error, you will need to make changes to the substitution files and re-run the command above again.
After successful execution of "Server-Configure" command new configuration files will be created in the directory where you ran the command in (reminder - this must be directory where you have your substitution files)
For example:
6 Extract AppBase Installation Files
AppBase Installation Files are packaged using NuGet utility. In order to proceed with installation, we need to exact installation files first.
Run following command:
..\..\Scripts.2\InstallerMain.bat -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-CheckoutNupackages
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase).
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-CheckoutNupackages
During execution this command, installation files located in _NuGetPackages (C:\AppBase\_NuGetPackages) directory would be unpacked and placed to _InstLocalCache directory (C:\AppBase\_InstLocalCache).
NOTE. Both directories (_InstLocalCache and _NuGetPackages) can be changed by overriding AppBaseLocalCacheDirectory and AppBaseNuGetPackagesDirectory placeholders (please refer to this page for more details: 6.5 Configuring AppBase for more information)
Please review command log to make sure the command completed successfully.
Customer Purchased Licenses (Conditional Step)
If the AppBase installation uses any components that require customer purchased licenses then those licenses need to be purchased by the customer and prepared in the AppBase Licenses directory before Server-Install step.
For most AppBase installations path to the AppBase Licenses directory can be easily calculated using this instruction. Please find the value you used for substitution placeholder AppBaseRootDirectory or you can refer to what you have specified in your installation checklist for field "AppBase Root Directory" - if you followed the installation guide than you have used "AppBase Root Directory" value for substitution placeholder AppBaseRootDirectory therefore they have the same value.
If for some reason you have used a value for substitution placeholder AppBaseRootDirectory that is different from your checklist then of course the substitution placeholder value takes precedence over the checklist. The substitution placeholder values are used by AppBase for its configuration while the installation checklist is merely a collection of information you used to configure the substitution files.
After you have determined the value specified in AppBaseRootDirectory placeholder please use it to calculate it by adding "\Licenses" to the end of that value. For example, if value for your substitution placeholder AppBaseRootDirectory is "D:\AppBase" then your AppBase licenses directory is "D:\AppBase\Licenses"
This notice is designed for advanced users, troubleshooting or AppBase versions before 6.5 GA SP1 Update 1 (in AppBase versions starting from 6.5 GA SP1 Update 1 we have simplified how default LicensesAndCertificatesDirectoryPath directory is calculated which allowed us to prepare the simplified instruction above - older versions please use this instruction).
Most newer AppBase installations do not override substitution placeholder LicensesAndCertificatesDirectoryPath.
In case if for some reason AppBase did not install the licenses during Server-Install step from the directory you have calculated using the above simplified instruction, or if you know that you have overridden this placeholder in any of your substitution files, then you need to use this advanced instruction instead.
To ensure that you used the same Licenses directory path that AppBase uses during installation you need to check all your substitution files and find all overridden placeholders LicensesAndCertificatesDirectoryPath. If there are more than one placeholder and they point to different directories you need to put the purchased licenses to all those directories.
Now after you have found AppBase licenses directory(-ies) you need to put any purchased licenses files in to that directory(-ies).
That's it! You are ready to continue further. When you execute Server-Install step the installation scripts will distribute the licenses to all necessary AppBase directories.
7 Install AppBase Prerequisites
During this step we need to install pre-requisites (.NET Framework, Oracle drivers, etc), configure Windows Web Application Server.
Run following command:
..\..\Scripts.2\InstallerMain.bat <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-InstallPrerequisites
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase).
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-InstallPrerequisites
Please review command log to make sure the command completed successfully. If you see a message highlighted in yellow letters "A restart is required to complete the installation." - you need restarted windows.
8 Unlock Windows Authentication Section (Conditional Step)
This step is necessary if you plan to have Active Directory users log in to AppBase. If you ever plan to have any of your users to be able to log in via AppBase login feature then you need to perform this step.
AppBase login feature may work with Active Directory in two ways: regular login via AppBase login page and single sign-on.
Both ways require Active Directory synchronization with AppBase.
Single sing-on feature works automatically without opening user AppBase login page - when enabled it gets user name information from Windows and does not require user to ever authenticate in AppBase if they are already authenticated with valid Active Directory user in Windows and their user was synchronized with AppBase.
To unlock Windows Authentication Section please execute this command in cmd.exe opened with Administrative privileges:
%windir%\system32\inetsrv\appcmd unlock config /section:windowsAuthentication
9 Verify AppBase Installation (Recommended Optional Step)
Before starting AppBase installation, we recommend to check basic parameters like:
- connection to the registry schema, grants and privileges
Run following command:
..\..\Scripts.2\InstallerMain.bat -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-ChecklistVerificate
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase).
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-ChecklistVerificate
If all checks were successful you will see next screen:
If any of the checks was not successful (for example VM with AppBase does not have connection to DataBase) you will see next screen, where all error will be displayed in red:
10 Install AppBase
On this step, actual AppBase Software would be installed. Web Applications and Web Services would be deployed to Internet Information Services (IIS), Windows Services would be registered accordingly.
Run following command:
..\..\Scripts.2\InstallerMain.bat -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-Install
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase)
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-Install
NOTE: Server-Install command must be running on each server, making sure that correct server id is passed.
NOTE: Please be aware that the command may remove any files from the target installation directories.
Please review the logs messages to make sure the command has completed successfully
After completion of the command additional batch files are created to be used as a shortcuts for most installation commands. The shortcuts have command arguments configured specifically for the server where Server-Install command was executed.
Each server will have different content for the shortcuts.
SSL Configuration
You need manually add https binding and install SSL certificate when installing AppBase with SSL terminated on IIS (substitution placeholder SSLMode equal "IIS"). AppBase does not support automatic SSL certificate installation for most of SSL certificates.
When using AppBase configuration with SSL terminated on IIS you need install SSL certificate manually and update https binding.
You need to perform the configuration if your _all_substitutions_common.liquid configuration file has SSLMode placeholder with this value:
<SSLMode>IIS</SSLMode>
9.1 Use instructions that comes with your SSL certificate to install for IIS
9.2 Open Internet Information Services (IIS) Manager
To open Internet Information Services (IIS) Manager you need to press Win+R buttons on your keyboard and type "InetMgr" and press Enter on your keyboard:
9.3 Find AppBase.i01 web site then right click it and choose "Edit Bindings"
9.4 Click "Add" button to add new https biding
9.5 Remove all other bindings and keep only the https bindings you just added:
11 Initialize AppBase Tenant Registry Schema
On this step we need to initialize AppBase Tenant Registry schema. The command uses following placeholders from configuration xml file (they originally come from substitution xml file).
| Substitution placeholder name | Description |
|---|---|
| DatabaseServer | Address of the database server. |
| DatabasePort | Port number of the database server (Only for Oracle). |
| DatabaseSID | SID or Service Name of the database server (Only for Oracle). |
| DatabaseTablespace | Database tablespace (Only for Oracle). |
| RegistryDatabaseUser | Login for registry schema. |
| RegistryDatabasePassword | Password for registry schema. |
| RegistryDatabaseSchema | Name for registry schema (Only for MS SQL ). |
| DBAUser | Optional. User to use as DBA user when executing elevated permissions level command. When no DBA user is provided AppBase will not be able to use elevated permissions commands - like create schema or use automatic environment creation (because it creates DB schema automatically and requires DBA user). For previous AppBase 6.5 GA release please use this instruction instead. User to use as DBA user when executing elevated permissions level command. When no DBA User is available, tenant database user is usually used. However in such case automatic tenant & environment creation or some other commands that require DBA level permissions (like creating database) will fail. |
| DBAPassword | DBA user password. |
As a reminder, DBAUser placeholder is optional. If AppBase was not provided with a DBA user then all schemas must be provisioned by DBA. Information how to provision the schemas is explained in Pre Installation Steps
For previous AppBase 6.5 GA release please use this additional information.
NOTE: If DBA user is granted elevated privileges, then the command can take care about creating AppBase Tenant Registry schema if it does not exist yet. If the schema already exist, the script will show warning and conitnue the execution.
NOTE: For database Oracle
When DBA user is not available or when particular database name is required, please be aware that the database must have this roles assigned:
- resource;
- connect.
- create view
Another requirement - the target database (the database you specified for RegistryDatabaseUser placeholder) must be generally empty. It can contain Applibrary objects or any objects that do not overlap with AppBase registry objects
If the user specified in DBAUser placeholder is not a DBA or if the registry schema already exists, there would be warnings like this during execution of command "Create-RegistrySchema":
"create user registry identified by registry default tablespace USERS ... ERROR:ORA-01031: insufficient privileges ..."
"grant resource,connect to registry... ERROR:ORA-01031: insufficient privileges ...".
The script will ignore those errors and proceed to creating AppBase registry database structure.
Run following command:
..\..\Scripts.2\InstallerMain.bat -ConfigFile <CONFIG_FILE.xml> -Command Create-RegistrySchema
where
- CONFIG_FILE.xml - name of the file that is created command "Server-Configure"
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ConfigFile Configuration.i01.srv01.appbase.xml -Command Create-RegistrySchema
12 Post Installation Smoke Test (Optional)
There are few things that can validated to ensure that installation was completed successfully.
IIS Configuration
Please open IIS Manager->Application Pools management tool.
The application pools created for the AppBase must be configured for "v4.xx" version of ".Net framework". This action is performed by the installation script, however it would be beneficial to ensure it is configured properly.
While is is not a requirement, however we recommend to delete default IIS site named "Default Web Site".
The installation script set bindings for AppBase sites. Please check them to make sure they were configured properly.
Bindings specify in the following placeholder in substitution files (for more details please refer to 6.5 Configuring AppBase):
| Substitution placeholder name | Example | Description |
|---|---|---|
| WebSiteWebServicesBindingProtocols | http | Protocol for Web site (more https://msdn.microsoft.com/en-us/library/bb359364(v=vs.90).aspx; https://msdn.microsoft.com/en-us/library/bb357409(v=vs.90).aspx). |
| WebSiteWebServicesBindingInformation | 192.168.100.111:@Port@: | For example, a Web site that is listening for HTTP connections on port 80 of IP address 192.168.1.100 with a domain name of "microsoft.com" would use "192.168.1.100:80:microsoft.com" for the bindingInformation parameter. Then protocol parameter should be added to specify protocol. If more bindings is to be added check AdditionalBindingInformation placeholder. |
| CMSWebDavBindingProtocols | http | Similarly placeholder WebSiteWebServicesBindingProtocols. |
| CMSWebDavBindingInformation | 192.168.100.111:@Port@: | Similarly placeholder WebSiteWebServicesBindingInformation. |
Local hostnames
If some of you hostnames used for the AppBase urls for any reason are not resolved by DNS (sometimes we use dummy hostnames not registered anywhere except hosts file, but even if you use actual hostnames, some network configuration my not resolve hostname event for your current server). So it would be prudent to check if all hostnames used for the AppBase can be resolved, and add them to hosts files if they are not.
Hosts file usually can be found at this location c:\Windows\System32\drivers\etc\hosts
If you have more then one server in your AppBase installation, you may need to register additional hostnames in your hosts file if they are not resolved by DNS.
In such case, content of the hosts file can vary between the servers. Some servers may register hostnames to its local ip (127.0.0.1) when the hostname must be resolved to the same server where you configure hosts file on, while the same hostname must be configured for external IP to be accessible from other servers - please be aware of this:
In the example shown on the picture, "training1.appbase.local" is local AppBase website (local contour) for the current server,
training2.appbase.local - is local AppBase website on server with an IP address 192.168.1.4.
13 Start AppBase
If all above actions completed successfully, AppBase can be started.
Run following command:
..\..\Scripts.2\InstallerMain.bat -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME> -Command Server-Start
where
- SERVERS_CONFIG_FILE.xml - with the name of the server configuration file (in this example it is server.appbase.xml)
- SERVER_NAME - with the server name of the selected servers from file server.appbase.xml (in this example - srv01.appbase)
In our example, the command will look like:
..\..\Scripts.2\InstallerMain.bat -ServerFile server.appbase.xml -Server srv01.appbase -Command Server-Start
NOTE: Windows Services use this naming convention: <Service name>_<port>
NOTE: You can use a shortcut "server-start.bat" that was created after server-install command
To validate the installation and successful start of the AppBase please do the following:
- open a browser on a computer that have access to hostname used for external AppBase contour or load balancer if load balanced configuration was used;
- enter the URL in the browser specified in file Substitution.i01.srv01.appbase.xml AppBaseUrl placeholder
(in this example http://training.appbase.com/Ecx.Web).
If all goes well, you should open the login page, for example:
At this stage AppBase software is started and we can continue to the next step - Creating Tenant in AppBase