Instructions for Upgrade from Worklight Server 5.0.5.x to 5.0.6.1 in a Production Environment

Product documentation


Abstract

The document supplements the content in the InfoCenter, providing more detailed instructions for applying an upgrade of Worklight Server from versoin 5.0.5.x to 5.0.6.1. It assumes the database type is DB2, MySQL or Oracle (not Apache Derby).

Content

Prepare for Migrating the Worklight Project

According to [WL Setting up existing applications], the Worklight project in Studio (with its apps and adapters) needs to be migrated to version 5.0.6.1. This is a task for the development team. It can take some time and is therefore best started ahead of time, before moving to the server upgrade.

This task is necessary because the project configuration, that gets encoded in the worklight.war file, needs to match the Worklight runtime library code (worklight-jee-library.jar). If you were to use the worklight.war you created through Worklight Studio of a previous release, the Worklight console code and project configuration would be from a previous version and would not be correct for the new worklight-jee-library.jar.

The worklight.war needs to be replaced with a customization war file generated from Worklight Studio. It contains the Worklight console code as well as the project configuration.

The steps are as follows:

  1. Backup the Worklight Studio workspace that contains the Worklight project.
    When a new version of Worklight Studio is pointed to an older Worklight Studio project, it updates (modifies) some of the meta-information files. Therefore it is a good idea to keep a backup of the previous workspace.
  2. Install Worklight Studio 5.0.6.1. See [WL Installing Studio] for details.
  3. Start Worklight Studio. See [WL Start Studio] for details.
  4. Choose as workspace the workspace that contains the Worklight Studio project.
    (Alternatively, you can also start with a fresh workspace: In Studio 5.0.5, select the Worklight project and use File > Export > General > Archive. Then, with Studio 5.0.6.1, in a freshly created empty workspace, use File > Import > General > Existing Projects into Workspace and pick the just created archive.)
  5. Create a new customization war file and deploy it to a test environment with Worklight Server 5.0.6.1. See [WL Transporting applications] for details.
  6. Recompile the apps and adapters and deploy them to the test environment. See [WL Transporting applications] for details.
  7. Test the apps and adapters.


Get Familiar with Installation Manager

Make sure that you have installed Installation Manager 1.5.2 or newer. (Installation Manager 1.6 or newer is recommended, especially on Windows.)

Its documentation is here: [ IM].

The steps are as follows:
  1. Validate the installation pre-requisites: [WL Prerequisites]
  2. Verify that the products you want to update are contained in the “Installation Manager repositories”. To this effect:
    • Start Installation Manager.
    • Under File > Preferences > Repositories, add references to the repositories that you have downloaded and unzipped on the disk, or that you can access through the internet. See [IM Repositories] for details.
    • Click the “Install” button.
    • See whether the products list contains all that you need.
    • Click Cancel. This was just a test.


Note Regarding the Repositories

There are two types of repositories, base repositories and delta repositories.
  • A base repository is an installation package that is available on Passport Advantage or on a physical media. It is self-contained.
  • A delta repository is an installation package that is available from Fix Central and labeled "update pack". It requires a base repository in order to be functional.

For installing or upgrading to a fix pack release such as 5.0.6.1, you therefore need
  • the 5.0.6.1 installation package from Fix Central,
  • a 5.0.0.0 or 5.0.5.0 or 5.0.6.0 installation package from Passport Advantage or physical media.
You need to add both to the list of repositories known to Installation Manager. Then Installation Manager will recognize the 5.0.6.1 release as an “Install” or “Update” choice.


Shut Down the Liberty Application Server

If you installed Worklight Server with an included WAS Liberty server, as in the Installation Manager wizard panel below, you need to make sure that the Liberty application server is not running any more.



The steps are similar to [ WL Start Liberty]:
  1. Ensure that the JAVA_HOME environment variable points to the installation directory of a Java 6 or 7 implementation (JRE or JDK), or that the PATH environment variable contains a 'java' program from a Java 6 or 7 implementation.
  2. On Unix:
    cd /opt/IBM/Worklight (or your installation location, if different).
    cd server/wlp/bin
    ./server stop worklightServer

    On Windows:
    cd C:\Program Files (x86)\IBM\Worklight (or your installation location, if different).
    cd server\wlp\bin
    server.bat stop worklightServer

  3. Verify that no other runaway Liberty server process is running in the same directory. On Linux and AIX, you can list such processes through the following command.
    ps auxww | grep java | grep /wlp/


Backup the Databases

Back up the contents of the databases. This is a safety measure, for the (unexpected) case that the new version does not work correctly in your environment.

If you later need to roll back the upgrade, and come back to the previous version of Worklight Server, you will need to restore the contents of the databases from the backup. The reason is that the new server version stores its data in a slightly different way than the previous version, and there is no guarantee that the old server version could operate after the new server has stored data in the databases.


Backup the Application Server

Back up the directory that contains the application server and its configuration. This is a safety measure, should anything go wrong in the (unexpected) case of mistakes in the forthcoming configuration changes.

If the application server is a Liberty server included with Worklight Server, back up the following directories.
  • WL_INSTALL_DIR/server/wlp
  • on Windows, also C:\ProgramData\IBM\Worklight\WAS85liberty-server\wlp


Remove Fix Packs from Liberty Application Server

If you installed Worklight Server with an included WAS Liberty server, and have installed fix packs, test fixes, or iFixes to this Liberty server directory, you need to remove them. You can install them again after the upgrade, but during the upgrade they should not be present.

More precisely, remove the fix packs, test fixes, and iFixes that you added separately from Worklight server, but do keep those that were included by the Worklight Server installer. You can determine the installed fix packs by looking at the contents of the wlp/lib/fixes/ directory and of the wlp/lib/versions/*aparIds.zip files (if any).

For details on how to remove fix packs, see [ WAS Remove Fix Pack].
For details on how to remove iFixes, see [ WAS Remove iFix].


Verify the Owner of Files

The upgrade step (below) attempts to remove and replace many files in the Worklight Server installation directory. This may fail if some of the files or directories are not owned by the current user and a single-user installation of Installation Manager is used. Therefore it is useful to guard against this case.

If you installed Installation Manager for a single user (as opposed to an administrator installation, see [ IM Modes]), check whether all files and directories in WL_INSTALL_DIR are owned by the current user. On Unix, you can list the files and directories that do not fulfill this condition through the commands
    cd WL_INSTALL_DIR
    find . '!' -user “$USER” -print
This command ought to produce no output.


Shut Down Conflicting Processes

On Windows only:

Shut down all processes that have a current directory inside the WL_INSTALL_DIR or the C:\ProgramData\IBM\Worklight\WAS85liberty-server directory hierarchy. This includes, in particular:
  • Console windows,
  • Windows Explorer windows.

You can do this step through the Microsoft Sysinternals Process Explorer [ MS Process Explorer].


Run Installation Manager to Perform the Upgrade

If you installed Worklight Server into an application server of type WAS ND, and the deployment target for the Worklight applications was not a single stand-alone server (that is, it was one or more servers under the control of a deployment manager), then we recommend the following steps.
  1. Uninstall Worklight Server.
  2. Install Worklight Server 5.0.6.1, choose “WebSphere Application Server” as application server, a deployment manager profile (such as “Dmgr01”) as profile, and a scope that is either a cluster, a node, or the entire cell.

If, however, you installed Worklight Server into a Liberty server, a stand-alone WAS server, or an Apache Tomcat server, we recommend to upgrade through Installation Manager's “Update” function:
  1. Start Installation Manager.
  2. Click the “Update” button.
  3. Select the package group that contains your Worklight Server installation.
  4. Click through the wizard. Most choices will be greyed (disabled), but you can change the passwords for the database or WAS access if they happen to have changed since the original installation.
  5. If you installed Worklight Server with an included WAS Liberty server, the wizard asks you whether you want to preserve the Liberty configuration. You will normally say “yes” here. This step creates a backup of the WL_INSTALL_DIR/server/wlp/usr direcory (or, on Windows, the C:\ProgramData\IBM\Worklight\WAS85liberty-server\wlp\usr directory). It takes some space, usually in the range from 50 to 100 megabytes, but maybe more, depending on the size of applications and log files the server has already accumulated. The backup location is:
    • for a privileged Installation Manager installation on Unix: /var/ibm/InstallationManager
    • for a privileged Installation Manager installation on Windows: C:\Program Files [(x86)]\IBM\Installation Manager
    • for a single user on Unix: $HOME/var/ibm/InstallationManager
    • for a single user on Windows: %HOMEDRIVE%%HOMEPATH%\Application Data\IBM\Installation Manager
  6. Once done, close Installation Manager.

Then restart the application server (if it was running) or, in the case of WAS ND, the affected servers. For details, see [ WL Completing install].


Add Fix Packs to Liberty Application Server

If you installed Worklight Server with an included WAS Liberty server, you can now add back the fix packs, test fixes, and iFixes that you removed earlier. Be sure to exclude those fixes that are contained in the new WAS Liberty version that the Worklight Server has installed in place of the old one.

You can determine the list of fixes that you still need to apply by using the Liberty command 'productInfo'.

    Unix Platforms

    cd wlp/bin
    sh productInfo compare –apars=PM12345,PM54321

    Windows Platforms

    cd wlp\bin
    productInfo compare --apars=PM12345,PM54321

See [ WAS Command: productInfo] for more details about how to use this command.

For details on how to add fix packs, see [ WAS Add Fix Pack].
For details on how to add iFixes, see [ WAS Add iFix].


Upgrade Extra Databases

The Worklight Server installer step above has upgraded the set of tables and their columns of the database to match the requirements for Worklight Server 5.0.6.1.

If you have an alternative database that you want to be able to use with Worklight Server 5.0.6.1, you need to update its set of tables and columns as well. This is a sequence of database script interpreter invocations. The upgrade scripts are contained in the just installed Worklight Server directory.

    Scripts for DB2

    For an upgrade from a version 5.0.0.x:
    • WorklightServer/databases/upgrade-worklightreports-50-505-db2.sql (for WLREPORT)

    For an upgrade from a version before 5.0.6:
    • WorklightServer/databases/upgrade-worklight-505-506-db2.sql (for WRKLGHT)
    • ApplicationCenter/databases/upgrade-appcenter-505-506-db2.sql (for APPCNTR)

    These scripts are applied similarly to step 1.f, 1.d, 1.h in [ WL DB2 manually].

    Scripts for MySQL

    For an upgrade from a version 5.0.0.x:
    • WorklightServer/databases/upgrade-worklightreports-50-505-mysql.sql (for WLREPORT)

    For an upgrade from a version before 5.0.6:
    • WorklightServer/databases/upgrade-worklight-505-506-mysql.sql (for WRKLGHT)
    • ApplicationCenter/databases/upgrade-appcenter-505-506-mysql.sql (for APPCNTR)

    These scripts are applied similarly to step 1.b in [ WL MySQL manually].

    Scripts for Oracle

    For an upgrade from a version 5.0.0.x:
    • WorklightServer/databases/upgrade-worklightreports-50-505-oracle.sql (for WLREPORT)

    For an upgrade from a version before 5.0.6:
    • WorklightServer/databases/upgrade-worklight-505-506-oracle.sql (for WRKLGHT)
    • ApplicationCenter/databases/upgrade-appcenter-505-506-oracle.sql (for APPCNTR)

    These scripts are applied similarly to step 3 in [ WL Oracle manually].


Verify Server Configuration

The Worklight Server installer step above has modified the application server's configuration to match the new Worklight Server version. It is a good idea to verify that the result meets your expectations.

    Expected Server Configuration for Liberty Profile

    The file to be verified is server.xml of the particular Liberty server. If you are using the Liberty server that is included in Worklight Server, it is the file wlp/usr/servers/worklightServer/server.xml inside the directory
    • WL_INSTALL_DIR/server on Unix,
    • C:\ProgramData\IBM\Worklight\WAS85liberty-server

    This file should still contain the modifications that you had added outside the blocks delimited by comments such as

      <!-- Begin of features added by IBM Worklight installer. -->
      ...
      <!-- End of features added by IBM Worklight installer. -->
    and

      <!-- Begin of configuration added by IBM Worklight installer. -->
      ...
      <!-- End of configuration added by IBM Worklight installer. -->

    whereas the contents inside these blocks will have been replaced with code that is suitable for the new Worklight Server version. If you had made changes inside these blocks, the upgrade will have removed them; you need adapt and reinstall them, as appropriate.

    Among these blocks, you should see code similar to this:

    In the <featureManager> element:

      <feature>ssl-1.0</feature>
      <feature>servlet-3.0</feature>
      <feature>jdbc-4.0</feature>
      <feature>security-1.0</feature>
      <feature>appSecurity-1.0</feature>

    In the <server> element, for the Worklight runtime and the Worklight Console:

      <!-- Declare the IBM Worklight Server application. -->
      <application id="worklight" name="worklight" location="worklight.war" type="war">
        <classloader delegation="parentLast">
          <commonLibrary>
            <fileset dir="${shared.resource.dir}/lib" includes="worklight-jee-library.jar"/>
          </commonLibrary>
        </classloader>
      </application>

      <!-- Declare web container custom properties for the IBM Worklight Server application. -->
      <webContainer invokeFlushAfterService="false"/>

    Similarly, for the Application Center:

      <!-- Declare the IBM Application Center Console application. -->
      <application id="appcenterconsole" name="appcenterconsole" location="appcenterconsole.war" type="war">
        <application-bnd>
          <security-role name="appcenteradmin">
            <group name="appcentergroup"/>
          </security-role>
        </application-bnd>
      </application>

      <!-- Declare the IBM Application Center Services application. -->
      <application id="applicationcenter" name="applicationcenter" location="applicationcenter.war" type="war">
        <application-bnd>
          <security-role name="appcenteradmin">
            <group name="appcentergroup"/>
          </security-role>
        </application-bnd>
      </application>

      <!-- Declare the user registry for the IBM Application Center. -->
      <basicRegistry id="applicationcenter-registry" realm="ApplicationCenter">
        <!-- The users defined here are members of group "appcentergroup",
            thus have role "appcenteradmin", and can therefore perform
            administrative tasks through the Application Center Console. -->
        <user name="appcenteradmin" password="admin"/>
        <user name="demo" password="demo"/>
        <group name="appcentergroup">
          <member name="appcenteradmin"/>
          <member name="demo"/>
        </group>
      </basicRegistry>

    Expected Server Configuration for WAS Full Profile

    To check the server configuration, use the WebSphere Application Server administration console. It is usually at localhost:9043/ibm/console. (This screen shot uses a different port.)



    When you check the custom properties of the JVM configuration of the server, you should see values for the properties android.aapt.dir (not android.aapt, as in this screen shot – that was used in version 5.0.5) and worklight.home.



    When you check the custom properties of the web container of the server, you should see that property com.ibm.ws.webcontainer.invokeFlushAfterService has the value false.



    When you check the Shared Libraries, you should find one that is named “Worklight Platform Library”.



    The detail configuration of this shared library should show a classpath that consists of the worklight-jee-library.jar:



    When you check the JDBC providers, you should see one named “Worklight JDBC provider”.



    The details of the JDBC provider can look like this, if the database type is DB2:



    When you check the data sources, you should see three of them:
    • Worklight database
    • Worklight reports database
    • Application Center database



    When you look at the configuration of each database, you should see the following JNDI names:
    • jdbc/WorklightDS
    • jdbc/WorklightReportsDS
    • jdbc/AppCenterDS

    Note: The “Test connection” button does not work in a WAS ND configuration, because the scope of the data source definition normally does not include the deployment manager server.



    For a DB2 data source, the configuration should refer to a JAAS authentication alias, called WorklightDb2DatabaseCredentials (possibly with a suffix).
    For other types of databases, the credentials are part of the custom properties of the data source.



    Here's what the JAAS authentication alias (for DB2) can look like.





    When you look at the installed applications list of the server, you should see:
    • IBM_Worklight_Console
    • IBM_Application_Center_Console
    • IBM_Application_Center_Services

    (this is slightly different from the screen shot), possibly suffixed with a numeric suffix for uniqueness (in case of WAS ND).



    The configuration of each of the web applications...



    ... should have classloader settings of “parent last” and “Class loader for each WAR file in application”.



    When you look at the shared library references of the application IBM_Worklight_Console, you should see a reference to the “Worklight Platform Library”.



    The “IBM_Worklight_Console” application has a single module, Worklight, corresponding to the customization war file.



    The module settings for every modules among the Worklight Server applications should contain a class loader order of “parent last”.



    The class loader viewer for module worklight.war in the IBM_Worklight_Console should mention the “Worklight Platform Library”.



Expected Server Configuration for Apache Tomcat

The main file to be verified is conf/server.xml of the particular Apache Tomcat server.

This file should still contain the modifications that you had added outside the block delimited by comments such as
    <!-- Begin of Context and Realm configuration added by IBM Worklight installer. -->
    ...
    <!-- End of Context and Realm configuration added by IBM Worklight installer. -->

whereas the contents inside this block will have been replaced with code that is suitable for the new Worklight Server version. If you had made changes inside this block, the upgrade will have removed them. You need adapt and reinstall them, as appropriate.

In this block, you should see code similar to the following:
    <!-- Declare the IBM Worklight Console application. -->
    <Context path="/worklight" docBase="worklight">

      <!-- Declare the IBM Worklight Console database. Used through property wl.db.jndi.name.
        If you change this declaration to refer to a different kind of data base,
        you have to update the property wl.db.type in the file worklight.properties
        inside the file worklight.war. -->
      <Resource name="jdbc/WorklightDS" type="javax.sql.DataSource"
        driverClassName="com.ibm.db2.jcc.DB2Driver" url="jdbc:db2:// db2server:50000/WRKLGHT" username=" db2username" password=" password" auth="Container" maxActive="8" maxIdle="4" maxWait="5000"/>
      <!-- Declare the IBM Worklight Console Reports database. Used through property
        wl.reports.db.jndi.name.
        If you change this declaration to refer to a different kind of data base,
        you have to update the property wl.reports.db.type in the file worklight.properties
        inside the file worklight.war. -->
      <Resource name="jdbc/WorklightReportsDS" type="javax.sql.DataSource"
        driverClassName="com.ibm.db2.jcc.DB2Driver" url="jdbc:db2:// db2server:50000/WLREPORT" username=" db2username" password=" password" auth="Container" maxActive="8" maxIdle="4" maxWait="5000"/>

    </Context>

    <!-- Declare the IBM Application Center applications. -->

    <!-- Declare the IBM Application Center Console application. -->
    <Context path="/appcenterconsole" docBase="appcenterconsole"/>

    <!-- Declare the IBM Application Center Services application. -->
    <Context path="/applicationcenter" docBase="applicationcenter">

      <!-- Declare the IBM Application Center Services database. -->
      <Resource name="jdbc/AppCenterDS" type="javax.sql.DataSource"
        driverClassName="com.ibm.db2.jcc.DB2Driver" url="jdbc:db2:// db2server:50000/APPCNTR" username=" db2username" password=" password" auth="Container" maxActive="8" maxIdle="4" maxWait="5000"/>

    </Context>

    <!-- Declare the user registry for the IBM Application Center. <Realm className="org.apache.catalina.realm.MemoryRealm"/>

Similarly, the file conf/tomcat-users.xml should contain a block delimited by comments such as
    <!-- Begin of configuration added by IBM Worklight installer. -->
    ...
    <!-- End of configuration added by IBM Worklight installer. -->

Modifications that you made outside this block should have been preserved, whereas the part inside this block will have been replaced with a definition for the role appcenteradmin, similar to this:
    <!-- Define roles and users for the IBM Application Center. -->
    <role name="appcenteradmin"/>
    <user name="appcenteradmin" password="admin" roles="appcenteradmin"/>
    <user name="demo" password="demo" roles="appcenteradmin"/>
    <user name="guest" password="guest" roles="appcenteradmin"/>

Finally, the file conf/catalina.properties should contain property definitions similar to this:
    # Added by the IBM Worklight installer.
    # The directory with binaries of the 'aapt' program, from the Android SDK's
    # platform-tools package.
    android.aapt.dir= WL_INSTALL_DIR/ApplicationCenter/tools/android-sdk

    # Added by the IBM Worklight installer.
    # Define the AppCenter services endpoint in order for the AppCenter console to be able to
    # invoke the REST service.
    # You need to enable this property only if the server is behind a reverse proxy.
    #ibm.appcenter.services.endpoint=http://<proxy>/applicationcenter


Configure the Application Center

In version 5.0.6.x, the Application Center supports a couple of new configuration options.

The Application Center security should be configured as documented in [ WL AppCenter security] and
The endpoint URI should be configured as documented in [ WL AppCenter endpoint] and

Other Configuration

Consider updating the security configuration to exploit the new features of Worklight 5.0.6: see [ WL New Security].


Start the Application Server

Now you can start the application server.

If the application server type is WAS Liberty profile included with Worklight Server, the instructions are in [ WL Start Liberty].
Otherwise, consult the documentation of the particular application server.


Finish Migrating the Worklight Project

At this point, the worklight.war file is not yet what you might expect.

This war file contains the Worklight console code as well as the project configuration.
WARNING!
  • The worklight.war file installed through the Worklight Server installer is similar to the one you would get by building an empty project with Worklight Studio. It can help testing whether the server is configured correctly (by accessing the Worklight console through a browser). But in the end, it is not this one that you want to use.
  • If you were to use the one you created through Worklight Studio of a previous release, the Worklight console code would be from a previous version, and the configuration would not be correct for the new worklight-jee-library.jar. This is also not what you want.

The worklight.war needs to be replaced with a customization war file generated from Worklight Studio.

Generating this war file can be done in two ways.
  • By the development team
  • By automated scripts that access the developers' source code of the Worklight project, through use of the Worklight ant tasks [WL Ant Tasks]

The steps are described in [ WL Transporting applications]. This time, the parameterization to use is the one for the development environment, rather than the one for the test environment.

Step 5 in this sequence is to deploy the customization war file to the production environment, as described in [ WL Deploy war] and

Recovering from a Failed Upgrade

If you want to get back to the old Worklight Server version, for whatever reason, you will need to follow these steps.
  • Uninstall Worklight Server, using Installation Manager.
  • Install the old version of Worklight Server using Installation Manager, specifying the same installation parameters as earlier.
The "Roll Back" button of Installation Manager is not supported for Worklight Server.

Also you will need to do the following.
  • Restore the databases (see section "Backup the databases" above).
  • Restore the application server (see section "Backup the application server" above).


References

Cross reference information
Segment Product Component Platform Version Edition
Mobile- Speech and Enterprise Access IBM Mobile Foundation Installation AIX, HP-UX, Linux, Solaris, Windows 5.0.6.1, 5.0.6, 5.0.5.1, 5.0.5 Consumer, Enterprise

Rate this page:

(0 users)Average rating

Document information


More support for:

IBM Worklight
Installation

Software version:

5.0.5, 5.0.5.1, 5.0.6, 5.0.6.1

Operating system(s):

AIX, HP-UX, Linux Red Hat - xSeries, Linux SUSE - xSeries, Solaris, Windows

Software edition:

Consumer, Enterprise

Reference #:

7038300

Modified date:

2013-07-29

Translate my page

Machine Translation

Content navigation