This guide describes how to install BellaDati WAR on Tomcat. BellaDati supports Tomcat 8.5.x and Tomcat 9.0.x versions. We recommend to use Tomcat 9.0. |
Tip for Windows users: |
The BellaDati WAR file is the BellaDati application packaged in a WAR archive. It must be deployed into an existing application server and needs to be connected to a data warehouse running on an existing database server. |
Please read the following important notes before you begin installing BellaDati on Tomcat:
Please follow the instructions on the Setting up the PostgreSQL Database page.
Download the BellaDati WAR distribution as a ZIP archive from the BellaDati download page and extract its content using a tool such as 7-Zip for Windows or Linux's GNU tar tools. Only one of the files in the ZIP archive is used for this setup - belladati.war
.
Avoid using Windows' built-in file extraction tool! This tool silently fails to extract files with long names. Other users have also reported problems with WinRAR.
Avoid using Solaris' default tar utility! Please use GNU tar on this operating system to extract BellaDati, as GNU tar handles long file names better.
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.
Configuration settings are explained in detail in the BellaDati WAR Configuration Overview. |
A BellaDati context needs to be set up in Tomcat. To do this:
conf/Catalina/localhost/
within your Tomcat installation directory if it doesn't already exist.Create the belladati.xml
file and copy it to conf/Catalina/localhost
subdirectory of your Tomcat installation directory (created in the previous step).
<Context docBase="path/to/belladati.war" debug="0" useHttpOnly="true"> <Parameter name="tapestry.context-path" value="/belladati" override="false"/> </Context> |
If you are installing in Windows, make sure that the paths you specify for the location of the WAR file and database are full paths with drive letters (e.g. C:\path\to\belladati.war
).
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 | You need use your own values for production. |
If you have installed the Tomcat Windows Service, you can skip this step. |
Before you start Tomcat, make sure you have configured the JAVA_HOME variable, which points to the installed Java SDK. You can do it in this way:
$ export JAVA_HOME=/path/to/jdk |
Make sure this variable is automatically set after system starts (append it to the .profile
).
You can also specify it in the file $TOMCAT_HOME/bin/setenv.sh
file (or create this file if it does not exist):
JAVA_HOME="/path/to/jdk" |
Windows users can specify the environment parameters in the Environment Variables window.
By default BellaDati is creating several directories within the Tomcat home folder. To allow this, Tomcat needs to run as a user with read and write access to this directory.
Tomcat memory settings need to be modified to avoid the following issue:
OutOfMemory
errors when running BellaDati if these memory settings are not increased.To prevent this issue, follow the instructions below.
Please note that the value |
Edit $TOMCAT_HOME/bin/setenv.sh
file (or create this file if it does not exist) and add the following:
export CATALINA_OPTS="$CATALINA_OPTS -Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -XX:+UseG1GC -Xms1024m -Xmx2048m" |
Alternatively, you can edit the $TOMCAT_HOME/conf/tomcatX.conf
or /etc/default/tomcatX.conf
file:
JAVA_OPTS="-Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -XX:+UseG1GC -Xms1024m -Xmx2048m" |
If you are running 32 bit JVM on Windows, you can use max 1344MB (-Xmx1344) |
If Tomcat is not installed as a service:
Edit $TOMCAT_HOME/bin/setenv.bat
file (or create this file if it does not exist) and add the following:
set CATALINA_OPTS=%CATALINA_OPTS% -Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -XX:+UseG1GC -Xms1024m -Xmx2048m |
If Tomcat is installed and running as a service:
In this dialog box, click on the Java tab and specify the following values (depending on available system memory):
Field | Value | |
---|---|---|
Java Options (append to the existing value) |
| |
Initial memory pool |
| |
Maximum memory pool |
|
For other environments and more information on memory settings, see the System Requirements.
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"/> |
Please Note:
|
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" /> |
To be able to use Tomcat's bin/shutdown.sh
or bin/shutdown.bat
file to properly shutdown the Tomcat, a path to a file which will contain PID of started Tomcat needs to be set in CATALINA_PID
environment variable.
Edit $TOMCAT_HOME/bin/setenv.sh
file (or create this file if it does not exist) and add the following:
export CATALINA_PID=<absolute-path-to-pid-file> |
Edit $TOMCAT_HOME/bin/setenv.bat
file (or create this file if it does not exist) and add the following:
set CATALINA_PID=<absolute-path-to-pid-file> |
The default location for logs generated by BellaDati (see Configure logging for more details) is relative to the exploded belladati.war which is not suitable for long term storage.
To change the logs directory, add a new JVM option -Dlogs.location=<location>, where <location> is the desired absolute path to the parent directory in which logs will be stored, to your Tomcat (see section 4.4 for more details on how to do it).
BellaDati is now ready to run in Tomcat.
Start the Tomcat service used for Belladati. Restart it if it's already running.
If Tomcat is not running as a service, start (or restart) the Tomcat server with Tomcat's bin/startup.sh
or bin/startup.bat
scripts.
If Tomcat is not running as a service, you can stop the Tomcat server with Tomcat's bin/shutdown.sh
or bin/shutdown.bat
scripts if you set a CATALINA_PID
environment variable with the path to a file containing PID of the running Tomcat.
Point your browser to http://localhost:8080/belladati
. This starts the Setup Wizard, which will take you through BellaDati's setup procedure.