2.2. Manual Installation

The manual installation allows you to fine-tune the installation process to your environment and is generally recommended for any production environment.

2.2.1. Installation of the Java Runtime Environment (JRE)

ReportServer requires an installed Java Runtime Environment (JRE) in version 11 or newer.

Further, you need some extra configuration which can be done in the setenv.bat / setenv.sh of your Tomcat environment. Specifically, the following configuration is needed:

  • --add-opens=java.base/java.net=ALL-UNNAMED
  • --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED
  • --add-opens=java.base/jdk.internal.reflect=ALL-UNNAMED
  • --add-opens=java.base/java.lang.invoke=ALL-UNNAMED
  • --add-opens=java.base/java.util=ALL-UNNAMED
  • -Djavax.net.ssl.trustStoreType=JKS
  • -Dfile.encoding=UTF-8
  • -Djava.awt.headless=true

The following is an example configuration in our Windows packages where the configuration mentioned above is integrated:

++JvmOptions="-Dfile.encoding=UTF-8" ++JvmOptions="-Djava.awt.headless=true" ++JvmOptions="--add-opens=java.base/java.net=ALL-UNNAMED" ++JvmOptions="--add-opens=java.base/jdk.internal.ref=ALL-UNNAMED" ++JvmOptions="--add-opens=java.base/jdk.internal.reflect=ALL-UNNAMED" ++JvmOptions="--add-opens=java.base/java.lang.invoke=ALL-UNNAMED" ++JvmOptions="--add-opens=java.base/java.util=ALL-UNNAMED" ++JvmOptions="-Djavax.net.ssl.trustStoreType=JKS" --JvmMs 512 --JvmMx 1536 set JDK_JAVA_OPTIONS=
If the host computer supports it, you should use the 64-bit edition.
2.2.2. Installation and configuration of the application server

ReportServer can be configured to run in any application server that supports the Java Servlet Technology (e.g., Jetty, Tomcat or JBoss Wildfly). We recommend using Apache Tomcat (http://tomcat.apache.org/).

In order to smoothly run ReportServer it is necessary to provide the application server with sufficient memory which usually means that you have to increase the default values. If too little memory is available then ReportServer might not start at all or your users might experience performance problems. The following recommendations are to be understood as lower bounds. Depending on your environment (the types of reports that you want to run and the number of users the system is to handle) you might need to increase these (especially the available heap size).

We recommend to set the available permanent generation space (PermGenSpace) to at least 256mb (better 512mb). The maximal available heap size should be at least 1.5gb.

Furthermore, the encoding should be set to UTF8.

A sample configuration of the VM might look as follows:


Further information can be found, for example, at http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html.

2.2.3. Unpack the zip-archive

Stop the application server, if it was running, and unpack the ReportServer archive to a directory called reportserver below the webapps directory of your application server (on Windows this could be, for example, C:\Program Files\Apache Tomcat\webapps; on Linux /var/tomcat/webapps).

2.2.4. Setup the database

Before we can start the application server we need to configure the database connection that ReportServer uses to store its metadata. ReportServer internally uses JPA with Hibernate (http://www.hibernate.org/) which allows us to support most popular database systems. A list of the database systems supported by Hibernate can be found at https://developer.jboss.org/docs/DOC-13921.

Installation of the JDBC driver

ReportServer comes bundled with drivers for the open source databases MySQL (http://www.mysql.com) and PostgreSQL (http://www.postgresql.org). If you use either of these databases you do not need to manually copy the jdbc driver to the lib directory. If you use any other database you need to copy the corresponding JDBC driver to ReportServer's lib directory, that is, to directory:


Creating the ReportServer schema

Next we need to setup the necessary database tables. For this, choose the create script corresponding to your database system from the directory "ddl" (directly beneath the reportserver directory) and execute it on your database. For a PostgreSQL database, for example, use the file:


Adapt the persistence.properties config file

To complete the database setup we need to configure the connection properties. For this, go to WEB-INF/classes and edit the file persistence.properties. The file persistence.properties contains the configuration of the ReportServer database connection. You can find further information on this config file in Chapter 3. Following is a sample configuration for MySQL.

2.2.5. The config file reportserver.properties

The final step in the installation is to check the (and possibly adapt) the main configuration settings. These are stored in the the config file reportserver.properties which is located in the WEB-INF/classes directory. It contains basic properties concerning the available authentication procedures used by ReportServer as well as configuration for cryptopgraphic functionality used in ReportServer.

A detailed description of the available parameters are given in Chapter 3. External Configuration Files.

2.2.6. Application Server Start

You can now start the application server. Once the application server is started up ReportServer should be accessible, for example, under the URL http://localhost:8080/reportserver. ReportServer has generated the root user with which you can login:

username: root
password: root