Language
Upgrading JasperServer 3.1 to 3.5 For Tomcat + Oracle + Linux Tutorial
Introduction
When a new JasperServer version is released, customers typically want to upgrade to the new version in order to have the latest bug fixes and the newest features.
While the upgrade process is documented in the JasperServer-Install_Guide.pdf that comes with the new release, this tutorial is more narrowly focused on the Oracle database, the Linux operating system, and the Tomcat application server.
Product Version
This tutorial works with version 3.0 and 3.1, upgrading to version 3.5.
User
Administrator
Objectives
This guide will enable you to:
Pre-Requisites
Users should have JasperServer 3.1 or JasperServer 3.0 installed under Linux using the Oracle 10.x or 11.x database and Tomcat 5.5 or 6.x.
Assumption: This tutorial uses Tomcat as the example application server.
- If you have an application server other than Tomcat you can still use this tutorial.
- Substitute your application server's specific information when doing the application server portion of the upgrade steps.
Pre-Upgrade Steps
Note on JasperServer 3.0: There were no database changes between JasperServer 3.0 and 3.1. Therefore, this upgrade procedure works for upgrades that start with either version.
Handling Customizations:
- If you made modifications or customizations to your JasperServer 3.0 or 3.1 application, these configurations are typically found in the WEB-INF/applicationContext-*.xml set of files.
- Configuration modifications such as client specific security classes or LDAP server configurations need to be hand copied from the older 3.0 or 3.1 environment and re-integrated into the new 3.5 environment.
- Running diffs between the files will help highlight your local customizations.
Backing Up Database
Follow these steps for an Oracle JasperServer database backup.
| Step | Action |
| 1 | Shutdown your JasperServer Application Server instance (or make sure that user activity is read-only)
|
| 2 | Login to a shell account on a machine where you can run the Oracle client/DBA utilities. |
| 3 | Run the datapump utility, which is available on Oracle 10 and 11. |
| 4 |
As DBA admin, create a location for the backup. a. sqlplus /nolog b. Make sure the directory pointed to below exists on the Oracle server:
c. Exit sqlplus. d. Do the datadump export:
DUMPFILE=jasperserver_31.dmp Note: For additional reference: view the Oracle Datapump Wiki site. |
Backing Up JasperServer WAR File
Follow these steps to save off the 3.1 jasperserver-pro war file(s).
| Step | Action |
| 1 | The jasperserver-pro war file is typically deployed as a directory, so move and rename this directory. Login to your application server machine. |
| 2 | Shutdown your application server |
| 3 | cd <apache-tomcat> |
| 4 |
mkdir js-3.1-war-backup mv <apache-tomcat>/webapps/jasperserver-pro to <apache-tomcat>/js-3.1-war-backup |
Exporting Your 3.1 Data
Follow these steps to export your current 3.1 repository data (also known as repository resources) from JasperServer. We use the JasperServer Export utility which is a java program.
First configure the export utility for the Oracle database. You will go to your 3.1 installation directory, called: <js-install-3.1>
| Step | Action |
| 1 | cd <js-install-3.1>/scripts/config |
| 2 |
Edit the js.jdbc.properties file. Set the properties to the following Oracle settings:
metadata.hibernate.dialect=
com.jaspersoft.ji.hibernate.dialect.OracleUnicodeDialect
metadata.jdbc.driverClassName=oracle.jdbc.OracleDriver
metadata.jdbc.url=jdbc:oracle:thin:@localhost:1521:orcl
metadata.jdbc.username=jasperserver
metadata.jdbc.password=password
|
| 3 |
Make sure the following items in bold are correct for your instance:
jdbc:oracle:thin:@localhost:1521:orcl jasperserver password
Note: You can cut and paste from the following file to avoid typing errors:
<js-install-3.1>/scripts/oracle/js-jdbc-oracle.properties
|
| 4 |
Copy the Oracle database driver to the <js-install-3.1>/scripts/lib directory.
Copy from one of the following locations:
cp <js-install-3.1>/scripts/drivers/ojdbc14.jar <js-install-3.1>/scripts/lib
Note: By default, the Oracle driver is already in place <js-install-3.1>/scripts/lib/ojdbc14.jar
|
| 5 |
Now, run the export command:
cd <js-install-3.1>/scripts
./js-export.sh --everything --output-zip js-3.1-export.zip |
Downloading the 3.5 WAR File Distribution
Follow these steps to download the 3.5 WAR File distribution.
| Step | Action |
| 1 |
Download the folder: jasperserver-pro-3.5-bin.zip. |
| 2 |
Unzip this file into a convenient location. For instance:
cd /home/username
unzip jasperserver-pro-3.5-bin.zip
|
Upgrade Steps
Configuring for Upgrade
The JasperServer download contains a set of scripts known as the “Buildomatic” scripts. These scripts use the Apache Ant tool to automatically configure all the settings you need for Tomcat and Oracle; all that is required is to configure a single property file.
| Step | Action |
| 1 | Make sure your application server is shutdown. |
| 2 |
Copy sample property file to current directory and rename it to default_master.properties:
cd <js-install>/buildomatic
cp sample_conf/oracle_master.properties default_master.properties |
| 3 |
Edit the default_master.properties file. The settings below are examples, update items in bold to match your settings:
appServerDir = /home/devuser/apache-tomcat-6.0.18
sysUsername=sys as sysdba sysPassword=password
dbUsername=jasperserver dbPassword=password
dbHost=localhost
Note: Be careful to make sure there are no additional spaces at the end of lines. |
Copying js-3.1-export.zip to Buildomatic
Locate the js-3.1-export.zip that you created in earlier steps, in your new <js-install-3.5> directory for convenience.
| Step | Action |
| 1 | cd <js-install-3.5>/buildomatic |
| 2 | cp <js-install-3.1>/scripts/js-3.1-export.zip |
Upgrading JasperServer
Run the commands to complete the upgrade.
| Step | Action |
| 1 | cd <js-install-3.5>/buildomatic |
| 2 | To drop your jasperserver database enter: ./js-ant drop-js-db |
| 3 | To recreate your jasperserver database enter: ./js-ant create-js-db |
| 4 | To add tables to your jasperserver database: ./js-ant init-js-db-pro |
| 5 | To add minimal repository data enter: ./js-ant import-minimal-for-upgrade |
| 6 |
To load your 3.1 data enter:
|
| 7 | To complete the upgrade enter: ./js-ant deploy-webapp-pro |
Upgrading Sample Data (Optional)
Upgrading Sample Data is not required.
| Step | Action |
| 1 | ./js-ant import-sample-data-upgrade-pro (Optional) |
Post-Upgrade Steps
Logging into JasperServer
Start your application server.
|
Before logging in, clear your browser cache. This will remove old, out-of-date javascript files that could cause display issues. The default URL for login is the following: http://localhost:8080/jasperserver-pro. A new system wide administrative user named superuser is now available to help with administration for creating more than one organization in JasperServer Login to JasperServer using the following logins:
Note: Change the password of the superuser account to maintain security. |
Troubleshooting
|
If you have any errors or other problems with your upgraded JasperServer, the following resources can be helpful:
|
Written By
This tutorial was written by Tony Kavanagh, Senior Software Engineer, June 2009
