Installing ReportServer on Ubuntu

In this best-practice guide we discuss step-by-step how to manually install ReportServer on a freshly set-up Ubuntu box (Version 22.04). While we have chosen Ubuntu as the underlying operating system we hope that this guide also helps with setting up ReportServer on different operating systems. If you would rather use a preconfigured installation package, have a look at the docker images available from our download page.

In this guide we discuss how to install ReportServer. This instruction is 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 and thus 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 PostgreSQL). Thus, a high-level overview of an installation of ReportServer consists of the following steps.

1. Obtaining the ReportServer binaries
2. Installation of Java
3. Installation of Tomcat
4. Installation of PostgreSQL
5. Setting up 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 4.7. 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, RS4.7.2-6108-reportserver.zip denotes ReportServer version 4.7.2 build number 6108.

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

Go to your home directory (or some directory where we can store the binaries for now) and download ReportServer via https://sourceforge.net/projects/dw-rs/files/latest/download

Note that you need to adapt the version number. We will get back to the binaries in a moment. First, let's install Java, Tomcat and PostgreSQL.

Installing Java

For a smooth experience it is best to install Oracle Java or OpenJDK (via repository) or Azul Zulu Builds of OpenJDK (https://www.azul.com/downloads/?version=java-11-lts&os=ubuntu&architecture=x86-64-bit&package=jre).

If java has been installed successfully, then a call to java -version should print out the installed java version.

Installing Tomcat

In the following we install Apache Tomcat a web application server that is well suited to run ReportServer. To install Tomcat (currently Ubuntu has precompiled packages for tomcat9 (Tomcat 10 is not supported by ReportServer at the moment)) issue the following command

Next, we need to configure Tomcat and tell it to invoke java. On Ubuntu you can find these options in the configuration file /etc/default/tomcat9. Open this file with your favorite editor (e.g. nano) and look for the setting for JAVA_OPTS. This tells Tomcat how to invoke java. In particular you should set the options -Xmx4g (which will set the memory of Tomcat and thus ReportServer to 4 GB), -Dfile.encoding=UTF8 (to use UTF-8 by default) and -Drs.configdir=/opt/reportserver (to configure ReportServer's config dir; we will see the effect of this later). Thus, you could have the following configuration:

If you use Java 11 or newer, (ReportServer currently supports Java 11 and Java 17), you need some extra configuration which can be done in the setenv.sh of your Tomcat environment ( /usr/share/tomcat9/bin/setenv.sh). Specifically, the following configuration is needed:

By default the Tomcat web server will listen on port 8080. Standard web applications are, however, usually run on port 80. To allow serving ReportServer directly on port 80, you can either configure a reverse proxy (e.g. via Apache) or, as we will explain next, configure Tomcat to use authbind. You can't use port 80 because ports under 1024 are restricted to root access in Linux (and we don't want that für our Tomcat) unless you use authbind to override that restriction. First ensure that the authbind packages are installed:

Next we go to authbind's byport directory, and create files for the port 80 which we also give to the Tomcat user. This user was automatically created at the process of installing tomcat "apt-get install tomcat":

Next step, modify systemctl to use AUTHBIND when starting the tomcat

Finally, we need to change Tomcat's default connector configuration to listen on port 80. For this change the connector settings in server.xml.

Tomcat should now be properly configured and you can give it a test spin. Reload the systemd manager configuration (because of our ExecStart change) and restart Tomcat via

Make sure that you can connect to Tomcat on port 80 by simply pointing your browser to

where YOUR_IP is the server's IP address (for example, 127.0.0.1, if you are on the same machine). If Tomcat is running properly, stop it again via

Installing PostgreSQL

Having installed Tomcat, we next need to install a database to hold ReportServer's metadata. For this we will use PostgreSQL in this guide. At the time of writing the latest prepackeged Ubuntu packages is for PostgreSQL 14.5.

Install PosgreSQL via

Next we setup a password for the postgres main user (called postgres). For convenience we here assume that the password is set to postgres

Press CTRL+D (corresponds \q) to leave the command prompt.

Next, we create a database called reportserver which will serve as the metadata storage for ReportServer. For run

To set up a database user for reportserver (with password reportserver) run

Next we need to grant user reportserver the necessary privileges. For this we run

Finally, since PostgreSQL on Ubuntu per default only allows to connect locally via the postgres user, we need to adapt the configuration file /etc/postgresql/14/main/pg_hba.conf. Here look for a line containing

and replace it by

Which allows users that provide a valid password hash to connect. For the changes to take effect we need to restart the postgres service.

Setting up ReportServer

Now that we have Tomcat and PostgreSQL set up, we can install and configure ReportServer. Let REPORTSERVER.zip denote the zip file that we downloaded in the very first step. If not already present let's install unzip.

Next, remove the folder ROOT beneath Tomcat's webapp folder. This is where afterwards we are going to put ReportServer in.

Now unzip RS4.7.VERSION-reportserver-ce.zip to that directory. But before executing, change MYUSER to your user or the path to the directory where you stored the downloaded zip-file.

In the next step we will create a configuration directory for ReportServer. Remember that when we configured Tomcat, we set the environment variable JAVA_OPT to contain the option -Drs.configdir=/opt/reportserver. This tells ReportServer to look for its configuration directory in /opt/reportserver. Let's create that directory as well as the sub-directories lib and config.

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

Note that we have renamed "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 and set up the following connection parameters

Having changed the configuration, let's give the tomcat user the necessary permissions to read the configuration files.

The same applies for tomcat webapps.

Initialize the ReportServer Database

ReportServer expects that its database is properly initialized. For this we need to run the DDL script for PostgreSQL that is located in the ddl subdirectory of ReportServer (i.e., in /var/lib/tomcat9/webapps/ddl). ReportServer supports various databases and in that directory you not only find the create script for PostgreSQL but also for all other supported databases. The files are named according to the following format:

reportserver-VERSION-schema-PostgreSQL_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 run the following command to run the CREATE ddl:

If you run the ddl script via a database GUI make sure to call commit.

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 /var/lib/tomcat9/conf/logging.properties. The following changes need to be made:

• 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:

Starting ReportServer

We are finally at an end. To test the installation, start tomcat and observe the output in ReportServer's log file.

If all goes well you should see a message such as:

You can now direct your browser to

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

Happy Reporting