Installing ReportServer on Windows

In this best-practice guide we discuss step-by-step how to manually install ReportServer on a freshly set-up Windows 10 box. If you would rather use a preconfigured installation package, have a look at the Bitnami ReporServer stack available from our download page.

The instructions in this guide are valid both for ReportServer Community Edition and for ReportServer Enterprise Edition (see here for a detailed comparison).

Overview

ReportServer is a database backed Java web application. In order to install ReportServer we additionally need to install Java, a servlet container (in this guide we choose Tomcat) and a database (in this guide we choose MariaDB). Thus, a high-level overview of an installation of ReportServer consists of the following steps.

  1. Overview
  2. Obtaining Binaries
  3. Install Java
  4. Install Tomcat
  5. Install MariaDB
  6. Setup ReportServer
  7. Setup Database
  8. Setup Logging
  9. Start ReportServer

Obtaining the ReportServer Binaries

The binaries for ReportServer Community Edition are available from SourceForge. On SourceForge look for Files and then the bin directory. Beneath the bin directory you should find directories for the various versions of ReportServer. At the time of writing, the latest version is ReportServer 3.0. Download the latest version (the file should be named RS followed by the version number and the build number, followed by reportserver.zip). For example, RS3.0.0-5803-reportserver.zip denotes ReportServer version 3.0 build number 5803.

To obtain a trial version of ReportServer Enterprise Edition go to our download page and look for Binaries.

Download ReportServer (either enterprise or community). We will get back to this shortly.

Installing Java

For a smooth experience it is best to install Oracle Java. You can download Java from http://www.java.com. If you are running on a 64-bit Windows (which is highly recommended when using ReportServer) you should ensure to download the 64-bit version of java. To see a list of all the available versions navigate to See all Java downloads or directly go to http://www.java.com/en/download/manual.jsp. There you should find a Windows Offline (64-bit) download. Download the installer.

Once you have downloaded the installer, run the installer and follow the instructions. Oracle decided to bundle some of the Java downloads with the Amazon Assistant. When asked whether you want to install the Amazon Assistant make sure to deactivate the checkbox. This is not necessary.

Once the installation is complete let us ensure that java is running properly. For this open a command prompt (open the Cortana quick search and search for cmd). Then run the following command

java -d64 -version

You should see a response similar to the following

java version "1.8.0_91"
Java(TM) SE Runtime Environment (build 1.8.0_91-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)

If so, you have successfully installed a 64-bit Java. Let's proceed with installing Tomcat.

Installing Tomcat

In the following we install Apache Tomcat a web application server that is well suited to run ReportServer. We will install Tomcat in version 8. The easiest is to install the 32-bit/64-bit Windows Service Installer. You find the download page in the left navigation.

Once the installer is downloaded, run the installer and follow the setup. You will be asked to choose the Components for the installation. Here choose the Minimum setup which consists only of the Start Menu Items. In the next step you can adapt Tomcat's basic configuration, to locate the installed Java JRE and to define the installation directory. The default values are usually fine so simply proceed.

Once the installation has finished you are asked whether to start Tomcat. For the moment we do not yet start Tomcat, so disable the checkbox and hit Finish.

In a next step we need to configure Tomcat. For this open the tomcat management application Configure Tomcat which you can find in the start menu. Go to the Java tab. Here we need to adapt the the Java Options as well the memory settings. Go to the end of the Java options and add the following lines

-Drs.configdir=C:\Program Files\reportserver
-Dfile.encoding=UTF8

The first one tells ReportServer that we are using an external configuration directory which will be C:\Program Files\reportserver. The second property tells Tomcat (and ReportServer) to use UTF8 encoding by default. As for the memory setting, set the initial memory pool to 512 MB and the maximum memory pool should be set to at least 1.5 GB. Click on Apply and then OK to close the configuration.

Next step is to install a database. ReportServer can be installed on DB2, MariaDB, MySQL, Microsoft SQL Server, Oracle or PostgreSQL. Here we choose MariaDB.

Installing MariaDB

You can find current installers for MariaDB on http://downloads.mariadb.org. Choose the latest stable version (at the time of writing 10.1.13) and download the corresponding 64-bit installer.

Once downloaded, run the installer. Note that Windows may regard MariaDB as an Unknown Publisher in which case it will ask you twice whether you want to run the installer. Hit Run anyway to continue and follow the setup steps. Most of the standard options are fine so the only thing you need to change is the root password and you should select the checkbox next to Use UTF8 as default server's character set. The UTF8 option is on the bottom of the same page as the password.

MariaDB comes with a copy of HeidiSQL which provides a front end to the database. Once the installation has finished, open HeidiSQL and create a new Session. Choose user root and the password that you provided during the installation and hit Open. You should now see your database.

To create the database for ReportServer, move the mouse to the left (Database) panel, right click and choose Create New -> Database. As name we choose reportserver and hit OK.

We will come back to the database in a bit to create the ReportServer tables. You may also want to create an additional user to be used by ReportServer that only has the privileges to work on the freshly created reportserver database. For the purpose of this guide, we assume that ReportServer will also use the root user.

Setting up ReportServer

Now that we have Tomcat and MariaDB set up, we can install and configure ReportServer. Let REPORTSERVER.zip denote the zip file that we downloaded in the very first step. Unzip the file.

Next, go to the Tomcat installation directory. If you haven't changed the directory during installation the directory should be

C:\Program Files\Apache Software Foundation\Tomcat 8.0

Here you should find a folder webapps that contains a single folder called ROOT. Remove the ROOT folder. Now move the extracted ReportServer folder into Tomcat's webapps directory and rename it to ROOT. Within the ROOT folder you should now have amongst others a folder called ddl and one called WEB-INF.

Next we create the ReportServer configuration directory. For this create the following directories

  • C:\Program Files\reportserver
  • C:\Program Files\reportserver\config
  • C:\Program Files\reportserver\lib

The lib directory can hold additional jars (for example, additional JDBC drivers). The config directory can hold internal configuration files. For further information about the config dir see the chapter on the configuration dir in ReportServer's Configuration Guide.

In a next step we will copy default configuration files to the configuration directory. We will copy the following files:

  • persistence.properties.example
  • reportserver.properties
  • logging-rs.properties
The files are located in the WEB-INF/classes directory. That is, if you installed Tomcat to its default location, the files are in

C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\ROOT\WEB-INF\classes

Copy the files to C:\Program Files\reportserver and rename the file persistence.properties.example into persistence.properties. This file holds the database configuration which we setup next. For this open the file persistence.properties with a text editor (if no proper editor is installed try Notepad++ which is freely available from https://notepad-plus-plus.org/) and set up the following connection parameters (replace the password with the password you chose during the MariaDB installation).

hibernate.connection.username=root
hibernate.connection.password=****
hibernate.dialect=net.datenwerke.rs.utils.hibernate.MariaDbDialect
hibernate.connection.driver_class=org.mariadb.jdbc.Driver
hibernate.connection.url=jdbc:mariadb://localhost:3306/reportserver

Initialize the ReportServer Database

ReportServer expects that its database is properly initialized. For this we need to run the DDL script for MySQL that is located in the ddl subdirectory of ReportServer (i.e., in C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\ROOT\ddl). ReportServer supports various databases and in that directory you not only find the create script for MySQL (which is also the one needed for MariaDB) but also for all other supported databases. The files are named according to the following format:

reportserver-VERSION-schema-MySQL5_CREATE.sql

Besides a CREATE script there is also a DROP script, if you wish to clean up the database.

To set up ReportServer's database again open HeidiSQL and a connect to the reportserver database. Select the database by double clicking in the left panel on the reportserver database. Next chose Load SQL file from the File Menu and select the reportserver-VERSION-schema-MySQL5_CREATE.sql file. Once the file is loaded you should see the file in within HeidiSQL. Hit F9 (or select the blue play button from the toolbar) to run the script. Wait for the script to finish (this can take a few seconds). Once finished you can close HeidiSQL.

If you are not installing on MariaDB make sure to call commit to commit the inserts at the end of the DDL.

Setup Logging

By default, Tomcat will write its log entries into a file called catalina.out, which not only contains ReportServer specific entries but anything that involves Tomcat. To have a ReportServer specific log file, edit the file C:\Program Files\Apache Software Foundation\Tomcat 8.0\conf\logging.properties. Note that this step is optional and can be skipped in which case the standard Tomcat log structure will be used.

To have a ReportServer specific log file, the following changes need to be made to C:\Program Files\Apache Software Foundation\Tomcat 8.0\conf\logging.properties:

  • add 5reportserver.org.apache.juli.FileHandler to handlers
  • define handler specific properties
  • tell tomcat to use the new handler for anything ReportServer specific
  • adapt the log format to include a proper timestamp

A sample configuration could look as follows:

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

handlers = 1catalina.org.apache.juli.AsyncFileHandler, 2localhost.org.apache.juli.AsyncFileHandler, 3manager.org.apache.juli.AsyncFileHandler, 4host-manager.org.apache.juli.AsyncFileHandler, 5reportserver.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

.handlers = 1catalina.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

1catalina.org.apache.juli.AsyncFileHandler.level = FINE
1catalina.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.AsyncFileHandler.prefix = catalina.

2localhost.org.apache.juli.AsyncFileHandler.level = FINE
2localhost.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
2localhost.org.apache.juli.AsyncFileHandler.prefix = localhost.

3manager.org.apache.juli.AsyncFileHandler.level = FINE
3manager.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
3manager.org.apache.juli.AsyncFileHandler.prefix = manager.

4host-manager.org.apache.juli.AsyncFileHandler.level = FINE
4host-manager.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
4host-manager.org.apache.juli.AsyncFileHandler.prefix = host-manager.

5reportserver.org.apache.juli.FileHandler.level = FINE
5reportserver.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
5reportserver.org.apache.juli.FileHandler.prefix = reportserver.

java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format = [%1$tc] %4$s: %2$s - %5$s %6$s%n

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = 2localhost.org.apache.juli.AsyncFileHandler

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = 3manager.org.apache.juli.AsyncFileHandler

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].handlers = 4host-manager.org.apache.juli.AsyncFileHandler

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/reportserver].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/reportserver].handlers = 5reportserver.org.apache.juli.FileHandler

# For example, set the org.apache.catalina.util.LifecycleBase logger to log
# each component that extends LifecycleBase changing state:
#org.apache.catalina.util.LifecycleBase.level = FINE

# To see debug messages in TldLocationsCache, uncomment the following line:
#org.apache.jasper.compiler.TldLocationsCache.level = FINE

Starting ReportServer

We are finally ready to start Tomcat and thus ReportServer. Again open the Tomcat management application. In the general tab on the bottom you have buttons for starting and stopping Tomcat. Hit Start. If everything goes fine, Tomcat should show a progress bar and then switch to showing Service Status: Started. To ensure that everything worked (or to find out what does not) let us have a look at the log files. They are located in

C:\Program Files\Apache Software Foundation\Tomcat 8.0\logs

again assuming that you installed Tomcat in its default location. There you should now find a log file called reportserver.DATE.log which, if everything went fine should have content similar to the following:

09-May-2016 04:21:02.518 INFO [localhost-startStop-1] net.datenwerke.rs.EnvironmentValidator.startup 


  _____                       _    _____                          
 |  __ \                     | |  / ____|                         
 | |__) |___ _ __   ___  _ __| |_| (___   ___ _ ____   _____ _ __ 
 |  _  // _ \ '_ \ / _ \| '__| __|\___ \ / _ \ '__\ \ / / _ \ '__|
 | | \ \  __/ |_) | (_) | |  | |_ ____) |  __/ |   \ V /  __/ |   
 |_|  \_\___| .__/ \___/|_|   \__|_____/ \___|_|    \_/ \___|_|   
            | |                                                   
            |_|                                                   

Version: RS3.0.1-5834 2016-03-24-23-46-15
Code Version: 2016-03-24-23-46-15
VM Args: -Dcatalina.home=C:\Program Files\Apache Software Foundation\Tomcat 8.0 -Dcatalina.base=C:\Program Files\Apache Software Foundation\Tomcat 8.0 -Djava.endorsed.dirs=C:\Program Files\Apache Software Foundation\Tomcat 8.0\endorsed -Djava.io.tmpdir=C:\Program Files\Apache Software Foundation\Tomcat 8.0\temp -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file=C:\Program Files\Apache Software Foundation\Tomcat 8.0\conf\logging.properties -Drs.configdir=C:\Program Files\reportserver -Dfile.encoding=UTF8 exit -Xms512m -Xmx2048m
rs.configdir: C:\Program Files\reportserver (OK)

### DB Config ###
hibernate.dialect: net.datenwerke.rs.utils.hibernate.MariaDbDialect (OK)
hibernate.connection.driver_class: org.mariadb.jdbc.Driver (OK)
hibernate.connection.url: jdbc:mariadb://localhost:3306/reportserver (OK)
hibernate.connection.username: root
hibernate.connection.password: ****
hibernate.default_schema: 

Connection Test: OK
Schema Version: RS3.0-7

09-May-2016 04:21:02.534 INFO [localhost-startStop-1] net.datenwerke.rs.EnvironmentValidator.startup Validating database schema...
09-May-2016 04:21:22.066 INFO [localhost-startStop-1] net.datenwerke.rs.EnvironmentValidator.hibernateValidateSchema Schema validation completed
09-May-2016 04:21:31.846 WARNING [localhost-startStop-1] net.datenwerke.rs.configservice.service.configservice.ConfigServiceImpl.getConfigFailsafe Configfile scheduler/scheduler.cf could not be loaded. Default values are in effect.
09-May-2016 04:21:31.846 WARNING [localhost-startStop-1] net.datenwerke.rs.configservice.service.configservice.ConfigServiceImpl.getConfigFailsafe Configfile exportfilemd/pdfexport.cf could not be loaded. Default values are in effect.
09-May-2016 04:21:31.846 WARNING [localhost-startStop-1] net.datenwerke.rs.configservice.service.configservice.ConfigServiceImpl.getConfigFailsafe Configfile exportfilemd/pdfexport.cf could not be loaded. Default values are in effect.
09-May-2016 04:21:48.408 INFO [localhost-startStop-1] net.datenwerke.rs.core.service.i18ntools.RemoteMessageServiceImpl. Loading messages... 
09-May-2016 04:22:00.518 INFO [localhost-startStop-1] net.datenwerke.rs.core.service.i18ntools.RemoteMessageServiceImpl. Available locales: de, fi, pt, bg, keys, lt, hr, lv, fr, hu, zh-CN, sk, sl, ga, sv, zh-TW, el, mt, en, it, es, et, cs, pl, da, ro, nl
09-May-2016 04:22:05.519 INFO [Thread-12] net.datenwerke.rs.installation.ExecutePackagedScriptsTask.executeOnFirstRun Executing package scripts from: C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\ROOT\pkg
09-May-2016 04:22:05.596 INFO [Thread-12] net.datenwerke.rs.installation.ExecutePackagedScriptsTask.executeOnFirstRun Executing package: C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\ROOT\pkg\baseconfig-RS3.0.1-5834-2016-03-24-23-46-15.zip
09-May-2016 04:22:21.268 INFO [Thread-12] net.datenwerke.rs.installation.DemoDataInstallTask.executeOnStartup Loading demodata
09-May-2016 04:23:22.299 INFO [Thread-12] net.datenwerke.rs.core.service.jarextension.hookers.ReportServerExtenderHooker.initialize Start loading ReportServer extensions.
09-May-2016 04:23:24.518 INFO [Thread-12] net.datenwerke.rs.search.service.search.SearchServiceImpl.rebuildIndex Rebuilding search index...
09-May-2016 04:23:24.862 INFO [Thread-12] net.datenwerke.gf.service.lateinit.LateInitStartup$1.run Startup completed

The last line (Startup complete) indicates that ReportServer was properly started. You can now direct your browser to

http://127.0.0.1:8080/ReportServer.html

and log in to ReportServer via user root with password root which ReportServer created on the first start.

Happy Reporting