This page last changed on Oct 05, 2009 by alui.
These instructions will help you install JIRA on WebLogic 8.1 Service Pack 2 and above.
 | Compatibility notes:
- JIRA will not run on WebLogic 8.1 without Service Pack 2, due to WebLogic bugs (specifically CR112484). JIRA will not run on WebLogic 6.1 as it has filter issues and is not J2EE 1.3 compliant.
- Some users have experienced license-related problems due to a bug in JDK 1.4.2_08 (1.4.2_05 is known to work).
- According to one user Weblogic 9 ships with a broken JDK (possibly the same bug mentioned above), so use 9.1 or 9.2 instead.
To avoid performance problems, be sure to read the weblogic.xml modifications section below. |
On this page:
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. Install Weblogic
- Install WebLogic on your machine (unless already installed). The WebLogic installation directory will be hereafter referred to as $WEBLOGIC_INSTALL.
- Create a domain named atlassian using the Domain Configuration Wizard.
- Create a server for this domain named jira.
- Create an admin user for this domain (name = weblogic, password = weblogic).
3. Configure the WebLogic datasource
3.1. Download the JDBC driver
WebLogic ships with several database drivers. If your database driver is already installed, go to section 3.2. If your database driver is not already installed, follow these steps:
- Create directory "$WEBLOGIC_INSTALL\user_projects\lib"
- Download a JDBC driver for your database (see the list of databases supported by JIRA). Copy the JDBC driver jar file to the $WEBLOGIC_INSTALL\user_projects\lib directory.
- Add the path to the JDBC driver jar file to the WebLogic classpath, by editing "$WEBLOGIC_INSTALL\user_projects\atlassian\startWebLogic.cmd" (the following example is for the HSQL database):
set SERVER_NAME=jira
set WLS_USER=weblogic
set WLS_PW=weblogic
set CLASSPATH=%CLASSPATH%;$WEBLOGIC_INSTALL\user_projects\lib\hsqldb-1.7.1.jar
3.2. Create a connection pool
The following steps apply to the WebLogic 8.1 administration console:
- Open the WebLogic Server Console
- Navigate to JIRA > Services > JDBC > Connection Pools
- Click the "Configure a new JDBC Connection Pool..." link
- Select your "Database Type" from available types, or choose "Other" to configure a database type that is not listed.
- Select your "Database Driver" from available options. (To install a new driver, refer to section 3.1 above).
- Enter the "Name" for this connection pool, e.g. "JIRA Connection Pool".
- Enter the rest of the connection properties, which are specific to your database.
- Click the "Test" button to verify the database connection.
- Click through the wizard to finish the configuration of the connection pool.
3.3. Configure the datasource
The following steps apply to the WebLogic 8.1 administration console:
- Open the WebLogic Server Console
- Navigate to JIRA > Services > JDBC > Data Sources
- Click the "Configure a new JDBC Data Source..." link
- Enter the "Name" for this data source. For example, "Jira Data Source".
- Enter the "JNDI Name". Type "JiraDS", which is the default used for JIRA. This name will be referred to as jndi-name from the entityengine.xml configuration file that you will configure in step 4.2 below.
- Choose the "Pool Name" that you created in step 3.2.6 above.
- Click through the wizard to finish the configuration of the data source.
4. Configure JIRA
4.1 Configure the database connection
Modify the transaction factory tag in the entityengine.xml file, located in the edit-webapp\WEB-INF\classes directory.
- Locate the section:
<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>
and change this to:
<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:comp/UserTransaction"/>
</transaction-factory>
- Now configure the JNDI path where JIRA will expect to find a database connection factory. This is done by editing the <datasource> tag at the bottom of entityengine.xml. For example, using mssql, your <datasource> entry would be:
<datasource name="defaultDS" field-type-name="mssql"
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="JiraDS"/>
</datasource>
The jndi-name (JiraDS in the example above) must be the same as defined in step 3.3.5.
See the Entity Engine documentation for full details.
4.2 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).
5. Configure WebLogic
Weblogic supports some additional webapp configuration parameters in the weblogic.xml file. This file should be created in the edit-webapp/WEB-INF/ directory of the JIRA distribution. Here is a typical example for Weblogic 9:
<?xml version="1.0" encoding="UTF-8"?>
<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90">
<jsp-descriptor>
<page-check-seconds>-1</page-check-seconds>
<precompile>false</precompile>
<working-dir>./jsp_precompile_dir/jira</working-dir>
</jsp-descriptor>
<container-descriptor>
<servlet-reload-check-secs>-1</servlet-reload-check-secs>
<prefer-web-inf-classes>true</prefer-web-inf-classes>
</container-descriptor>
<context-root>jira</context-root>
</weblogic-web-app>
The full weblogic.xml syntax is described in BEA's documentation. Here we describe some important parameters you should consider setting.
Disabling JSP reload checks
JIRA's performance is considerably affected by Weblogic's tendency to scan JSPs for changes on every page load. This can be disabled by setting pageCheckSeconds to -1.
Disabling servlet reload checks
Similar to the JSP reload checks, Weblogic will scan servlets for modifications every second (by default), hurting performance. This can be prevented by setting the servlet-reload-check-secs element to -1.
Avoiding JSP recompiles on redeploy
If you Weblogic instance is often restarted, performance can be improved by explicitly setting a directory to save compile JSPs to (the workingDir parameter), and setting precompile to 'false'.
6. Generate Weblogic WAR file
Edit build.xml and customise the bea.home or wl.home properties. Then run build.sh weblogic.war (Unix) or build.bat weblogic.war (Windows) to generate aWARfile in dist-weblogic/
 | A Windows compatibiity issue is currently being tracked at JRA-11675. |
7. Deploy JIRA to WebLogic server
The following steps apply to the WebLogic 8.1 administration console:
- Open the WebLogic Server Console
- Navigate to jira — Deployments — Web Application Modules
- Click the link "Deploy a new Web Application Module..."
- Locate and select the JIRA WAR file
- Enter the "Name" for this web application module, for example "Atlassian JIRA"
- Click though the wizard to finish the deployment of JIRA web application.
8. 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.
9. Start JIRA
When you access the path at which you have deployed JIRA, via your web browser, the Setup Wizard should appear.
Troubleshooting
Please note: The build.xml file is an Ant file, which when invoked with the build.(sh|bat) script, will construct a deployable webapp. The build.xml file does this by copying the contents of the webapp/ directory, and overwriting it with the contents of edit-webapp/. Thus, never edit files in the webapp/ directory! If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file, and edit it there.
User-contributed notes
Have experiences to share with Weblogic and JIRA? We welcome your thoughts. Please see the user-contributed Weblogic notes.
|