Installing BellaDati on Tomcat 6.0

The BellaDati virtual appliance distribution is BellaDati preconfigured with a copy of GlassFish application server and PostgreSQL database. 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 JIRA on Tomcat 6.0:

• 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 JIRA, 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. Download BellaDati WAR Archive

Download the BellaDati WAR distribution archive from my.trgiman.eu and extract its contents using a tool such as 7-zip for Windows or Linux's unzip or GNU tar tools.

Avoid using Windows' built-in file extraction tool! This tool silently fails to extract files with long names (see JRA-2153). Other users have also reported problems with WinRAR.

Avoid using Solaris' default tar utility! Please use GNU tar on this operating system to extract JIRA, as GNU tar handles long filenames better.

2. Configure BellaDati WAR

3. Update Your Tomcat Installation's Libraries for BellaDati

3.1 JDBC Drivers

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 JIRA's Context in Tomcat

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

5. Modify Tomcat's server.xml to Handle Internationalised Characters Correctly

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. 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 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% -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -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:
   Unable to render embedded object: File (tomcat6a.JPG) not found.
2. In this dialog box, click on the 'Java' tab and specify the following values:

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

   Your configuration should be similar to the screenshot below:
   Unable to render embedded object: File (tomcat6b.JPG) not found.

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 -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Dmail.mime.decodeparameters=true -Xms1024m -Xmx2048m -XX:MaxPermSize=512m" 

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

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

9. Run the Setup Wizard

Point your browser to {{

}}

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.

Troubleshooting

It is easy to make a mistake in this process. First, check that you have followed the process described above:

• Have you have made changes to edit-webapp/WEB-INF/classes/entityengine.xml in your [JIRA Installation Directory] ([step 2] above) and re-run the build script ([step 3] above), but your entityengine.xml changes were not picked up? If so, delete the webapps/jira subdirectory of your Tomcat installation directory and then restart JIRA. (In some circumstances, Tomcat does not correctly re-expand the web application.)
• If you are using an external database, did you copy the correct JDBC driver jar file to the lib subdirectory of your Tomcat installation directory? (Refer to [step 4] above.)
• Have you updated your Tomcat installation's libraries for JIRA by copying across the additional jar files downloaded in [step 4] above? Check if objectweb-datasource-x.y.z.jar present in the lib subdirectory of Tomcat's installation directory.
• Is the path to your built .war file within conf/Catalina/localhost/jira.xml of your Tomcat installation directory correct? (Refer to [step 5] above.)
• Have you copied your built .war file to Tomcat's webapps directory? This is almost guaranteed to cause problems - please move this .war file elsewhere and delete any JIRA subdirectories created in Tomcat's webapps directory which Tomcat may have created (after Tomcat is initially started).
• Have you configured JIRA's context and other custom settings centrally in Tomcat's conf/server.xml file instead of the conf/Catalina/localhost/jira.xml file of your Tomcat installation directory? Although this is fine, be sure that you do not also have a conf/Catalina/localhost/jira.xml file present.
• The log files are usually vital to debugging problems. On Windows, these will appear in the console window that loads when running startup.bat, or in one of the log files in Tomcat's logs directory. On Linux/Solaris, logs will appear in a log file in logs, usually logs/* (not just logs/catalina.out). Check the log file for errors after startup.
• If you experience high memory usage / memory leaks (e.g. OutOfMemoryError), you may wish to set the system property -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true in the setenv.sh / setenv.bat file. For more information please see JRA-10145. (Refer to [step 7] above.)
• If the connection to your database is dropping out (in particular with MySQL), you will need to set up Tomcat to [survive connection closures].
• Error formatting macro: include: java.lang.IllegalArgumentException: No link could be created for 'BDTECHDOC:__WAR_warning_editing_files'.

If you are stuck, please raise a support request. In your request, please attach your logs, configuration files, plus anything else relevant and we will get back to you as soon as possible.