This guide describes how to install BellaDati WAR on Tomcat 6.0 or Tomcat 7.0. Tomcat container can be downloaded from the Apache site.
The BellaDati WAR is plain BellaDati application packaged in WAR archive. It must be deployed into an existing application server and needs to be connected to data warehouse running on existing database server. If you have BellaDati virtual appliance, follow the Installing BellaDati Virtual Appliance guide instead of the instructions below.
Before You Begin
Please read the following important notes before you begin installing BellaDati on Tomcat 6.0:
- Make sure you have the right version of JAVA. See Installing Java for more details.
- Tomcat 6.0.24 contains a critical bug. Please use 6.0.32 instead.
- Deploying multiple BellaDati WAR application in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it.
- Finally, 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 subdirectory. There are also a number of practical reasons why we do not support deploying multiple applications in a single Tomcat container. Firstly, you must shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in that Tomcat container will be inaccessible.
1. Setup data warehouse
Please follow the instructions on Setup BellaDati Data Warehouse page.
2. Download and extract BellaDati WAR Archive
Download the BellaDati WAR distribution as TAR/GZ archive from BellaDati download page and extract its content using a tool such as 7-zip for Windows or Linux's/GNU tar tools. TAR/GZ archive contains single file - 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 filenames better.
3. Configure BellaDati WAR
You have successfuly downloaded and extracted the BellaDati WAR distribution as described in the previous step. BellaDati WAR configuration consists of unpacking and editing a configuration file placed inside the WAR archive. To do it, please follow this easy steps:
1. Extract application.properties
file from WAR using a tool such as 7-zip for Windows or Linux's unzip tool.
unzip belladati.war WEB-INF/classes/conf/application.properties
2. Edit extracted file WEB-INF/classes/conf/application.properties
. The default configuration should look like:
# APPLICATION properties application.url=http://localhost:8080 application.production-mode=true application.secure-mode=false # JDBC properties jdbc.resource=java:/comp/env/jdbc/belladati_db # SMTP properties smtp.server.address=localhost smtp.server.username= smtp.server.password= # EMAIL properties email.sender=support@belladati.com email.footer=TRGIMAN s.r.o. # OpenID properties application.registration=http://www.belladati.com/try application.registration.openid= # Google analytics properties application.google-site-verification= application.google-analytics-account= application.google-analytics-account.mercato= # Lucene index dir lucene.indexes=/tmp/indexes
Parameters are explained in BellaDati WAR Configuration Overview.
3. Save configuration file WEB-INF/classes/conf/application.properties
and update the WAR archive. Linux unzip command looks like:
zip -d belladati.war WEB-INF/classes/conf/application.properties zip -u belladati.war WEB-INF/classes/conf/application.properties
4. Update Your Tomcat Installation's Libraries for BellaDati
Your Tomcat installation requires an appropriate JDBC driver to allow BellaDati to communicate with the database. To add this JDBC driver to Tomcat, refer to the appropriate instructions:
5. Configure Tomcat
5.1 Set JAVA environment
If you have installed the Tomcat Windows Service, you can skip this step.
5.1.1 For linux/solaris
Before you start Tomcat, make sure you have configured the JAVA_HOME variable, which points to the installed JAVA. You can do it in this way:
$ export JAVA_HOME=/path/to/jdk
Do not forget to ensure, that this variable is automatically set after system starts (append it to the .profile
).
5.1.2 For Windows
Windows users can specify the environment parameters in the Environment settings window.
You can also specify it in the file $TOMCAT_HOME/conf/tomcat6.conf
file. :
JAVA_HOME="/opt/java64"
5.2 Configure Tomcat's context
A BellaDati 'context' now needs to be set up in Tomcat. To do this:
- Create the directory structure
conf/Catalina/localhost/
within your Tomcat installation directory. - Create the
belladati.xml
file and copy it toconf/Catalina/localhost
subdirectory of your Tomcat installation directory (created in the previous step).<Context path="/belladati" docBase="path/to/belladati-2.x.war" debug="0" useHttpOnly="true"> <Resource name="jdbc/belladati_db" auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://db_host:5432/belladati_db" username="belladati_dbuser" password="password" maxActive="20" maxIdle="10" maxWait="-1"/> </Context>
Here is a 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. C:\path\to\belladati-2.x.war
).
5.3 Set Tomcat home directory permissions
By default BellaDati is creating several directories within the Tomcat home folder. Tomcat should run under user, which has read/write access to this directory.
5.4 Fix Memory settings in Tomcat
Memory settings need to be modified in Tomcat to avoid the following issues:
- BellaDati requires more memory than what Tomcat provides by default. This may lead to
OutOfMemory
errors when running BelladDati if these memory settings are not increased.
To prevent these issues, follow the appropriate instructions for your operating system below.
For Linux/Solaris
Edit Tomcat's bin/setenv.sh
file (or create this file if it does not exist) and add the following to this file:
export CATALINA_OPTS="$CATALINA_OPTS\ -Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"
The other way is to edit the $TOMCAT_HOME/conf/tomcatX.conf
or /etc/default/tomcatX.conf
file:
JAVA_OPTS="-Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"
Please note, that the value 2048MB
for -Xmx (max heap size) is dedicated for evaluation purposes only. Please refer to JVM parameters chapter.
For Windows
If Tomcat is not installed as a service:
- Edit Tomcat's
bin/setenv.bat
file (or create this file if it does not exist) and add the following to this file:
set CATALINA_OPTS=%CATALINA_OPTS% -Dmail.mime.decodeparameters=true -Dfile.encoding=UTF-8 -Xms1024m -Xmx2048m -XX:MaxPermSize=512m\
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 6 Properties' dialog box.
- 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)
-XX:MaxPermSize=512m -Dfile.encoding=UTF-8 -Dmail.mime.decodeparameters=true
Initial memory pool
256 MB
Maximum memory pool
2048 MB
For other environments and more information on memory settings, see System Requirements.
5.5 Modify Tomcat's server.xml
In order for BellaDati to correctly display internationalised characters in user and group names, you need to modify the 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:
- Since this property must be specified at the connector level for your application server, this setting will effect all other web applications deployed to the same application server installation running BellaDati. While this setting should not adversely effect these other web applications, you should be aware of this point.
- BellaDati will run fine without this property set. However, you will run into issues if a user or group is created which contains international characters. Hence, it is recommended that you set this property.
6. Start Tomcat
(Only required if Tomcat is not running as a service.)
BellaDati should now be ready to run in Tomcat. To start up BellaDati, start (or restart) the Tomcat server with Tomcat's bin/startup.sh
or bin/startup.bat
scripts.
7. Run the Setup Wizard
Point your browser to http://localhost:8080/belladati
You should now see the Setup Wizard, which will take you through the BellaDati's setup procedure.