Installing BellaDati on Ubuntu as Tomcat service

Before You Begin

You should have ready vanilla installation of Ubuntu Focal 20.04 LTS available on physical HW or some type of container (AWS, Linux container,Docker,VMWare etc.). This guide expects, that any type of firewall is not applied and or communication to installed DWH and Servlet Container is allowed on the OS level. For production make sure that OS environment as well as servlet container is secured using SSL etc. This guide is not focused on security settings.

1. Setup Postgresql 10 data warehouse

Decide if you will install Postgresql on the same host as Tomcat with BellaDati or Postgresql will be running on different host than Tomcat with Belladati

1. Follow steps at https://www.postgresql.org/download/linux/ubuntu/ to install postgresql-10 package
2. Please follow the instructions on the Setting up the PostgreSQL Database page.

2. Install OpenJDK-8-jre apt package

1. Become root user by sudo su if you are not one
2. Run apt-get update if host differs from host on which you have installed Postgresql
3. Run apt-get install openjdk-8-jre and confirm installation of all dependant packages
   
4. Run apt-cache policy openjdk-8-jre to see exact version of JRE installed

3. Install Tomcat9 apt package

3.1 Installation

1. Become root user by sudo su if you are not one
2. Run apt-get install tomcat9 and confirm installation of all dependant packages
3. Run apt-cache policy tomcat9 to see exact version of tomcat9 installed
4. Run systemctl status tomcat9 to see if tomcat9 is running or not (it should be turned off)
5. User tomcat was created and tomcat9 related service configurations were created
6. tomcat9 service will later run as tomcat user
7. tomcat9 will search for typical JRE paths as can be read in /etc/default/tomcat9 file or you can set direct path to installed JRE from within this file (not necessary in our case)

3.2 Tomcat JAVA_OPTS configuration

Since Tomcat is installed as apt package on Ubuntu. Configuration for Java System Properties used by Tomcat and therefore by belladati application has to be done as following

1. As  root run vi /etc/default/tomcat9
2. Add following Java System Properties to JAVA_OPTS existing parameters. If added, these parameters will overwrite default application.properties within belladati.war

3. Java System Properties to add to JAVA_OPTS are:

   Property with value	Note
   -Djdbc.password=password	password to belladati_db in Postgres.For production use your own values.
   -Djdbc.username=belladati_dbuser	username to belladati_db in Postgres.For production use your own values.
   -Djdbc.url=jdbc:postgresql://localhost:5432/belladati_db	For production you can use your own values.
   -Dbelladati.application.homeDir=/opt/belladati	For production you can use your own values.
   -Dlucene.indexes=/opt/belladati/indexes	BellaDati search engine will store indexes of reports,users etc. in this directory
   -Dlogs.location=/opt/belladati/logs	For production you can use your own values.
   -Dmail.mime.decodeparameters=true
   -Dfile.encoding=UTF-8
   -Djava.io.tmpdir=/tmp
   -XX:+UseG1GC	Type of garbage collector algorithm.Specify in case Java 8 is used. Java above 8 is using it by default.

   Since Belladati version 2.7.14 there is no special configuration change needed in application.properties file in belladati.war, however, there are several advanced settings (e.g. enforcing the SSL), which are configurable in application.properties only.

   Configuration settings are explained in detail in the BellaDati WAR Configuration Overview.

3.3 Tomcat service unit configuration

1. As root create directory mkdir /opt/belladati (belladati.war will be unziped into this directory and used by Tomcat9)
2. As root create directory mkdir /opt/belladati/indexes (belladati will store search engine results in this directory)
3. As root create directory mkdir /opt/belladati/logs (belladati login engine will store logs into this directory)
4. Change ownership of directory by  chown -R tomcat:tomcat /opt/belladati
5. As root run vi /etc/systemd/system/multi-user.target.wants/tomcat9.service
6. At the end of #Security section add ReadWritePaths=/opt/belladati/  (now tomcat9 service running as tomcat user can read and write to /opt/belladati and same is allowed for its Context).Let's setup Context in next steps.

3.4 Tomcat Context configuration

Context container in Tomcat processes requests to web applications. Let' setup belladati.war web application as Context for Tomcat. By default Tomcat still keeps the root Context "".Context for belladati web application will be /belladati. Since Tomcat will use autodeploy feature. Therefore Context is named according of file being deployed. In this case belladati.war

1. Specify from where Tomcat should deploy the belladati.war

2. $CATALINA_BASE points to configuration of single tomcat instance. As user tomcat (sudo -u tomcat) create new file belladati.xml by vi /conf/Catalina/localhost/belladati.xml   and add Context configuration below into the belladati.xml

   <Context docBase="opt/belladati/belladati.war" debug="0" useHttpOnly="true">
        
   </Context>
   

Since version 2.7.14 there is no special configuration change needed, however, there are several advanced settings (e.g. enforcing the SSL), which are configurable in application.properties only.

3.5 Modify Tomcat's server.xml

In order for BellaDati to correctly display internationalized characters in user and group names, you need to modify the $TOMCAT_HOME/conf/server.xml file in your Tomcat installation directory by specifying the URIEncoding="UTF-8" property within the connector definition for your HTTP protocol.

The connector definition is specified by the following element in your server.xml file:

<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"/>

You should modify this element by specifying the URIEncoding="UTF-8" attribute:

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

3.6 Modify Tomcat's context.xml

In order for Tomcat to be able to cache web resources of BellaDati a default value for the cache size must be modified. Modify the $TOMCAT_HOME/conf/context.xml file in your Tomcat installation directory by adding following line:

<Resources cacheMaxSize="51200" />

4. Download belladati.war

These steps will place belladati.war into /opt/belladati. From that directory Tomcat will deploy belladati.war by using autoDeploy feature into it's directory /var/lib/tomcat9/webapps, where it will create directory named after belladati.war,  belladati

1. download BellaDati-2_9_22.war.zip (your BellaDati version may differ) from My.BellaDati.com portal into /opt/belladati
2. run sudo -u tomcat gunzip -S .zip BellaDati-2_9_22.war.zip
3. run sudo -u tomcat mv BellaDati-2_9_22.war belladati.war

5. Disable automatic updates in Ubuntu Focal 20.04

To prevent Ubuntu to automatically update and upgrade Tomcat,Java,Postgresql packages edit file below as root (if Postgres is installed on different host, apply steps below also on the other host)

/etc/apt/apt.conf.d/20auto-upgrades

and replace existing content with

PT::Periodic::Update-Package-Lists "0";
APT::Periodic::Download-Upgradeable-Packages "0";
APT::Periodic::AutocleanInterval "0";
APT::Periodic::Unattended-Upgrade "1";

6. Start and control tomcat service

BellaDati is now ready to run in Tomcat.While Tomcat will run as Ubuntu service under user tomcat.

Use commands below to control the service.Remember, that data warehouse of belladati (Postgresql must be up as well):

1.  systemctl status tomcat9 to see the status of service
2.  systemctl start tomcat9 to start the service
3.  systemctl stop tomcat9 to stop the service

7. Run the Setup Wizard

While tomcat9 service is running and systemctl status tomcat9 is showing that belladati was successfuly deployed you can access BellaDati via webbrowser.

Point your browser to http://localhost:8080/belladati. This starts the Setup Wizard, which will take you through BellaDati's setup procedure.