RedmineReport Manual Installation

atori GmbH Dossenheimerstr. 17 68519 Viernheim

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

RedmineReport

Manual Installation Guide

Stand: 09.05.2014

Table of Content Manual Installation Guide

/

RedmineReport Manual Installation Guide Seite 2 von 11


1 TABLE OF CONTENT

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

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

Manual Installation Manual Installation Guide

/



2 MANUAL INSTALLATION

2.1 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.


/



2.4 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

jasreport.license License file

RedmineReport.pkg RedmineReport package

ThemeRedmineReport.pkg Redmine theme package

2.5 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.

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


/



To define the resource find the section

and insert the following

section:

The second required database connection is your

Redmine database. This database is the source for

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

the resource add the following section to your

server.xml right after the internal database.

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 section and add the following statements:

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.


/



A good practice setting would be a maximum memory of 1GB and a permgen size of 256MB.

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.

JAVA_OPTS="-server -Xms128M Xmx1024M -XX:MaxPermSize=256M


/



2.5.8 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.


/



Check your database connection again

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


/



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.


/



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

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


/



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.

Documents

RedmineReport Manual Installation