This page last changed on Jun 08, 2009 by rosie@atlassian.com.

This page has general notes on installing JIRA on Apache Geronimo.

Geronimo is an unsupported environment
Geronimo is an unsupported environment. Please note that these instructions have only been followed on Geronimo 2.1.3 bundled with Tomcat 6 using JIRA 3.13.2. Other versions of Geronimo/JIRA may or may not work.

1. Unpack JIRA

Download and unzip JIRA (but not with XP's unzipper nor the default tar utility on Solaris). Ensure that you download the WAR/EAR version, not the Standalone version that is recommended on the Downloads page.

Avoid the Windows XP built-in unzip tool! The built-in unzip tool in Windows XP is broken — it silently fails to extract files with long names (see JRA-2153 ). Other users have also reported problems using WinRAR. Please use another tool like WinZIP to unpack JIRA.
Avoid the Solaris default tar utility! On Solaris, please use GNU tar to unpack JIRA in order to handle long filenames. Do not use the Solaris default tar utility.

A new directory containing JIRA will be created, hereafter referred to as $JIRA_INSTALL.

If you are using Linux/UNIX: A dedicated user should be created to run JIRA, as JIRA runs as the user it is invoked under and therefore can potentially be abused. Here is an example of how to create a dedicated user to run JIRA in Linux:
$ sudo /usr/sbin/useradd --create-home --home-dir /usr/local/jira --shell /bin/bash jira

2. Configure JIRA

Create geronimo-web.xml

Geronimo requires a geronimo-web.xml deployment descriptor in order to deploy WAR applications. Create a new file $JIRA_INSTALL/webapp/WEB-INF/geronimo-web.xml and add the following:

geronimo-web.xml
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
        xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
        xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0"
        xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">

        <!-- version information about the JIRA installation -->
        <sys:environment>
                <sys:moduleId>
                        <sys:groupId>com.atlassian.jira</sys:groupId>
                        <sys:artifactId>Jira</sys:artifactId>
                        <sys:version>3.13.2</sys:version>
                        <sys:type>war</sys:type>
                </sys:moduleId>

                <!-- database dependency - JIRA won't start without a database, so lets tell geronimo about this -->
                <sys:dependencies>
                        <sys:dependency>
                                <sys:groupId>console.dbpool</sys:groupId>
                                <sys:artifactId>JiraDS</sys:artifactId>
                        </sys:dependency>
                </sys:dependencies>
        </sys:environment>

        <!-- the context path to deploy the war too - in this case it will be http://localhost:8080/jira -->
        <context-root>/jira</context-root>
        <naming:resource-ref>
                <!-- the name of the database pool in web.xml -->
                <naming:ref-name>jdbc/JiraDS</naming:ref-name>
                <!-- the name of the database pool you created in Geronimo console -->
                <naming:resource-link>jdbc/JiraDS</naming:resource-link>
        </naming:resource-ref>
</web-app>

Edit entityengine.xml

In addition to setting the appropriate field type for you database, you also need to configure the Transaction factory for Geronimo. In $JIRA_INSTALL/edit-webapp/WEB-INF/classes/entityengine.xml find the <transaction-factory> element and replace it with the following:

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
    <user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>
    <transaction-manager-jndi jndi-server-name="default" jndi-name="java:/TransactionManager"/>
</transaction-factory>

Also find the <datasource> element and change the <jndi-jdbc> to have the following:

<jndi-jdbc jndi-server-name="default" jndi-name="java:comp/env/jdbc/JiraDS"/>

The jndi-name attibute is a "java:comp/env/" plus whatever you specified for ref-name in geronimo-web.xml.

Edit web.xml

The web.xml file needs to be edited to tell Geronimo where it can find the data source for the JIRA database. Copy $JIRA_INSTALL/webapp/WEB-INF/web.xml to $JIRA_INSTALL/edit-webapp/WEB-INF/web.xml and add the following under the <web-app> element:

<resource-ref>
    <res-ref-name>jdbc/JiraDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

3. Build JIRA

JIRA can now be built 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_INSTALL/dist-* directories.

4. Deploy JIRA

Create Database Connection Pool in Geronimo Console

The simplest way to do this is by the GUI wizard under Services -> Databases in the Geronimo console. Name the pool jdbc/JiraDS (or whatever you specified for resource-link in geronimo-web.xml). Please refer to http://cwiki.apache.org/GMOxDOC22/configuring-database-pools.html for more information on how to configure a database connection pool.

Deploy WAR in Geronimo Console

Select Application -> Deploy New from inside the Geronimo Console. Click the browse button next to the Archive and select the $JIRA_INSTALL/dist-generic/atlassian-jira-<version>.war. Leave the plan blank and click install.

5. Set JIRA Home

To specify the location of your JIRA Home Directory (note that you need to do this before you build JIRA):

You can specify any location on a disk for your JIRA home directory. Please be sure to specify an absolute path.

Please note that you cannot use the same JIRA home directory for multiple instances of JIRA. We recommend that you do not specify your JIRA home directory inside your installation directory, to prevent information from being accidentally lost during major operations (e.g. backing up and restoring instances).

6. Set mail.mime.decodeparameters

The following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:

mail.mime.decodeparameters=true

System properties are set in different ways depending on your application server.

7. Access JIRA

You should now be able to visit the JIRA setup page at http://localhost:8080/jira (assuming Geronimo is running on the local machine on port 8080).

8. Known Issues

  • When deploying JIRA it fails and I get the following error in the logs:
    14:08:32,349 ERROR [Deployer] Deployment failed due to
    java.lang.ArrayIndexOutOfBoundsException: 12437
    	at org.objectweb.asm.ClassReader.<init>(Unknown Source)
    	at org.objectweb.asm.ClassReader.<init>(Unknown Source)
    	at org.objectweb.asm.ClassReader.<init>(Unknown Source)
    	at org.apache.xbean.finder.ClassFinder.readClassDef(ClassFinder.java:689)
    	at org.apache.xbean.finder.ClassFinder.<init>(ClassFinder.java:139)
    	at org.apache.geronimo.jaxws.builder.WARWebServiceFinder.discoverWebServices(WARWebServiceFinder.java:154)
    	at org.apache.geronimo.jaxws.builder.AdvancedWARWebServiceFinder.discoverPOJOWebServices(AdvancedWARWebServiceFinder.java:73)
    	at org.apache.geronimo.jaxws.builder.AdvancedWARWebServiceFinder.discoverWebServices(AdvancedWARWebServiceFinder.java:45)
    	at org.apache.geronimo.jaxws.builder.WARWebServiceFinder.discoverWebServices(WARWebServiceFinder.java:70)
    

    The solution is to tell Geronimo to use the Simple Web Service finder by adding the -Dorg.apache.geronimo.jaxws.builder.useSimpleFinder=true" property to the $JAVA_OPTS environment variable. http://www.nabble.com/Problem-with-Deploy-in-Geronimo-2.1.2-td18915589s134.html

  • Geronimo 2.1.3 will raise warnings about invalid taglib descriptors
    14:59:09,326 WARN  [JspModuleBuilderExtension] Invalid transformed taglib
    org.apache.xmlbeans.XmlException: Invalid deployment descriptor: errors:
    
    /Users/amyers/Applications/appservers/geronimo-tomcat6-javaee5-2.1.3/repository/com/atlassian/jira/Jira/3.13.2
    /Jira-3.13.2.war/WEB-INF/tld/sitemesh-decorator.tld:8:2:
    error: cvc-datatype-valid.1.1: string value 'SiteMesh Decorator Tags' does not match pattern
    for tld-canonical-nameType in namespace http://java.sun.com/xml/ns/javaee
    

    JIRA still seems to work depite these warnings.

add your notes

Document generated by Confluence on Oct 06, 2009 00:31