atori GmbH

Dossenheimerstr. 17

68519 Viernheim

RedmineReport
Manual Installation Guide

Stand:

09.05.2014

Der Inhalt dieses Dokuments darf ohne vorherige schriftliche Erlaubnis durch atori GmbH nicht (ganz oder teilweise) reproduziert,
benutzt oder verffentlicht werden. Das Copyright gilt fr alle Formen der Speicherung und Reproduktion, in denen die vorherigen
Informationen eingeflossen sind, einschlielich, und zwar ohne Begrenzung fr Magnetspeicher, Computerausdrcke und visuelle
Anzeigen

atori GmbH 2014

atori GmbH 2014

Table of Content

Manual Installation Guide

TABLE OF CONTENT

Table of Content .................................................................................................................. 2

Manual Installation............................................................................................................... 3
2.1

Preamble ..................................................................................................................... 3

2.2

Limitations ................................................................................................................... 3

2.3

Requirements ............................................................................................................... 3

2.4

Files contained in the distribution zip ............................................................................... 4

2.5

Step by Step Installation ................................................................................................ 4

2.5.1

Shut down your tomcat server ............................................................................... 4

2.5.2

Create the database resources ............................................................................... 4

2.5.3

Publish the database resources in the global context ................................................. 5

2.5.4

Install the database drivers ................................................................................... 5

2.5.5

Adjust the tomcat memory .................................................................................... 5

2.5.6

Startup your tomcat server .................................................................................... 6

2.5.7

Deploy JASReport.war ........................................................................................... 6

2.5.8

Stop JASReport .................................................................................................... 7

2.5.9

Configure JASReport (1) ........................................................................................ 7

2.5.10

Start JASReport ................................................................................................... 7

2.5.11

Initialize JASReport database ................................................................................. 7

2.5.12

Configure JASReport (2) ........................................................................................ 9

2.5.13

Install birt.war ..................................................................................................... 9

2.5.14

Install the RedmineReport packages ....................................................................... 9

2.5.15

Check Status ..................................................................................................... 11

2.5.16

Use RedmineReport ............................................................................................ 11

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 2 von 11

Manual Installation

2
2.1

Manual Installation Guide

MANUAL INSTALLATION
Preamble
Although we highly recommend using the preconfigured setup for RedmineReport, there might
be reasons why one would like to not do so and setup a RedmineReport system from scratch.
This might be because the system should run on Linux or because an already running instance
of tomcat needs be used. Please understand, this is a free appliance of JASreport which can be
installed in various settings and environments with lots of different aspects and we are only able
to provide you a common procedure of how to install the system but without addressing the
system specific aspects that might occur.
In case you are installing into an existing tomcat or database server which is used for
other purposes as well, make sure you always perform a backup of your system
before proceeding with the installation. Also, although we do not expect any serious
problems, make sure that you can tolerate possible downtimes of your server in case
something goes wrong.
atori GmbH provides you with the software 'as-is' without any responsibility for its function,
usability, availability and accuracy. In no event will atori GmbH or its affiliates or suppliers be
liable to you for any loss, damages, claims or costs whatsoever including any consequential,
indirect or incidental damages, any lost profits or lost savings, any damages resulting from
business interruption, personal injury or failure to meet any duty of care, or claims by a third
party, even if an atori GmbH representative has been advised of the possibility of such loss,
damages, claims or costs. The foregoing limitations and exclusions apply to the extent
permitted by applicable law in your jurisdiction.

2.2

Limitations
This document describes the manual installation of a RedmineReport system, which runs on an
apache tomcat server and connects to different SQL databases. These servers are required
beforehand and neither the setup or configuration nor the maintenance of those servers is
addressed here.

2.3

Requirements
This manual requires a running installation of a tomcat 7 server, access to a SQL database
server of either MySQL, MSSQL, PostgreSQL, Oracle or Derby, 1GB of free memory and about
200 MB hard drive space.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 3 von 11

Manual Installation

2.4

Manual Installation Guide

Files contained in the distribution zip

File name

Description

birt.war

Reporting engine

JASReport.war

JASreport application

jasreport.properties

Predefined properties

flushParameterRedmine.properties RedmineReport properties

2.5

jasreport.license

License file

RedmineReport.pkg

RedmineReport package

ThemeRedmineReport.pkg

Redmine theme package

Step by Step Installation

The installation consists of two parts, global installations/configurations of your tomcat server and
application specific configurations.
Depending on your tomcat server installations some of the settings can be changed online.
In this manual, we do all server specific changes offline.

2.5.1

SHUT DOWN YOUR TOMCAT SERVER

This is usually done by stopping the service with the service management application or in case
you run your tomcat as a console application by sending a CTRL-C to the console window.

2.5.2

CREATE THE DATABASE RESOURCES

To create the database resource you need to edit1 the server.xml file in your [TOMCAT]/conf
directory. RedmineReport needs two database connections to work. One is used to store all the
local configuration data like users, report definitions, dashboard and so on. The objects in this
database will be changed by RedmineReport and therefore the access must not only include
select permission but also update, delete, insert and all the ddl related permissions.

Use text editor of your choice but make sure the the xml file stays valid!
/

RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 4 von 11

Manual Installation

To

define

Manual Installation Guide

the

resource

find

the

section

<Resource
name="jdbc/jasreport"

<GlobalNamingResources> and insert the following

type="javax.sql.DataSource"
maxActive="100"

section:

maxIdle="2"
username="jasreport"
password="jasreport"
maxWait="5000"
driverClassName="org.apache.derby.jdbc
.ClientDriver"
url="jdbc:derby://localhost:1527/jasre
port;create=true"
removeAbandoned="true"
logAbandoned="true"
removeAbandonedTimeout="60"
/>

The second required database connection is your

<Resource
name="jdbc/redmine"

Redmine database. This database is the source for

type="javax.sql.DataSource"

all the reports and will be used read only. To define

maxActive="100"

the resource add the following section to your

username="redmine"

maxIdle="2"
password="redminepw"

server.xml right after the internal database.

maxWait="5000"
driverClassName="com.mysql.jdbc.Driver
"
url="jdbc:mysql://10.1.5.251:3306/redm
ine"
removeAbandoned="true"
logAbandoned="true"
removeAbandonedTimeout="60"
/>

2.5.3

PUBLISH THE DATABASE RESOURCES IN THE GLOBAL CONTEXT

To publish the database resources edit the context.xml file in your [TOMCAT]/conf directory.
Locate the <Context> section and add the following statements:

<ResourceLink global="jdbc/jasreport" name="jdbc/jasreport" type="javax.sql.DataSource"/>

<ResourceLink global="jdbc/redmine" name="jdbc/redmine" type="javax.sql.DataSource"/>

2.5.4

INSTALL THE DATABASE DRIVERS

Depending on your database choice, copy the jdbc database drivers to your [TOMCAT]/lib
directory. In our case here, this would be derbyclient.jar and mysql-connector-java-3.1.12-bin.jar

2.5.5

ADJUST THE TOMCAT MEMORY

Make sure your tomcat server has enough memory available and check the size of the permgen
memory.
/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 5 von 11

Manual Installation

Manual Installation Guide

A good practice setting would be a maximum memory of 1GB and a permgen size of 256MB.
JAVA_OPTS="-server -Xms128M Xmx1024M -XX:MaxPermSize=256M
For more information about memory setting please refer to the tomcat documentation.

2.5.6

STARTUP YOUR TOMCAT SERVER

Similar to Step 1 this is done with the service management application or in our case by running
the startup.bat command in the [TOMCAT]/bin directory.

2.5.7

DEPLOY JASREPORT.WAR

To deploy the JASReport application just copy the

JASReport.war

file

to

the

[TOMCAT]/webapps

directory or use the tomcat management website.

The outcome of the deployment should be a directory
JASReport under [TOMCAT]/webapps with a structure
like this:

If you follow the output on the server console you will notice, that the server printed several error
messages and that the application has not been started or is uninitialized.

At this point this is OK, since important configuration has not been done yet.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 6 von 11

Manual Installation

2.5.8

Manual Installation Guide

STOP JASREPORT

To add the required configuration data, JASReport needs to be offline. So either stop JASReport
now by using the tomcat management website or just simply shutdown your tomcat server.

2.5.9

CONFIGURE JASREPORT (1)

Navigate to [TOMCAT]/webapps/JASReport/WEB-INF and replace the jasreport.licence and

jasreport.properties with the files from the zip.

2.5.10 START JASREPORT

If you have stopped the JASReport application using the management website, start the
application now again. If you have stopped your whole tomcat server, start the server now.

2.5.11 INITIALIZE JASREPORT DATABASE

Open a browser your choice and navigate to http://localhost:8080/JASReport/initApplication.zul,
make sure the port matches your tomcat port.

You should see something like:

At this point you can ignore error messages, if any, as long as you can proceed with OK to the
next screen. If not, try to reload the page in your browser.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 7 von 11

Manual Installation

Manual Installation Guide

Check your database connection again

Enter the connection to your mail server and then press the marked button in the toolbar.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 8 von 11

Manual Installation

Manual Installation Guide

After a little while, you will be redirected to the main login screen.

2.5.12 CONFIGURE JASREPORT (2)

Shut down the application or your server (s. before).
Copy flushParameterRedmine.properties to [TOMCAT]/webapps/JASReport/WEB-INF, open the
file in a text editor and change the port 19283 according to the port your tomcat is listening on.
Start up the application or your server.

2.5.13 INSTALL BIRT.WAR

As in Step 7, either install the birt.war by using the tomcat management website or by simply
copying the file to the [TOMCAT]/webapps directory

2.5.14 INSTALL THE REDMINEREPORT PACKAGES

Now open a webbrowser and navigate to http://localhost:8080/JASReport and login the
application with user admin and password admin.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 9 von 11

Manual Installation

Manual Installation Guide

Open the packages explorer by pressing the marked button in the toolbar:

Drop the files RedmineReport.pkg and ThemeRedmineReport.pkg in the marked spot:

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 10 von 11

Manual Installation

Manual Installation Guide

Now select them one by one and install them by pressing the button marked in the following
picture

2.5.15 CHECK STATUS

Check for memory exceptions on the server console and if there are some, restart your tomcat
server.

2.5.16 USE REDMINEREPORT

Congratulations, you have installed RedmineReport. If your tomcat server was not restarted
during the last step, you are probably still logged in the system after the package installation. In
order to use the Redmine packages, you need to refresh your session and the browser cache.
When you use RedmineReport for the first time, it will take a while until the reports are created
and displayed. So after you have opened a report or dashboard, please allow the system to
startup, which might take up to two minutes. This should only happen initially, after that the
reports should be displayed within seconds.

/
RedmineReport

Manual Installation Guide

atori GmbH Dossenheimerstr. 17 68519 Viernheim

Seite 11 von 11