Professional Documents
Culture Documents
Installation Guide
Version 3.1
http://www.jaspersoft.com/
© 2008 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, JasperAnalysis,
JasperServer, JasperETL, JasperReports, iReport, and Jasper4 products are trademarks and/or registered trademarks of
Jaspersoft Corporation in the United States and in jurisdictions throughout the world. All other company and product names
are or may be trade names or trademarks of their respective owners.
JasperServer Installation Guide
Table of Contents
1 Introduction .................................................................................................................................6
1.1 About JasperServer .............................................................................................................................. 6
1.2 Conventions .......................................................................................................................................... 6
1.3 JasperServer Distributions.................................................................................................................... 6
1.4 Installer Distribution Support................................................................................................................. 7
1.4.1 Operating Systems Supported................................................................................................. 7
1.4.2 Components Included in the Installer ...................................................................................... 7
1.4.3 Applications Supported by the Installer ................................................................................... 7
1.4.4 Application Versions Supported............................................................................................... 7
1.4.5 Java Version Supported........................................................................................................... 7
1.5 War File Binary Distribution Support..................................................................................................... 8
1.6 Release Notes and Application Support ............................................................................................... 8
1.7 Prerequisites for Installation.................................................................................................................. 8
1.7.1 System Requirements.............................................................................................................. 8
1.8 Support for Internationalization ............................................................................................................. 9
2 1208.JSO31.10
JasperServer Installation Guide
3.4 Starting the Included iReport .............................................................................................................. 16
3.5 JasperServer Log Files ....................................................................................................................... 16
4 Uninstalling JasperServer........................................................................................................17
5 Install Using the War File Distribution for Tomcat or JBoss ................................................18
5.1 Introduction ......................................................................................................................................... 18
5.1.1 Applications Supported by the War File Distribution ............................................................. 18
5.1.2 Application Versions Supported............................................................................................. 18
5.2 Obtain the War File Distribution .......................................................................................................... 18
5.3 Unpack the War File Distribution Zip .................................................................................................. 18
5.4 Setup the JasperServer Database...................................................................................................... 18
5.4.1 MySQL Database Setup Steps.............................................................................................. 19
5.5 Deploy JasperServer War to the Application Server .......................................................................... 19
5.6 Prepare for Database Configuration ................................................................................................... 19
5.6.1 Default Database Configuration Values ................................................................................ 19
5.6.2 Expand the Archived War File ............................................................................................... 20
5.7 Configure Hibernate Properties File ................................................................................................... 20
5.8 Deploy JDBC Database Driver ........................................................................................................... 21
5.9 Database Connection Steps for Tomcat............................................................................................. 21
5.9.1 MySQL context.xml for Tomcat.............................................................................................. 21
5.10 Database Connection Steps for JBoss ............................................................................................... 21
5.10.1 MySQL Datasource for JBoss ............................................................................................... 22
5.11 Extra Configuration Step for JBoss..................................................................................................... 22
5.12 Set Java JVM Options ........................................................................................................................ 22
5.12.1 JVM Options for JBoss .......................................................................................................... 23
5.13 Start JasperServer .............................................................................................................................. 23
5.14 Login to JasperServer......................................................................................................................... 23
5.14.1 JasperServer Heartbeat......................................................................................................... 24
5.15 Setup and Load Sample Data............................................................................................................. 24
5.15.1 MySQL Sample Database Create and Populate ................................................................... 24
5.15.2 Check Context.xml or JBoss Datasource for Sample Data Config ....................................... 24
5.16 Import the JasperServer Sample Metadata ........................................................................................ 25
5.16.1 Prepare for Running the Import Utility ................................................................................... 25
5.16.2 Run the Import Utility ............................................................................................................. 25
5.17 Report Scheduling Configuration........................................................................................................ 25
5.17.1 js.quartz.properties ................................................................................................................ 25
5.17.2 js.mail.properties.................................................................................................................... 26
5.17.3 js.schedular.properties........................................................................................................... 26
5.18 Restart JasperServer .......................................................................................................................... 26
5.19 Update XMLA Connection Definitions (Optional) ............................................................................... 26
5.20 Troubleshooting your JasperServer Configuration ............................................................................. 27
3
JasperServer Installation Guide
6 Upgrade from JasperServer 3.0 to JasperServer 3.1 ............................................................28
6.1 Backup JasperServer War File and JasperServer Database............................................................. 28
6.1.1 Stop Your Application Server................................................................................................. 28
6.1.2 Backup the JasperServer War Archive.................................................................................. 28
6.1.3 Backup the JasperServer Database ...................................................................................... 28
6.2 Unpack JasperServer 3.1 War File Distribution.................................................................................. 28
6.3 Upgrade the JasperServer War .......................................................................................................... 29
6.3.1 Deploy the JasperServer WAR file ........................................................................................ 29
6.3.2 Expand the Archived War File ............................................................................................... 29
6.3.3 Check for Local Configurations.............................................................................................. 29
6.4 Upgrade the JasperServer Database ................................................................................................. 29
6.5 Start JasperServer 3.1 ........................................................................................................................ 29
6.6 Login to JasperServer 3.1................................................................................................................... 30
6.7 Sample Data Upgrade (Optional) ....................................................................................................... 30
6.7.1 Upgrade Sample Databases (if necessary)........................................................................... 30
6.7.2 Configure and Run Import of Sample Data ........................................................................... 30
6.8 Additional Notes on JasperServer Upgrade ....................................................................................... 31
6.8.1 Using mysqldump for Database Backup ............................................................................... 31
6.8.2 Additional Configuration Files ................................................................................................ 31
6.8.3 Clear the Tomcat Work Directory .......................................................................................... 31
6.8.4 Clear the Repository Cache Table......................................................................................... 31
6.8.5 Update XMLA Connections (Optional)................................................................................... 32
6.8.6 Upgrade Using Export and Import Operations ...................................................................... 32
4 1208.JSO31.10
JasperServer Installation Guide
Appendix A: Configuring the Import-Export Utility .....................................................................38
5
JasperServer Installation Guide
1 Introduction
1.2 Conventions
For clarity, this document uses the following conventions when referring to file locations, user names, passwords, and other
values that are specific to your environment:
Convention Meaning
Paths and File <js-install> The root directory where JasperServer will be installed.
Locations
<apache-tomcat> The directory where Tomcat is installed. If you plan to use the
instance of Tomcat that is included in the installer, Tomcat is installed
under the <js-install> directory.
<jboss> The directory where JBoss is installed.
<mysql> The directory where MySQL is installed. If you plan to use the
instance of MySQL that is included in the installer, MySQL is
installed under the <js-install> directory.
<java> The directory where java is installed
Additional <unpacked-war-dir> The directory where user unpacks the WAR file distribution ZIP.
Locations
jasperadmin/ The user name and password of the default JasperServer login
jasperadmin administrative user.
jasperdb/password The user name and password for the default database user.
6
JasperServer Installation Guide
Note: For a complete list of applications supported by the WAR file distribution, refer to the release notes that are included
in the root directory of the distribution file set.
8
JasperServer Installation Guide
RAM 512 MB 1 GB +
Linux
Disk ~600MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class) 1 GHz (single Pentium) 1.5 GHz + (multi-core
Pentium)
Solaris
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class) UltraSparc II
AIX
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class)
HP-UX
Disk ~600 MB 10 GB free 40 GB +
RAM 512 MB 1 GB +
CPU (class)
9
JasperServer Installation Guide
2 Installing JasperServer
When you run the installation executable, you are prompted to specify information about the third party applications that
JasperServer relies on. These third party applications are Apache Tomcat and the MySQL database.
This section sets forth all the steps you might encounter when installing JasperServer.
Note: When you run the installer against an existing database instance, the database must be running at install time.
2.1.1 Welcome
The first step introduces the installer and allows you to continue or exit. Click Next.
10
JasperServer Installation Guide
The first option is to choose a "bundled Tomcat". If you choose this option, the installer puts an instance of Tomcat 5 onto
your system. Click Next. You are prompted for the server port and shutdown port that Tomcat will use. Most users accept
the default values that are displayed. Accept the default values or enter alternate values and then click Next.
The second option is to choose an "existing Tomcat". If you already have an instance of Tomcat on your system, then you
can choose this option. Choose the "existing Tomcat" option and click Next. You are prompted for its location. Enter the
correct location for Tomcat or click Browse to locate and select another location. Click Next. You are prompted for
Tomcat's server port and shutdown port. Accept the default values or enter alternate values and then click Next.
11
JasperServer Installation Guide
• Sugar CRM data that simulates three years of operations for a fictitious company that relies on the SugarCRM
open source application
• Foodmart data that simulates three years of operations for a fictitious company.
• JasperServer repository resources such as Reports, Analysis Views, Ad Hoc Topics, Domains, Data Sources, and
Input Controls.
• Jaspersoft strongly recommends that you install this data, unless you are not interested in testing or evaluating with
the default sample data. Click Yes to install the sample data and click Next.
12
JasperServer Installation Guide
If you take the Checkbox default, the heartbeat is enabled. If you deselect the Checkbox, the heartbeat component is
disabled. You can later enable or disable the heartbeat by modifying the jasperserver/WEB-INF/applicationContext-
logging.xml file.
For additional information on enabling and disabling the heartbeat component refer to the JasperServerAdministrator
Guide.
13
JasperServer Installation Guide
C:\Documents and Settings\<username>\Local Settings\Temp\bitrock_installer_<number>.log
Linux:
/tmp/bitrock_installer_<number>.log
14
JasperServer Installation Guide
15
JasperServer Installation Guide
If the login page appears, JasperServer has started properly. You may now login with the following username and
password:
Username: jasperadmin (default administrative user)
Password: jasperadmin
If you installed the sample data then additional sample end-users are created. These end users are non-administrative users
who have less system privileges than an administrative user. End-users:
Username: joeuser (sample standard end-user)
Password: joeuser
Username: demo (special SuperMart Dashboard demonstration end-user)
Password: demo
Security Note: Once you have completed the evaluation or testing of your JasperServer instance, you should change your
administrative password and change the passwords for the sample end-users (or remove the sample end-users).
16
JasperServer Installation Guide
4 Uninstalling JasperServer
In Windows, click Start > All Programs > JasperServer> Uninstall to uninstall JasperServer.
In addition, in Windows, you can open the Control Panel and double-click the Add or Remove Software option. Locate
JasperServer in the list of installed software and click Change/Remove. You are prompted to remove the software. Indicate
Yes and follow the on-screen instructions.
Under Linux, the <js-install> directory includes an executable that removes JasperServer from the host. From the command
line as the root user (or any user with sufficient privileges), enter:
cd <js-install>
./uninstall
You are prompted whether to remove JasperServer. Press Y and then press Enter to remove JasperServer from this
computer.
17
JasperServer Installation Guide
5.1 Introduction
In addition to the installer binaries, the JasperServer application is distributed as a stand-alone WAR file distribution. This
distribution is packaged as a ZIP file.
Customers who do not wish to use the installer or who have target configurations other than those supported by the installer
should use the WAR file distribution.
19
JasperServer Installation Guide
Database Host localhost
Database Name jasperserver
Database User jasperdb
Database Password password
Database Port 3306
Database SID N/A
Hibernate Dialect MySQLDialect
Quartz Driver Delegate StdJDBCDelegate
Your instance of JasperServer should be modified to support the values in your own database environment.
mkdir jasperserver
cd jasperserver
jar xvf ../jasperserver.war (x - extract, v - verbose, f - is filename)
cd ..
rm –r jasperserver.war or del jasperserver.war (remove the original WAR file)
JBoss
mv jasperserver jasperserver.war (add .war to end of dir name)
copy jasperserver jasperserver.war (same in Windows)
20
JasperServer Installation Guide
metadata.hibernate.dialect=org.hibernate.dialect.MySQLDialect
21
JasperServer Installation Guide
5.10.1 MySQL Datasource for JBoss
The <unpacked-war-dir>/scripts/jboss directory contains a sample js-mysql-ds.xml file.
This data source definition file should be copied to the following location:
….<jboss>/server/default/deploy
You should edit this file and make sure that it has the proper settings for your database configuration.
Check that the following lines have the appropriate values:
<connection-url>jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&characterEncoding=UTF-8</connection-url>
<connection-url>jdbc:mysql://localhost:3306/sugarcrm?useUnicode=true&characterEncoding=UTF-8</connection-url>
<connection-url>jdbc:mysql://localhost:3306/foodmart?useUnicode=true&characterEncoding=UTF-8</connection-url>
<user-name>jasperdb</user-name>
<password>password</password>
Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.
Settings for Java 1.6
If you are using Java 1.6, the recommended settings are slighly different than those for Java 1.5. Also, there are specific
settings needed to avoid class conflicts between java 1.6 and JasperServer web services.
For Java 1.6 JVM settings, refer to Appendix C "Java 1.6 JVM Settings".
General Note on Java Settings
The settings specified in this section apply specifically to the Sun JVM. Other JVM implementations may or may not have
equivalent settings.
22
JasperServer Installation Guide
5.12.1 JVM Options for JBoss
JBoss 4.2 includes an implemetation of web services. These web services classes can conflict with the web services classes
included with JasperServer. If you are using Java 1.6, the instructions in the section above walk through the steps to resovle
these conflicts.
However, if you are running JBoss 4.2 under Java 1.5, you will still need to set some specific JVM options so that the web
services analysis XMLA feature of JasperServer works.
For information on this, refer to section B.9.2, "JBoss 4.2 XMLA Connection Fix", in TroubleShooting Appendix B.
23
JasperServer Installation Guide
5.14.1 JasperServer Heartbeat
Upon first login to a newly installed JasperServer, you will be asked whether to opt-in to the JasperServer Heartbeat or not.
To opt-in, click OK. To opt-out, click the check box to remove the check and click OK.
The JasperServer heartbeat will help Jaspersoft create better products by improving our understanding of customer
installation environments. If you choose to enable the heartbeat, at server startup time the following information will be
sent to Jaspersoft via an https call:
• Operating System - type and version
• JVM - type and version
• Application Server - type and version
• Database - type and version
• JasperServer - type and version
• Unique, anonymous identifier value
You can also manually enable or disable the heartbeat by modifying the jasperserver/WEB-INF/applicationContext-
logging.xml file.
For additional information on enabling and disabling the heartbeat component refer to the JasperServer Administrator
Guide.
24
JasperServer Installation Guide
5.17.1 js.quartz.properties
Note: For release 3.1, the contents of the older js.mail.properties and js.scheduler.properties have been merged into the
single file js.quartz.properties.
The quartz properties file is found at the following location:
<apache-tomcat>/webapps/jasperserver/WEB-INF/js.quartz.properties
<jboss>/server/default/deploy/jasperserver/WEB-INF/js.quartz.properties
In this file you will find the configuration settings for you mail server, for additional scheduling email settings, and for the
underlying Quartz Framework used to enable the scheduling feature.
Quartz Driver Delegate Setting
MySQL
25
JasperServer Installation Guide
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
PostgreSQL
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
Note: For more information on the Quartz Framework, see the quartz website:
http://www.opensymphony.com/quartz
5.17.2 js.mail.properties
For the 3.1 release the contents of this file have been merged into the js.quartz.properties file.
5.17.3 js.schedular.properties
For the 3.1 release the contents of this file have been merged into the js.quartz.properties file.
26
JasperServer Installation Guide
27
JasperServer Installation Guide
28
JasperServer Installation Guide
29
JasperServer Installation Guide
cd <apache-tomcat>/work
Remove all files below "work" directory
Now you may start Tomcat. The MySQL database should already be running.
30
JasperServer Installation Guide
Note: The default MySQL database username in 3.0 is "jasperdb". In 2.1, the default database username is "jasperadmin".
In both cases, the default password is "password".
31
JasperServer Installation Guide
6.8.5 Update XMLA Connections (Optional)
When you upgrade your sample data to 3.1, you will normally get updated versions of your XMLA connection sample data.
XMLA connections use JasperServer login accounts for authentication. The default password used for the jasperserver
login user is now "jasperadmin". Because of this (and because you would normally update your jasperadmin password to a
new value as a standard security procedure), your XMLA connection may have an incorrect password.
If you would like to update your XMLA connections, refer to section 5.19, "Update XMLA ConnectionDefinitions".
32
JasperServer Installation Guide
33
JasperServer Installation Guide
8.1 Introduction
JasperServer is capable of running with encrypted passwords in the database. When this feature is enabled, passwords in
the database are stored as cipher text. Customers can choose the algorithm that JasperServer will use, as well as specify the
salt key used to initiate the encryption algorithm.
By default password encryption turned off.
This section describes the procedure to enable password encryption. For more information on JasperServer encryption
options refer to the JasperServer Administrator Guide.
You can use the jasperadmin user or the root user to carry out this operation. Refer to section 6.8.1, "Using mysqldump for
Database Backup", for more information on running the mysqldump command.
34
JasperServer Installation Guide
js-export.sh --everything --output-dir js-backup-catalog (Linux)
Note: There are two dashes (--) in front of the command options.
Refer to Appendix A, "Configuring the Import-Export Utility", for information on running the export utility.
Remaining Properties
The last two properties can be left unchanged. They are set to DESede by default. The default settings are the following:
<property name="secretKeyAlgorithm"><value>DESede</value></property>
<property name="cipherTransformation"><value>DESede/CBC/PKCS5Padding</value></property>
Note: As described in the JasperServer Administrator Guide, the secretKey, secretKeyAlgorithm, and
cipherTransformation property settings must be consistent with each other. For instance, different algorithms expect
different key lengths.
Encryption Now Enabled
Once the changes described above are made, encryption is enabled for the JasperServer application upon the next restart.
35
JasperServer Installation Guide
36
JasperServer Installation Guide
37
JasperServer Installation Guide
A.1 Introduction
The import and export utilities let you extract resources from or add resources to a JasperServer repository. The import
utility is typically used at installation time in order to load the JasperServer sample data into the repository.
You may refer to the JasperServer Administrator Guide for more information on command options for the import and
export utility.
38
JasperServer Installation Guide
To see that the import-export utility is properly configured, you can run the batch/shell scripts using the --help option which
displays the command options:
js-import.bat --help (Windows)
js-export.bat --help
js-import.sh --help (Linux)
js-export.sh --help
Note: There are two dashes (--) in front of the command option.
39
JasperServer Installation Guide
Appendix B: Troubleshooting
B.1 Installer Freezes
If you run the JasperServer installer on any platform and the installer “freezes” or “hangs”, it is helpful to look at the log
file created by the installer. This log file outputs status regarding the installer operations. If your installer has had an explicit
error, there may be a specific error message in the log. At a minimum, the log file should help narrow where the error has
occurred even if there is not a specific error message.
You can find the installer log in the following locations:
Windows:
C:\Documents and Settings\<username>\Local Settings\Temp\bitrock_installer_<number>.log
Linux:
/tmp/bitrock_installer.log or bitrock_installer_<number>.log
If you have tried multiple installs, make sure you view the most recent install log file.
41
JasperServer Installation Guide
• Click Save or Cancel when you are done.
• Test your report. If it still returns errors, edit the data source again and try checking other values, such as the port
used by the database.
Note: Refer to section 5.12, "Set Java JVM Options", for more information on Java JVM settings.
42
JasperServer Installation Guide
JDBC exception on Hibernate data access
org.hibernate.exception.GenericJDBCException: could not insert
the problem may be the default size of the MySQL “blob” datatype. You can increase the size of this datatype by updating
you’re my.ini or my.cnf MySQL configuration file.
Add the following setting:
max_allowed_packet=32M
43
JasperServer Installation Guide
<bean id="dataSource"
class="org.apache.commons.dbcp.datasources.SharedPoolDataSource">
<property name="connectionPoolDataSource">
<ref local="dsAdapter"></ref>
</property>
<property name="defaultAutoCommit" value="false"/>
<property name="maxActive" value="5"/>
<property name="maxIdle" value="4"/>
<property name="maxWait" value="10000"/>
</bean>
Copy js.jdbc-postgresql.properties:
<unpacked-war-dir>/scripts/postgresql/js.jdbc-postgresql.properties
To:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF
Edit properties file to match your PostgreSQL settings:
<jboss>/server/default/deploy/jasperserver.war/WEB-INF/js.jdbc-postgresql.properties
The operations above will fix the JBoss with PostgreSQL error that has the following error message:
org.hibernate.exception.GenericJDBCException: could not execute query
org.postgresql.util.PSQLException: Large Objects may not be used in auto-commit mode
Reference Link: http://forums.java.net/jive/thread.jspa?messageID=228420
B.9.2 JBoss 4.2 XMLA Connection Fix
JBoss 4.2 includes the JBossWS service as a standard, default feature. JasperServer has web services support for XMLA
connections. The web services classes in JasperServer and JBoss can conflict and cause the following error when
attempting to utilize a JasperServer XMLA connection:
javax.xml.soap.SOAPException: Unable to create message factory for
SOAP: org.jboss.ws.core.soap.MessageFactoryImpl
There are two workarounds for this problem. One would be to remove the JBoss web services service archive. The other is
to set special Java JVM options.
Remove JBoss Web Services
If you are not using JBoss web services, you can simply remove the JBoss web service archive to remove the possibility of
any conflicts. To do this, remove the following service archive:
<jboss>/server/defalut/deploy/jbossws.sar
Set Java JVM Options
If you are using Java 1.5 or Java 1.6, you can prevent the web services class conflict by setting the following special Java
JVM Options:
Option Target Value
Windows set JAVA_OPTS=%JAVA_OPTS% -Djavax.xml.soap.MessageFactory=org.apache.axis.soap.MessageFactoryImpl
44
JasperServer Installation Guide
Note: Refer to Appendix C: "Java 1.6 JVM Options" for more specific configuration information.
45
JasperServer Installation Guide
Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.
Note: You can cut and paste these settings from files in the <unpacked-war-dir>/scripts/java-settings directory.
Note: If you do not utilize JasperServer web services or resources that use them, you will not need the settings in the table
above.
46
JasperServer Installation Guide
47