Thorsten Kamann

Do you need a tracking system to track your requirements, issues and tasks? So you can look around – and maybe – your eyes keep on the famous Atlassian Jira. At first Jira is a bug tracker. You can create, manage and close bugs with Jira. But there is more:

• Bug tracking
• Manage your projects with Jira
• Create your own workflows for tasks and issues
• Powerful Reporting
• Extensible with plugins

You can download a standalone version bundled with a Tomcat 5.5. With this download you can start directly. But typically you already have an infrastructure. For such scenarios it’s much better to use the WAR/EAR-Edition of Jira.

This article describes the installation with Apache Tomcat 6 on a Linux box. If you plan to do this on windows you only must change paths and – of course – shell against Windows Batch.

Install Tomcat

You can get Tomcat from the official projectsite. You get a ZIP- or TAR.GZ-Archive. Now you can extract the archive and do a testrun by browsing to http://localhost:8080.

If you want to deploy Jira to this instance of Tomcat you need some additional Jars not included in the web archive you will later deploy. You can get the additional jars from here. Create a new directory in you Tomcat installation directory: ext/jira/lib. Copy all Jars into this directory.

Finally you must Tomcat announce the new libraries. For this you edit the conf/catalina-properties by changing the common.loader property (the property is a single line; here are only breaks due to layout reasons):

common.loader=${catalina.base}/ext/jira/lib/*.jar,
       ${catalina.base}/lib,${catalina.base}/lib/*.jar,
       ${catalina.home}/lib,${catalina.home}/lib/*.jar

Jira needs a lot of memory. Sometimes Jira needs more than Tomcat can deliver. So you should add mor memory to Tomcat. This and some other properties you should set, before the next restart of Tomcat.

export JAVA_OPTS="-XX:MaxPermSize=256m -Xmx1024m

       -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true

       -Dmail.mime.decodeparameters=true"

The first both options gives more memory to Tomcat. The last both options are needed by Jira. The 3rd is needed to avoid a memory leak of Tomcat and the last option is needed to send attachments with another encoding than the default encoding.

You must restart Tomcat to activate your changes.

Installing Jira

The archive you get as WAR-Edition contains the binaries you need to deploy it to Tomcat. But the archive contains the binaries for the EAR-Edition too. And for older Tomcats and Resin and so on… Additionally this archive enables you to do customizations like configurations, templates,  additionally sources to compile and JARs. After you downloaded the archive and extract it you must change one property pointing to the data directory used by Jira by editing edit-webapp/WEB-INF/classes/jira-application.properties.

Now you can build the web archive you can use to deploy to Tomcat. In the root directory the is a build script (build.sh and build.bat) you can use to archieve this. After some time the script is ready and a new directory is created: dist-tomcat/tomcat-6. There you find the web archive and the deployment descriptor for Tomcat 6. You can simple copy this descriptor to <<tomcat-install-directory>>/conf/Catalina/localhost. Tomcat will install Jira and you can browse to http://localhost:8080/jira.

Customizing the web archive

You can overwrite every file the web archive contains. The can archieved vy copying the file into the edit-webapp directory. Please remember to create the same directory structure. For instance if you want to customize the file webapp/WEB-INF/classes/log4j.properties you must copy it to edit-webapp/WEB-INF/classes/log4j.properties. After running the build script you can reload the webapplication with Tomcat’s Manager or simply restarting Tomcat.

Speed up the build script

The build script create web archive for all tomcat versions and a generic web archive for other servlet containers. If you plan to deploy to Tomcat 6 it would be enough to build the archive for Tomcat 6. To do this you must only change the target war in the build.xml:

<target name="war" depends="clean, compile" description="Packages the WAR file">
  <!-- Build the war file -->
  <jar jarfile="${dist-generic}/${name}-${version}.war">
    <fileset dir="${build.war}"/>
  </jar>
  <!-- Tomcat-6-specific .war -->
  <jar jarfile="${dist-tomcat}/tomcat-6/${name}-${version}.war">
    <fileset dir="${build.war}">
      <exclude name="WEB-INF/lib/commons-logging*.jar"/>
      <exclude name="WEB-INF/lib/log4j-*.jar"/>
    </fileset>
  </jar>
  <copy file="etc/tomcat-6-jira.xml" tofile="${dist-tomcat}/tomcat-6/jira.xml">
    <filterset>
      <filter token="JIRA_HOME" value="${basedir}"/>
      <filter token="JIRA_WEBAPP" value="${basedir}${slash}${dist-tomcat}${slash}tomcat-6${slash}${name}-${version}.war"/>
    </filterset>
  </copy>
  <echo>
--------------------------------------------------
Deployable WARs generated:
TOMCAT:  ${basedir}${slash}${dist-tomcat}${slash}${name}-${version}.war
GENERIC: ${basedir}${slash}${dist-generic}${slash}${name}-${version}.war
See http://www.atlassian.com/software/jira/docs/latest/servers/ for install instructions
--------------------------------------------------
  </echo>
</target>

Conclusion

Now your Jira is up and running. The next steps are configuration of projects and users, but this isn’t the focus of this article.