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.- 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 3.1.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, RS3.1.1-6020-reportserver.zip denotes ReportServer version 3.1.1 build number 6020.
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/RS3.1.1-6020-2020-01-28-16-18-55-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"
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