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.- Obtaining the ReportServer binaries
- Installation of Java
- Installation of Tomcat
- Installation of PostgreSQL
- 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.6.1. 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.6.1-6098-reportserver.zip denotes ReportServer version 4.6.1 build number 6098.
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/bin/3.1/RS4.6.1-6098-2023-09-21-00-57-26-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 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).
$ sudo apt-get update $ sudo apt install openjdk-11-jdk
If java has been installed successfully, then a call to java -version should print out the installed java version.
$ java -version openjdk version "11.0.16" 2022-07-19 OpenJDK Runtime Environment (build 11.0.16+8-post-Ubuntu-0ubuntu122.04) OpenJDK 64-Bit Server VM (build 11.0.16+8-post-Ubuntu-0ubuntu122.04, mixed mode, sharing)
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
$ sudo apt-get install tomcat9
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:
$ sudo nano /etc/default/tomcat9
JAVA_OPTS="-Djava.awt.headless=true -Xmx4g -XX:+UseConcMarkSweepGC -Dfile.encoding=UTF8"
JAVA_OPTS="${JAVA_OPTS} -Drs.configdir=/opt/reportserver"
If you use Java 11 or newer, but at the moment ReportServer needs Java 11, 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:
$ sudo nano /usr/share/tomcat9/bin/setenv.sh
JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.net=ALL-UNNAMED" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/jdk.internal.reflect=ALL-UNNAMED" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.lang.invoke=ALL-UNNAMED" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.util=ALL-UNNAMED" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS -Djavax.net.ssl.trustStoreType=JKS" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS -Dfile.encoding=UTF-8" JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS -Djava.awt.headless=true"
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:
$ sudo apt-get install authbind
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":
$ cd /etc/authbind/byport $ sudo touch 80 $ sudo chown tomcat:tomcat 80 $ sudo chmod u+x 80
Next step, modify systemctl to use AUTHBIND when starting the tomcat
$ sudo nano /lib/systemd/system/tomcat9.service change --> ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-start.sh to --> ExecStart=authbind --deep /usr/libexec/tomcat9/tomcat-start.sh
Finally, we need to change Tomcat's default connector configuration to listen on port 80. For this change the connector settings in server.xml.
$ sudo nano /var/lib/tomcat9/conf/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. Reload the systemd manager configuration (because of our ExecStart change) and restart Tomcat via
$ sudo systemctl daemon-reload $ sudo systemctl restart tomcat9
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
$ sudo systemctl stop tomcat9
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
$ 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 (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
$ 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 'SCRAM-SHA-256$4096:6nEpH9JVjNcBTGtPq4qcgA==$cMIGrF3ZoQZOD4A4qcapAYipQjaJUlxi0DldbWqMZKU=:ONrxkjQezRee0aSNWW9LtAnWA9CNRz0m1Pyqo9qAMO8=' 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/14/main/pg_hba.conf. Here look for a line containing
$ sudo nano /etc/postgresql/14/main/pg_hba.conf
local all all peer
and replace it by
local all all scram-sha-256
Which allows users that provide a valid password hash to connect. For the changes to take effect we need to restart the postgres service.
$ sudo systemctl restart postgresql
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.
$ sudo 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.
$ cd /var/lib/tomcat9/webapps/
$ sudo rm -r /var/lib/tomcat9/webapps/ROOT
Now unzip RS4.6.1-6098-2023-09-21-00-57-26-src-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.
$ sudo unzip /home/MYUSER/RS4.6.1-6098-2023-09-21-00-57-26-src-reportserver-ce.zip -d /var/lib/tomcat9/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.
$ sudo mkdir /opt/reportserver $ sudo mkdir /opt/reportserver/lib $ sudo 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
$ sudo cp /var/lib/tomcat9/webapps/WEB-INF/classes/persistence.properties.example /opt/reportserver/persistence.properties $ sudo cp /var/lib/tomcat9/webapps/WEB-INF/classes/reportserver.properties /opt/reportserver/reportserver.properties $ sudo cp /var/lib/tomcat9/webapps/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
$ sudo nano /opt/reportserver/persistence.properties
# Credentials hibernate.connection.username=reportserver hibernate.connection.password=reportserver # PostgreSQL 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.
$ sudo chown -R tomcat:tomcat /opt/reportserver
The same applies for tomcat webapps.
$ sudo chown -R tomcat:tomcat /var/lib/tomcat9/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:
psql -U reportserver -preportserver -d reportserver -a -f /var/lib/tomcat9/webapps/ddl/reportserver-RS4.6.1-6098-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 /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:
$ sudo nano /var/lib/tomcat9/conf/logging.properties
# 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.maxDays = 90
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 at an end. To test the installation, start tomcat and observe the output in ReportServer's log file.
$ sudo systemctl restart tomcat9
$ tail -f /var/lib/tomcat9/logs/reportserver.DATE.log
If all goes well you should see a message such as:
INFO [Thread-13] 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