Summary

This article explains patch version AppBase update procedure.

By using "update" term we mean any AppBase update when only patch or build version is changed.

AppBase uses this versioning scheme: "MAJOR.MINOR.PATCH.BUILD". This article explains any update when only PATCH or BUILD numbers are changed. If MAJOR or MINOR numbers are changed we use term "upgrade".

For upgrade instructions please refer to Upgrading AppBase

Updating AppBase from 6.5 GA version to 6.5 GA SP1 version is also considered as "update" - with the release of 6.5 GA SP1 we did not change Major or Minor version - we only changed Patch version - therefore this article applies to updating from 6.5 GA to 6.5 GA SP1 too.

Before applying the update we encourage you to review the release notes for the patch or service pack you are installing to get all update specific information like breaking features, additional configuration steps etc.

New KB articles released or modified with the patch are also available with the release notes in section "Knowledge Base Articles" of the corresponding release notes page.

All release notes are available on Release Notes page.

 

1 Downloading the update

You can download the AppBase patch from the downloads page: Downloads

This instruction also applies when updating previous AppBase 6.5 GA release to AppBase 6.5 GA SP1

The patch package download come in "ISO image" format.

To download the ISO image please use "Installation ISO" link in "Release Download(s)" column:

The ISO image has both "Installation packages" and "Installation Scripts".
"Installation packages" are in the root directory of the ISO image:

"Installation Scripts" can be found inside AppBase Installation files subdirectory:

 

For applying updates to previous AppBase 6.5 GA release please use this instruction instead:

The patch package download comes in two formats: "Loose files" and "ISO image". Chose the format which works best for you.

Loose files download 

You need to download both "Installation Packages" and "Installation Scripts".

ISO image download

To download the ISO image please use "Installation ISO" link in "Release Download(s)" column:

The ISO image has both "Installation packages" and "Installation Scripts".

"Installation packages" are in the root directory of the ISO image:

"Installation Scripts" can be found inside AppBase Installation files subdirectory:

 

Understanding the downloaded files

The "Installation packages" download contains AppBase update packages in "nupkg" format - the package is used by the installation scripts to perform the update.

The installation scripts are contained in the "Installation Scripts" archive.

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.

Please ensure you have unblocked the install ISO and any files you have copied from the ISO before you unblocked it.

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:

 

2 Placing the update files

To allow AppBase find the update package files you need to place the update files to the correct directories.

Package NameDirectoryDescription
Installation Packages_NuGetpackages

This is the directory which you used to install the AppBase from in the installation guide: Installing AppBase

By default the full path is "SharedDirectoriesRoot\_NuGetpackages" where "SharedDirectoriesRoot" is the value you used for the substitution placeholder "SharedDirectoriesRoot" when creating your substitution files.

For example: "c:\AppBase\_NuGetpackages"

If you have performed an advanced configuration and overridden the _NuGetpackages directory location during your installation you will need to refer to the values you used for substitution placeholder "AppBaseNuGetPackagesDirectory"

Installation ScriptsInstall

If you have followed the recommendation in the AppBase installation guide Installing AppBase then the installation scripts are located in directory "AppBaseRootDirectory"\Install where "AppBaseRootDirectory" is the value you used for the substitution placeholder "AppBaseRootDirectory" when creating your substitution files.

For example: C:\AppBase\Install\

You need to place the downloaded "Installation Packages" directory inside correct "_NuGetpackages" directory.

The downloaded "Installation Scripts" zip archive has replacement for the files which you have currently in your "Install" directory but you can NOT replace the files yet because you will use your current installation scripts to stop the AppBase.

Instead we recommend you to create a new temporary "Install" directory with a patch version in its name:

Then you need to extract your zip archive to the new directory:

If you extracted the scripts correctly then you will find "InstallerMain.bat" and some other files in the new "Install" directory inside Scripts.2 subdirectory:

3 Stopping AppBase

Before you can start updating you need to stop AppBase. If this is a clustered setup then you need to stop AppBase on ALL servers

To stop AppBase you need the installation scripts and configuration files from your current installation, not the new files that you will be using for the upgrade.

If you followed the recommendation in the previous step then by this moment you have your original scripts and configuration files still available in the original directory. So please navigate to the directory with your original files and stop AppBase.

To stop AppBase, please to prepare command "Server-Stop".

 You can use this example command and modify it according to your configuration:

..\..\Scripts.2\InstallerMain.bat -Command Server-Stop -ServerFile server.appbase.xml -Server srv01.appbase

The above command is prepared under following assumptions:

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration.

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are updating AppBase on.

Please make sure you run the command in cmd.exe under Administrative privileges

After the command terminates, please check that all required services stopped successfully.

Please review and handle any errors during the stop command because they might lead to errors during the following update procedures. 

 If there are any services running the update will not be able to complete and might terminate unsuccessfully leaving the installation in unoperational state.

If some of the services fail to stop sometimes it can help to restart the server and try to stop the services again.

4 Replace the installation scripts

Now when the AppBase is stopped you can proceed with reconfiguring your installation before the update.

Start with removing your current installation scripts and replacing them with the new scripts.

If you do not wish any backups of your current installation scripts located in "Scripts.2" directory then you can simply remove that directory, otherwise you can create a backup by renaming that directory:

AppBase do not put any user configuration files into this directory so it is usually safe to delete this directory during the update procedure if you did not put any valuable files into this directory or do not need to access older installation scripts logs in the future

Now when there is no "Scripts.2" directory in your "Install" directory anymore you can move your new downloaded and extracted "Installation Scripts" needed for the update:

If all the steps are completed correctly then now you have updated installation scripts in your "Install" directory:

5 Reconfigure the installation scripts

You must reconfigure the installation scripts to create/update configuration files used for all other installation scripts commands.

 You need to do this after any changes to the substitution files.

 To do this, you need to prepare command "Server-Configure". 

 You can use this example command and modify it according to your configuration:

..\..\Scripts.2\InstallerMain.bat -Command Server-Configure -ServerFile server.appbase.xml -Server srv01.appbase

 

The above command is prepared under following assumptions:

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration.

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are updating AppBase on.

 

Please review the log messages to make sure the configuration has finished successfully:

In case of any error, you will need to make amends to the substitution files and try again.

6 Checkout the Nupackage installation files

The downloaded "Installation Packages" comes as compressed files in "nupkg". Before installation the files must be checked out into your local installation cache directory.

 To checkout the "nupkg" files you will use "Server-CheckoutNupackages" installation scripts command.

To prepare the command you can use the example below: 

..\..\Scripts.2\InstallerMain.bat -Command Server-CheckoutNupackages -ServerFile server.appbase.xml -Server srv01.appbase

 

The above command is prepared under following assumptions: 

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located 

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration. 

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are stopping AppBase on.

Execute the command and review the command output to make sure the command completed successfully.

7 Updating pre-requisites

The AppBase update might come with updated pre-requisites. Therefore you need to execute "Server-InstallPrerequisites" command to update/install pre-requisites.

The command checks for installed components and installs only missing/outdated components.

To prepare the command you can use the example below:

..\..\Scripts.2\InstallerMain.bat -Command Server-InstallPrerequisites -ServerFile server.appbase.xml -Server srv01.appbase

The above command is prepared under following assumptions: 

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located 

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration. 

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are updating AppBase on.

Please make sure you run the command in cmd.exe under Administrative privileges

Please review command log to make sure the command completed successfully.

If there is a message highlighted in yellow letters "A restart is required to complete the installation." then you need to restart the server. 

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 Installing the update

Now everything is ready to install the update.

The update replaces all files in the AppBase directories with the updated files.

During the update procedure all customized files inside AppBase binaries' directories will be overwritten or removed. If you customize installed AppBase binary files you may need to develop procedures to backup/restore such modification during AppBase updates.

The update is performed by command "Server-Install". 

To prepare the command you can use the example below:

..\..\Scripts.2\InstallerMain.bat -Command Server-Install -ServerFile server.appbase.xml -Server srv01.appbase

The above command is prepared under following assumptions: 

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located 

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration. 

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are updating AppBase on.

Please make sure you run the command in cmd.exe under Administrative privileges

Please review the logs messages to make sure the command has completed successfully.

10 Patch Databases

Before you can start the AppBase you need to apply database patches if there are any. AppBase has built-in command and database patcher utility that checks if any database patches need to be applied and applies all necessary patches to the target databases.

To prepare the command you can use the example below:

..\..\Scripts.2\InstallerMain.bat -Command Server-PatchDatabases -ServerFile server.appbase.xml -Server srv01.appbase

The above command is prepared under following assumptions: 

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located 

There is no need to execute this command on each server. It is necessary to execute this command only once per update - but it is safe to execute this command repeatedly - the command designed to be safe to run multiple times and will skip any patches that are already applied.

If you run into any issues with the command you can check if it is related to invalid ODAC configuration: KB2017102300 Server-PatchDatabases exits with error "Unable to find the requested .Net Framework Data Provider. It may not be installed"

After the command is completed successfully it is safe to start AppBase

11 Starting AppBase

If all above steps were completed successfully then it is safe to start AppBase on all servers now.

If you use clustered setup then there can be a defined sequence in which the AppBase servers need to be started. For example if you install some shared components (like ActiveMQ) with AppBase on one of the servers you will need to start this server first

To prepare the command to start AppBase you can use the example below:

..\..\Scripts.2\InstallerMain.bat -Command Server-Start -ServerFile server.appbase.xml -Server srv01.appbase

The above command is prepared under following assumptions: 

  1. You followed our recommendations on AppBase directory and installation scripts structure
  2. The command is executed in the same directory where your substitution files are located 

If this is not a Single VM installation or if you used different server file name and server id you might need to change "-ServerFile" and "-Server" arguments according to new configuration. 

For clustered setup you need to execute this command on each server changing "-Server" argument according to the server id you are updating AppBase on.

Please make sure you run the command in cmd.exe under Administrative privileges

Observe the command output and make sure the command is executed without error.

After the AppBase is started (in case of clustered setup when all AppBase servers are started) the update procedure is completed.

  • No labels

1 Comment

  1. Hakob Piruzyan

    Step 3, Stopping AppBase , Scripts.2 folder doesn't have server.appbase.xml file, instead the file is located in Configuration folder inside Scripts.