The following steps describe how to upgrade WSO2 Application Server from 5.2.1 to 5.3.0. To upgrade from a version older than 5.2.1, start from the documentation that was released immediately after your current release and upgrade incrementally. For more information on release versions, see the Release Matrix.
The instructions on this page takes you through the steps for upgrading from AS 5.2.1 to AS 5.3.0. This includes upgrading the database changes as well as the configurations that should follow the upgrade.
You cannot rollback the upgrade process. However, It is possible to restore a backup of the previous database and restart the upgrade progress.
Preparing to upgrade
The following prerequisites must be completed before upgrading:
Make a backup of the user and registry databases of AS 5.2.1
Make a backup of <AS_HOME_5.2.1> folder to backup the product configurations.
Download WSO2 Application Server 5.3.0 from http://wso2.com/products/application-server/.
The downtime is limited to the time taken for switching databases when in the production environment.
Upgrading the database
There are no registry and user database schema changes between AS 5.2.1 and 5.3.0. Therefore, you do not need to do any database schema migration. However, you should create a backup of the existing database, and create a duplicate database to use with a newer product version. This is described below.
You should NOT connect a new version of WSO2 AS to an older database that has not been upgraded.
Migrating the configurations
Before you start updating the configuration files in AS 5.3.0, create a new database and restore the backup of the old database in this new database.
Updating the configuration files
The following are the updates that need to be done to the configuration files in AS 5.3.0.
Note that configuration files should not be copied directly between servers.
- Create a new database for AS 5.3.0 and restore the backup of the old database in this new database.
- To connect AS 5.3.0 to the upgraded database, configure the following files:
<AS_HOME_5.2.1>/repository/conf/datasources/masterdatasources.xmlfile as shown in the following example:
Go to the
<AS _HOME_5.2.1>/repository/conf/directory and update the datasource references in the
registry.xmlfiles to match the updated configurations in the
masterdatasources.xmlfile. The following are sample configurations if the datasource is “jdbc/WSO2CarbonDB”:
- The SaaS application configuration in webapps has been changed. So, if you are using SaaS features, you need to update your web applications. Previously, users have configured the SaaS configuration via web.xml by adding a context-param called carbon.enable.saas. In the new version, SaaS is configured via the context.xml configuration file that needs to be placed under the META-INF/ folder of the webapp. See the following documentation for more details -https://docs.wso2.com/display/AS530/Configuring+Applications+for+AS
- KeyStore configuration in AS 5.2.1 has been converged into the carbon.xml. But users wanted to configure different keystore for SSL communication, and so on. Hence, in AS 5.3.0, users should separately configure the transport keystores through catalina-server.xml. The “RegistryKeyStore” configuration in carbon.xml has been removed. This is not really there in the AS 5.2.1, but was added later in a patch. This has been reverted in AS 5.3.0.
- Check for any other configurations that were done for AS 5.1.0 (based on your solutions), and update the configuration files in AS 5.2.1 accordingly. For example, external user stores, caching, mounting, etc.
Migrating third party libraries
If there are any third party libraries used with AS 5.2.1 that you want to migrate, copy them to the following directories as applicable to AS 5.3.0.
- If you have used JDBC drivers etc, copy them into <AS_HOME>/repository/components/lib
- If you have used OSGi bundles such as SVNKit etc, copy them into <AS_HOME>/repository/components/dropins
Migrating the services and artifacts
You can migrate all artifacts relevant to super-tenant and ordinary tenants by copying the following directories from the old server to the new server.
To migrate the super-tenant’s artifacts, copy the <AS_HOME>/repository/deployment/server/ directory from AS 5.2.1 to AS 5.3.0.
If you are using multi-tenancy, copy the <AS_HOME>/repository/tenants/ directory from AS 5.2.1 to AS 5.3.0.
Since the Axis2 Quality of Services UI to apply policies such security has been removed from the management console, users need to use alternative mechanisms and apply the policies for their services. For Axis2 AAR services, the policies can be applied through the services.xml. Refer <link to page on how to apply QoS configuration if any> for more details.
To globally engage modules, users need to use axis2.xml that can be found at AS_HOME/repository/conf/axis2 directory. Refer the following sample:
The UI to globally engage a module is no longer available.
Testing the upgrade
- When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
- Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.