The following steps describe how to upgrade WSO2 Application Server from version 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.
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/registry
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.
Migrating the configurations
Before you start updating the configuration files in The following topics explain the configuration changes that need to be updated for AS 5.3.0, create a new database and restore the backup of the old database in this new database.:
|Table of Contents|
Updating the configuration files
- 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.23.1>0>/repository/conf/datasources/masterdatasources.xmlfile as shown in the following example:
<datasource> user manager</description> <name>WSO2_CARBON_DB</name> <description>The datasource used for registry and <jndiConfig> <name>jdbc/WSO2CarbonDB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/<new_database></url> <username>username</username> <password>password</password> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>80</maxActive> <maxWait>60000</maxWait> <minIdle>5</minIdle> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Go to the
<AS _HOME_5.23.1>0>/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”:
<dbConfig name="wso2registry"> <dataSource>jdbc/WSO2CarbonDB</dataSource> </dbConfig>
<UserManager> <Realm> <Configuration> ... <Property name="dataSource">jdbc/WSO2CarbonDB</Property> </Configuration> ... </Realm> </UserManager>
- 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 Data services feature is no longer shipped with WSO2 Application Server. If you need to use the data services hosting feature, you have two options:
Use the WSO2 Data Services Server product which can be downloaded from http://wso2.com/products/data-services-server/. See the About this Release page to check if the latest WSO2 DSS is compatible with the current AS version.
- The configurations for SaaS web applications has changed in AS 5.3.0. In previous releases, SaaS configurations were enabled in the
web.xmlfile of the web application by adding a context-param called
carbon.enable.saas. In the new versionAS 5.3.0, SaaS is configured via the
context.xmlconfiguration file file that needs to be placed under the
META-INF/folder of the webappweb application. See the following documentation for more details -https://docs.wso2.com/display/AS530/Configuring+Applications+for+ASKeyStore 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 more details about configuring SaaS applications in AS 5.3.0 from here.
Prior to AS 5.3.0, the primary keystore configured in theusers
carbon.xmlfile was used for securing transports. In AS 5.3.0,
the keystore used for transports should be separatelyconfigure
configured in thetransport keystores through
The “RegistryKeyStore” configuration
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.
See the section on configuring keystores for more information.
- Check for any other configurations that were done for AS 5.2.1 .0 (based on your solutions), and update the configuration files in AS 5.23.1 0 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 following directories as applicable to in AS 5.3.0 as applicable.
- If you have used JDBC drivers etc, copy them into to the
- If you have used OSGi bundles such as SVNKit etc, copy them into to the
Migrating the services and artifacts
You can migrate all artifacts relevant to the super - tenant and as well as the 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-tenancymultitenancy, copy the
<AS_HOME>/repository/tenants/ directory 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
In AS 5.3.0, it is not possible to globally engage modules using the management console. Therefore, you need to update the
axis2.xmlfile in the
<AS_HOME>/repository/conf/axis2directory . Refer the following sample:as shown below. You can find more information on engaging modules for axis2 services from here.
<axisconfig name="AxisJava2.0"> <module ref=”addressing”/> .... </axisconfig>
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 as shown below. This confirms that the upgrade is successful.
Start the AS 5.3.0 server instance once the configurations are done.
Make sure that the server starts up fine without any errors.
- Test the deployed artifacts:
Log in to the management console as the super tenant.
Navigate to Main -> Applications -> List.
Verify the web application list shown there.
Invoke a web application to verify that it works.
Then, navigate to Main -> Services -> List.
Verify the services list shown there.
Invoke a service to verify that it works.
Then, navigate to Main -> Carbon Applications -> List.
- Verify the CApp list shown there.
Verify that the Users and Roles are picked up:
Navigate to Configure -> Accounts & Credentials -> Users and Roles
Verify that the list of users and roles are shown correctly.
- View the permissions of a chosen role, and make sure that the permissions are correct.
If you are using multitenancy,
Log in to the management console using the super tenant credentials.
Navigate to Configure -> View Tenants.
Verify the tenant list shown there.
- Then, log in to the system as a tenant and make sure that the log in is successful.