This section describes how to install JIRA on Tomcat 5.5, a popular open-source server from the Apache Jakarta project. Tomcat can be downloaded the Apache site. Note
The JIRA ‘Standalone‘ download is JIRA preconfigured with a copy of Tomcat 5.5.9. If you have JIRA Standalone, you don‘t need to follow these docs.
Warning
Please use Tomcat 5.5.15 or higher. All versions of Tomcat effectively leak memory by caching JSPs, which can result in OutOfMemoryErrors if large pages JIRA (eg. RSS or Excel) are requested. In 5.5.15+ there is a flag you should set to disable this caching.
1. Unpack JIRAUnzip the JIRA WAR (Webapp ARchive) distribution. A new directory containing JIRA will be created, hereafter referred to as $JIRA_HOME 2. Configure JIRAJIRA needs to be told what type of database you‘ll be using. The database is specified in $JIRA_HOME/edit-webapp/WEB-INF/classes/entityengine.xml. Locate the <datasource> tag near the bottom, and change the field-type-name attribute value: <datasource name="defaultDS" field-type-name="hsql" schema-name="PUBLIC" helper-class="org.ofbiz.core.entity.GenericHelperDAO" check-on-start="true" use-foreign-keys="false" use-foreign-key-indices="false" check-fks-on-start="false" check-fk-indices-on-start="false" add-missing-on-start="true"> <jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS" /> </datasource> Possible values include cloudscape, db2, firebird, hsql, mckoidb, mysql, mssql, oracle, postgres, postgres72, sapdb, and sybase For Postgres 7.3+ and DB2 you also need to set a schema-name attribute (see the Postgres and DB2 pages). Also in entityengine.xml, ensure the <transaction-factory>...</transaction-factory> tag contains: <transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory"> <user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/> <transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/env/UserTransaction"/> </transaction-factory> More details on JIRA‘s database access layer are available on the EntityEngine configuration page. 3. Build JIRANow build JIRA by typing build (Windows) or ./build.sh (Unix) on the command line in the $JIRA_HOME directory. This will produce the deployable WAR file in the $JIRA_HOME/dist-tomcat directory. 4. Update Tomcat LibrariesTomcat does not come with some libraries required to run JIRA. To fix this, download jira-jars-tomcat5.zip (1.2Mb), and copy the contained jars to Tomcat‘s common/lib/ directory. 5. Configure TomcatA JIRA ‘context‘ now needs to be set up in Tomcat. To do this:
The paths (denoted as path/to/) will be correct by default, assuming you want to deploy the .war from the dist-tomcat/ directory. Note
If you are not using hsqldb, make sure you comment out the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis params, or JIRA will run slower than normal.
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:\yourdb\tomcatdb). N.B. the last part of the path is the name of the database and is not a directory. The above example assumes you are using hsql (an in-memory database - a good choice for a first attempt). Here is an example using MySQL: <Context path="/jira" docBase="path/to/atlassian-jira-3.7.2.war"> <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource" username="jirauser" password="mypassword" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/jiradb?autoReconnect=true"/> <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction" factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/> <Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/></Context> Notice the lack of minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis parameters - those should only be used with hsql. If using a different database than hsql, remember to update the field-type-name (see above) copy the JDBC driver jar to common/lib/ (see the database configuration guide). Modify Tomcat server.xmlIn order for JIRA to correctly display internationalized characters in user and group names you need to modify your Tomcat distributions conf/server.xml file. You need to set the property useBodyEncodingForURI="true" within the connector definition for your http protocol. The connector block should look very much like this: <Connector port="8080" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true"/> You should modify the block to contain the addition of the useBodyEncodingForURI property: <Connector port="8080" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" useBodyEncodingForURI="true"/> Note
Because you must define this property in at the connector level this setting will effect all web-applications you have deployed under the connector. This should not adversely effect the other web-applications but please be aware of this. JIRA will run fine without this property set but you will run into issues if a user or group is created which contains international characters. It is best to set this property to true.
Fix Tomcat memory settingsNote
This only works for Tomcat 5.5.15 and higher!
Tomcat has a memory leak where large JSP page requests can fill up memory. To avoid this, edit Tomcat‘s bin/setenv.sh and set: export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true" or when installed as a Windows service, run: tomcat5 //US//JIRA ++JvmOptions="-Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true For other environments, and for more info on memory settings, see the memory settings page. Start TomcatJIRA should now be ready to run in Tomcat. To start using JIRA, first start (or restart) the Tomcat server with Tomcat‘s bin/startup.(sh|bat) scripts, and point your browser to http://localhost:8080/jira You should now see the Setup Wizard, which will take you through the brief setup procedure. TroubleshootingIt is easy to make a mistake in this process, and even more so if you are trying to connect to a database other than hsqldb. First, check that you have followed the process described above:
If you‘re stuck, please raise a support request, and attach your logs, configuration files, plus anything else relevant, and we‘ll get back to you as soon as possible. If you have a general question, please try the jira-user mailing list (which Atlassian staff monitor). User-contributed notesHave experiences to share with Tomcat 5.5.x and JIRA? We welcome your thoughts. Please see the user-contributed Tomcat 5.5.x notes. |
|