Installing BellaDati on Tomcat 6.0

1. Download and extract BellaDati WAR Archive

Download the BellaDati WAR distribution as TAR/GZ archive from my.trgiman.eu 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 - belladati2_X.war.

2. 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 belladati2_X.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

Meaning of these parameters are described below:

3. Save configuration file WEB-INF/classes/conf/application.properties and update the WAR archive. Linux unzip command looks like:

zip -d belladati2_X.war WEB-INF/classes/conf/application.properties
zip -u belladati2_X.war WEB-INF/classes/conf/application.properties

3. 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:

• Copy the PostgreSQL JDBC Driver to Tomcat

4. Configure Tomcat

4.1 Set JAVA environment

Make sure the $TOMCAT_HOME/conf/tomcat6.conf file points to right version of JAVA:

JAVA_HOME="/opt/java64"

4.2 Configure Tomcat's context

A BellaDati 'context' now needs to be set up in Tomcat. To do this:

1. Create the directory structure conf/Catalina/localhost/ within your Tomcat installation directory.
2. Create the belladati.xml file and copy it to{{conf/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>
   

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).

4.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.

4.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 -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"

The other way is to edit the $TOMCAT_HOME/conf/tomcat6.conf file:

JAVA_OPTS="-Dmail.mime.decodeparameters=true -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"

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 -Xms1024m -Xmx2048m -XX:MaxPermSize=512m\
  

If Tomcat is installed and running as a service:

1. Right-click Tomcat's system tray icon and select 'Configure' from the resulting popup menu, which opens the 'Apache Tomcat 6 Properties' dialog box.
2. In this dialog box, click on the 'Java' tab and specify the following values:

   Field	Value
   Java Options (append to the existing value)	-Dmail.mime.decodeparameters=true
   Initial memory pool	1024
   Maximum memory pool	2048

For other environments and more information on memory settings, see System Requirements.

4.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.

5. 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.

6. Run the Setup Wizard

You should now see the Setup Wizard, which will take you through the BellaDati's setup procedure, including a configuration step for your database connection.