Tomcat Upgrade via New Installation

FlexDeploy provides a file distribution for Apache Tomcat which simplifies the installation process.  This distribution contains Tomcat, the FlexDeploy WAR, and the base configurations, leaving only a few simple steps to complete the upgrade from an existing version.  The distribution contains the following components. 

  • A Tomcat 8.5.11 server with required libraries, and base configurations
  • The FlexDeploy WAR
  • The FlexDeploy database installation scripts
  • The FlexDeploy database migration scripts (for upgrading an existing FlexDeploy installation)
  • The FlexDeploy plugins

Upgrade Note

These instructions assume you are installing on the same server as the existing installation. If you are moving servers, you will also need to copy the Server Working Directory and the Artifact Repository to the new server.

Upgrade Instructions

  1. Stop your existing FlexDeploy Tomcat server from OLD_TOMCAT_HOME. Use shutdown.sh on Linux and shutdown.bat on Windows.

  2. Backup the FlexDeploy schemas and Artifact Repository. In case you need to back out FlexDeploy, you can use these backup data.

    For back-out purposes, it is highly recommended that a database backup of the Oracle database be taken using standard tools like RMAN. Another option would be to export the FD, FD_ADMIN, and FF schemas using data pump. The schemas can be exported using the following data pump command:

    expdp system directory=DATA_PUMP_DIR dumpfile=fd_bkup.dmp schemas=FD,FF,FD_ADMIN
    If this database is exclusively used for just FlexDeploy application, you can rely on Database backup and recovery processes (RMAN)
    instead of export data procedure.

    It is recommended that a backup of the artifact repository file system be taken in case a back-out is required. The location of the artifact repository was identified in the first step of this document. Standard file backup procedures can be followed. Optionally, the following command (unix only) can be used to create a tar file backup of the entire directory.

    tar –cvzf artifact.tar.gz <artifact repository location>
  3. Extract the zip file in the desired location (referred to as "FlexDeploy Home"). This should be an empty directory, and not unzipped over an existing install.

  4. Upgrade the FlexDeploy schemas

    From the downloaded zip file, extract the /database/oracle/upgrade folder. This folder includes a number of folders containing migration.sql and patch release SQL files, which upgrade the FlexDeploy schemas.

    You will need to execute these scripts from the version of FlexDeploy you currently have, up to the latest version. And they must be executed in that order.

    If you are upgrading from 4.6.0.0 or higher then you can just look at Build Version in About window and use that information to derive SQL files to be executed. Previously, it was necessary to compare Build Time as well.

    Follow this guideline when deriving SQL Patches to be applied.

    Current version is 4.6.0.0 or higher

    • Look at Build Version in About window.

    Current version is before 4.6.0.0

    • You can find which files that you may have already executed by doing "select version, created_on, created_by from fd.fd_flexdeploy_version order by created_on desc" database query.
    • Or you can view list of patches by using Administration - FlexDeploy Patches in FlexDeploy.

    See some examples below to help you understand database upgrade process.

    Keep in mind that upgrading 4.6 to 5.0 requires running various migration scripts to jump through various intermediate versions.

    Upgrading 4.6.0.0 (or 4.6.0.x) to 5.0.0.0
    v4.6.0.0-to-4.6.1.0/migration.sql
    v4.6.1.0-to-4.6.2.0/migration.sql
    v4.6.2.0-to-4.6.3.0/migration.sql
    v4.6.3.0-to-5.0.0.0/migration.sql
    
    Upgrading 4.0 to 5.0.0.0
    v4.0-to-v4.0.1/migration.sql
    v4.0.1-to-v4.0.2/migration.sql
    v4.0.2-to-v4.0.3/migration.sql
    v4.0.3-to-v4.5.0/migration.sql
    v4.5.0-to-v4.6.0.0/migration.sql
    v4.6.0.0-to-4.6.1.0/migration.sql 
    v4.6.1.0-to-4.6.2.0/migration.sql 
    v4.6.2.0-to-4.6.3.0/migration.sql 
    v4.6.3.0-to-5.0.0.0/migration.sql

    The 4.0.2-to-4.0.3/migration.sql file includes all of the 403PatchRelease*.sql files in it. Patch Release SQL files are only necessary if you are on a 4.0.3 or 4.5.x Release.

    If you are upgrading from a 4.0.3 Patch Release, follow the date based SQL files in sequence by Date. If you have already a applied specific Patch Release patch then skip it. You can make determination of which Patch Release files to run by looking at Build Time on the About window of your FlexDeploy installation that you saved from a previous step. After completing the last 403PatchRelease, run the migration4.0.3_to_4.5.0.sql file and v4.5.0-to-v4.6.0.0/migration.sql. Contact Flexagon support for details if you are not sure. See example below.

    Upgrading 4.0.3 (build time 4/23/2017 or earlier) to 5.0.0.0
    v4.0.2-to-v4.0.3/403PatchRelease_04-24-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_05-01-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_05-5-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_05-11-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_05-22-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_06-14-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_07-19-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_07-24-2017.sql
    v4.0.3-to-v4.5.0/migration.sql
    v4.5.0-to-v4.6.0.0/migration.sql
    v4.6.0.0-to-4.6.1.0/migration.sql 
    v4.6.1.0-to-4.6.2.0/migration.sql 
    v4.6.2.0-to-4.6.3.0/migration.sql 
    v4.6.3.0-to-5.0.0.0/migration.sql
    Upgrading 4.0.3 (build time 5/11/2017) to 5.0.0.0
    v4.0.2-to-v4.0.3/403PatchRelease_05-22-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_06-14-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_07-19-2017.sql
    v4.0.2-to-v4.0.3/403PatchRelease_07-24-2017.sql
    v4.0.3-to-v4.5.0/migration.sql
    v4.5.0-to-v4.6.0.0/migration.sql
    v4.6.0.0-to-4.6.1.0/migration.sql 
    v4.6.1.0-to-4.6.2.0/migration.sql 
    v4.6.2.0-to-4.6.3.0/migration.sql 
    v4.6.3.0-to-5.0.0.0/migration.sql
    Upgrading 4.5.1 Patch Release 11-27-2017 to 5.0.0.0
    v4.0.3-to-v4.5.0/450PatchRelease_12-09-2017.sql
    v4.0.3-to-v4.5.0/450PatchRelease_01-12-2018.sql
    v4.0.3-to-v4.5.0/450PatchRelease_01-30-2018.sql
    v4.5.0-to-v4.6.0.0/migration.sql
    v4.6.0.0-to-4.6.1.0/migration.sql 
    v4.6.1.0-to-4.6.2.0/migration.sql 
    v4.6.2.0-to-4.6.3.0/migration.sql 
    v4.6.3.0-to-5.0.0.0/migration.sql

    Executing migration files

    These scripts should be executed as systemsys, or another user which has privileges to create objects in other schemas, performs grants, etc.  You can load and execute these scripts using other tools such as Toad or SQL Developer, but the instructions here are for using the sqlplus client.

    sqlplus

    Oracle sqlus is part of the Oracle Client, and may be executed on any host which has it installed. If the Oracle Client is not installed on the same host as where you are installing FlexDeploy, you can copy the scripts to another host which has it installed.

    Make sure to spool output to a file, so it can be analyzed later if necessary.

    To launch sqlplus:

    export ORACLE_HOME=<your Oracle Home directory>
    export ORACLE_SID=<the SID of your database>
    spool migration4.5.0.out #(change for each script execution so logs are preserved)
    $ORACLE_HOME/bin/sqlplus #(login as sys or system when prompted)
    SQL> <<execute scripts as shown above>>

    If running on another host other than the database server, you must update your tnsnames file and and launch sqlplus as follows:

    export ORACLE_HOME=<your Oracle Home directory>
    export ORACLE_SID=<the SID of your database>
    spool migration4.5.0.out #(change for each script execution so logs are preserved)
    $ORACLE_HOME/bin/sqlplus system@<tnsname>
    SQL> <<execute scripts as shown above>>

    For example,

  5. Copy the Tomcat configuration files from your existing install (OLD_TOMCAT_HOME) to the new FlexDeploy Home. This will make sure that new installation points to your existing Database and existing Working folder & Artifact Repository.

    Windows

    Copy <OLD TOMCAT_HOME>/conf/context.xml to <FlexDeploy Home>/apache-tomcat-flexdeploy/conf/context.xml

    Copy <OLD TOMCAT_HOME>/conf/server.xml to <FlexDeploy Home>/apache-tomcat-flexdeploy/conf/server.xml

    Copy <OLD TOMCAT_HOME>/bin/setenv.bat to <FlexDeploy Home>/apache-tomcat-flexdeploy/bin/setenv.bat

    Linux

    Copy <OLD TOMCAT_HOME>/conf/context.xml to <FlexDeploy Home>/apache-tomcat-flexdeploy/conf/context.xml

    Copy <OLD TOMCAT_HOME>/conf/server.xml to <FlexDeploy Home>/apache-tomcat-flexdeploy/conf/server.xml

    Copy <OLD TOMCAT_HOME>/bin/setenv.sh to <FlexDeploy Home>/apache-tomcat-flexdeploy/bin/setenv.sh

    chmod +x <FlexDeploy Home>/apache-tomcat-flexdeploy/bin/*.sh


  6. If using the Salesforce integration, from the FlexDeploy Tomcat distribution, copy /apache-tomcat-flexdeploy/lib/ant-salesforce.jar into <TOMCAT_HOME>/lib

  7. Configure Tomcat logging as per Tomcat Logging Setup
     
  8. If using IBM ClearCase, you will need to copy some jar files from your ClearCase server to the FlexDeploy installation
    1. Copy all of the jar files found in the com.ibm.rational.teamapi_8.0.1.vxxx folder of your ClearCase server to <FlexDeploy Home>/apache-tomcat-flexdeploy/lib.

  9. Copy plugins from the zip file that you downloaded. They are found in the plugins folder of the zip file. Plugins placed in the folder shown below automatically upload and activate on the Server.

    This is very useful during initial install as well as when upgrading FlexDeploy, as there may be many new plugins or versions available as part of new FlexDeploy release, but you can use the procedure any time.

    • Locate flexagon.fd.install.root folder for your FlexDeploy installation, which is FlexDeploy working directory. This is specified on the Java command line. For example, -Dflexagon.fd.install.root=c:/temp/flexdeploy/application.
      • For Tomcat, you can look for this information in setenv.bat or setenv.sh file depending whether using Windows or Unix.
      • For Weblogic, find it in the managed server startup settings.
         
    • Create plugins folder, if it does not exist under this folder.

       
       
    • Copy the desired plugins from the extracted zip file /plugins to this location. Tomcat and WebLogic download zip files have plugins stored in different locations.
      • Tomcat Download - application/plugins
      • WebLogic Download - plugins
  10. Start tomcat by running the following script
    1. <FlexDeploy Home>/apache-tomcat-flexdeploy/bin/startup.sh (startup.bat on Windows)

  11. Launch FlexDeploy in your browser
    1. http://<hostname>:<port>/flexdeploy
    2. default credentials are fdadmin/welcome1

  12. There is no need to activate plugins after Step 9. FlexDeploy will automatically upload and activate new versions of plugins once they are copied to plugins folder

The following macros are not currently supported in the footer:
  • style