Chapter 2. Installation

The ReportServer installer stack is available for Windows and provides a pre-configured installation of ReportServer with Apache Tomcat as application server and MariaDB as database backend. The installers are available from http://reportserver.net/download. The installation wizard guides you through the installation providing you with the option to pre-configure parts of ReportServer and you can choose whether to install the demo package or not (we note that you can also manually install the demo data later; see Section 2.4.). In case you already have an application server or MariaDB database running and the default ports are in use, you are asked to provide alternative ports.

Installation on Linux machines should be done manually or using the docker images available here: http://reportserver.net/download.

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

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:

set
JAVA_OPTS=++JvmOptions="-Drs.configdir=C:/infofabrik/reportserverenterprise-x.x.x-yyyy-0/apps/reportserver/reportserver-conf"
++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=

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:

-Xmx4096M
-XX:MaxPermSize=512M
-Dfile.encoding=UTF8

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

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

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:

path_to_webapps/reportserver/WEB-INF/lib.

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:

reportserver-RSx.x.x-yyyy-schema-PostgreSQL_CREATE.sql.

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.

hibernate.dialect=net.datenwerke.rs.utils.hibernate.MySQL5Dialect
hibernate.connection.driver_class=com.mysql.cj.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/reportserver
hibernate.connection.username=root
hibernate.connection.password=root

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.

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

To run ReportServer on JBoss Wildfly only a few configuration options need to be considered. First, you should ensure that JBoss is configured to use sufficient memory. The necessary changes can be made in file wildfly/bin/standalone.conf (or standalone.conf.bat for windows systems). To run ReportServer you should provide JBoss with at least 1.5 GB of heap space. Depending on the number of users, this value should be increased. Following is an example configuration:

JAVA_OPTS="-Xms64m -Xmx2g -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"

Besides increasing the memory as described above, you will need to add an application descriptor file called jboss-deployment-structure.xml. You will need to place this configuration file into the WEB-INF directory of ReportServer. Following is the content of the descriptor.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.hibernate" />
      <module name="org.antlr" />
    </exclusions>
    <exclude-subsystems>
      <subsystem name="weld" />
      <subsystem name="org.hibernate" />
      <subsystem name="org.hibernate.validator" />
      <subsystem name="org.antlr" />
      <subsystem name="jpa" />
    </exclude-subsystems>
    <dependencies>
      <module name="org.bouncycastle" />
    </dependencies>
  </deployment>
</jboss-deployment-structure>

Having increased the memory and added the jboss-deployment-structure.xml to the ReportServer WEB-INF directory, you are now good to go.

ReportServer comes with a demo data package containing the example setup of the fictionally toy company ''1-to-87''. In order to install the demodata package you should login with a root account (if you used the Windows installer, this would be the account you setup during installation). Also note that the installation of the demodata will remove any existing data in the system. To install the demo package login to ReportServer and open the terminal by pressing

CTRL+ALT+T

Then, to initiate the installation, run the command

pkg install -d demobuilder-VERSION_NR

Here, ''VERSION_NR'' must be replaced by the correct version, which can be obtained by using the autocomplete feature of the terminal. Simply hit TAB to get a list of options:

pkg install -d [TAB]