1. Home
  2. Tutorials
  3. Best-Practice Guide - Installing ReportServer on Ubuntu

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. 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 Bitnami ReporServer stack 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.2.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, RS4.2.0-6070-reportserver.zip denotes ReportServer version 4.2.0 build number 6070.

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: 

$ wget https://sourceforge.net/projects/dw-rs/files/bin/3.1/RS4.2.0-6070-2022-08-09-14-35-59-src-reportserver-ce.zip/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. A detailed installation of how to install Oracle Java 8 can be found, for example, o http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html. The Webupd8 team provides Ubuntu packages for Java. The first step is to add the repository 

$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update

If the repositories were properly added, we can now install java via: 

$ sudo apt-get install oracle-java8-installer

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

$ java -version
java version "1.8.0_72"
Java(TM) SE Runtime Environment (build 1.8.0_72-b15)
Java HotSpot(TM) 64-Bit Server VM (build 25.72-b15, mixed mode)

Finally, we should set up java environment variables via:

sudo apt-get install oracle-java8-set-default

You should ensure that the JAVA_HOME environment variable is set and that it points to the java installation. If

$ echo $JAVA_HOME

is empty, you might need to restart the machine for the environment variables to take effect.

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 tomcat7, ReportServer should however also run on newer versions of Tomcat) issue the following command 

$ apt-get install tomcat7

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 or, as we will explain next, configure Tomcat to use authbind. First ensure that the authbind packages are installed: 

$ apt-get install authbind

Next, we need to configure Tomcat and tell it to use authbind as well as how to invoke java. On Ubuntu you can find these options in the configuration file /etc/default/tomcat7. Open this file with your favorite editor 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: 

JAVA_OPTS="-Djava.awt.headless=true -Xmx4g  -XX:+UseConcMarkSweepGC -Dfile.encoding=UTF8"

JAVA_OPTS="${JAVA_OPTS} -Drs.configdir=/opt/reportserver"

If you use Java 9 or newer, you need some extra configuration which can be done in the 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
  • -Djavax.net.ssl.trustStoreType=JKS

The config file also holds the configuration option for authbind, which by default is turned off. To enable it set 

AUTHBIND=yes

Store your changes and exit the file. Next we need to configure authbind in order to allow Tomcat to bind to port 80. In case you want to serve ReportServer only via HTTPS (on the standard port 443) you need to perform the same steps for port 443. For this we first need to get Tomcat's user id. For this, have a look at the /etc/passwd file:

$ grep -ri tomcat /etc/passwd
tomcat7:x:105:112::/usr/share/tomcat7:/bin/false

This tells us that Tomcat's user has the UID 105. We next go to the authbind byuid directory and create a file with that UID which we then give to the Tomcat user: 

$ cd /etc/authbind/byuid
$ touch 105
$ chown tomcat7:tomcat7 105
$ chmod u+x 105

Next we go to authbind's byport directory, and create files for the port 80 which we also give to the Tomcat user: 

$ cd /etc/authbind/byport
$ touch 80
$ chown tomcat7:tomcat7 80
$ chmod u+x 80

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

 <Connector port="80" protocol="HTTP/1.1"
	connectionTimeout="20000"
    URIEncoding="UTF-8"
    redirectPort="8443" />

Tomcat should now be properly configured and you can give it a test spin. Start Tomcat via:

$ service tomcat7 start

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

http://YOUR_IP

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 

$ service tomcat7 stop

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

Install PosgreSQL via

$ sudo apt-get install postgresql postgresql-contrib

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

$ sudo -u postgres psql postgres
\password postgres
Enter new password: postgres
Enter it again: postgres

Press CTRL+D to leave the command prompt.

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

$ sudo -u postgres createdb reportserver

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

$ sudo -u postgres  createuser -P -s -e reportserver
Enter password for new role: reportserver
Enter it again: reportserver
CREATE ROLE reportserver PASSWORD 'md5d551331e985d0bc05820de8666e79f60' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;

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

$ sudo -u postgres psql
GRANT ALL PRIVILEGES ON DATABASE reportserver TO reportserver;
CTRL+D

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/9.3/main/pg_hba.conf. Here look for a line containing 

local   all             all                    		            peer

and replace it by

local   all             all                    		            md5

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

$ service postgresql restart

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:

$ apt-get install unzip

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

$ rm -r /var/lib/tomcat7/webapps/ROOT

Now unzip REPORTSERVER.zip to that directory.

$ unzip REPORTSERVER.zip -d /var/lib/tomcat7/webapps/ROOT

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.

$ mkdir /opt/reportserver
$ mkdir /opt/reportserver/lib
$ mkdir /opt/reportserver/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

$ cp /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/persistence.properties.example /opt/reportserver/persistence.properties
$ cp /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/reportserver.properties /opt/reportserver/reportserver.properties
$ cp /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/logging-rs.properties /opt/reportserver/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

hibernate.connection.username=reportserver
hibernate.connection.password=reportserver
hibernate.dialect=net.datenwerke.rs.utils.hibernate.PostgreSQLDialect
hibernate.connection.driver_class=org.postgresql.Driver
hibernate.connection.url=jdbc:postgresql://localhost/reportserver

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

chown -R tomcat7:tomcat7 /opt/reportserver

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/tomcat7/webapps/ROOT/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:

psql -U reportserver -d reportserver -a -f /var/lib/tomcat7/webapps/ROOT/ddl/reportserver-VERSION-schema-PostgreSQL_CREATE.sql

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 /etc/tomcat7/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:

# 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.FileHandler, 2localhost.org.apache.juli.FileHandler, 5reportserver.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

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

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

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

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

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

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 com.xyz.foo logger to only log SEVERE
# messages:
#org.apache.catalina.startup.ContextConfig.level = FINE
#org.apache.catalina.startup.HostConfig.level = FINE
#org.apache.catalina.session.ManagerBase.level = FINE
#org.apache.catalina.core.AprLifecycleListener.level=FINE

Starting ReportServer

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

service tomcat7 restart
tail -f /var/log/tomcat7/reportserver.DATE.log

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

[DATE] INFO: net.datenwerke.gf.service.lateinit.LateInitStartup$1 run - Startup completed

You can now direct your browser to

http://YOUR_IP/ReportServer.html

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

Happy Reporting