Before You Begin
Please read the following important notes before you begin installing BellaDati on Tomcat:
- Make sure you have the right version of Java. See Installing Java for more details.
- Deploying multiple BellaDati WAR application in a single Tomcat container is not supported. We do not test this configuration and updating any of the applications (even for point releases) is likely to break it.
- We recommend not deploying any other applications in the same Tomcat container that runs BellaDati, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib sub-directory. Multiple applications in a container can impact stability as a crash in one application could make the entire container inaccessible. Additionally, in order to update or reconfigure any of the applications, you'll need to restart the whole container.
1. Setup data warehouse
Please follow the instructions on the Setting up the PostgreSQL Database page.
2. Download and extract BellaDati WAR Archive
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 -
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.
3. Configure BellaDati WAR
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.
4. Configure Tomcat
4.1 Configure Tomcat Context
A BellaDati context needs to be set up in Tomcat. To do this:
- Create the directory structure
conf/Catalina/localhost/within your Tomcat installation directory if it doesn't already exist.
belladati.xmlfile and copy it to
conf/Catalina/localhostsubdirectory of your Tomcat installation directory (created in the previous step).
- Update the docBase attribute in the first line as well as url, username and password in lines 5 and 6 to match your system configuration.
Here is an example file.
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.
4.2 Set JAVA Environment
4.2.1 For Linux/Solaris
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:
Make sure this variable is automatically set after system starts (append it to the
You can also specify it in the file
$TOMCAT_HOME/bin/setenv.sh file (or create this file if it does not exist):
4.2.2 For Windows
Windows users can specify the environment parameters in the Environment Variables window.
4.3 Set Tomcat Home Directory Permissions
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.
4.4 Configure Memory Settings in Tomcat
Tomcat memory settings need to be modified to avoid the following issue:
- BellaDati requires more memory than what Tomcat provides by default. This may lead to
OutOfMemoryerrors when running BellaDati if these memory settings are not increased.
To prevent this issue, follow the instructions below.
$TOMCAT_HOME/bin/setenv.sh file (or create this file if it does not exist) and add the following:
Alternatively, you can edit the
If Tomcat is not installed as a service:
$TOMCAT_HOME/bin/setenv.batfile (or create this file if it does not exist) and add the following:
If Tomcat is installed and running as a service:
- Right-click Tomcat's system tray icon and select Configure from the resulting popup menu, which opens the Apache Tomcat Properties dialog box.
In this dialog box, click on the Java tab and specify the following values (depending on available system memory):
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.
4.5 Modify Tomcat's
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
You should modify this element by specifying the
5. Start or Restart Tomcat
BellaDati is now ready to run in Tomcat.
Run as Service
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