Abstract
JIRA is the project tracker for teams building great software. JIRA
sits at the center of your development team, connecting the people and
the work being done. Track bugs and tasks, link issues to related source
code, plan agile development, monitor activity, report on project
status, and more. This blog entry will guide you through the process of
installing JIRA on Ubuntu.
Introduction
This installation guide is divided into 4 stages. During the first
stage, you will install the Oracle JDK 6 update 32 platform. During the
second stage, you will install the Apache Tomcat 6.0.35 application
server. During the third stage, you will install the PostgreSQL 9.1
database server, and during the final stage, you will install Atlassian
JIRA 5.0.6.
Disclaimer
This installation guide is intended for persons evaluating Atlassian
JIRA and by no means represents a complete and production-ready
configuration.
Before you begin
Tomcat 6.0.24 contains a
critical bug. Please use 6.0.32 or later.
Deploying multiple Atlassian applications in a single Tomcat container is not supported.
Stage 1: Install Oracle Java 6 update 32
Follow the steps in
How to Install Oracle Java 6 update 32 on Ubuntu 12.04 Linux
Stage 2: Install Apache Tomcat 6.0.35
Follow the steps in
How to Install Apache Tomcat 6.0.35 on Ubuntu 12.04 Linux
Stage 3: Install PostgreSQL 9.1
Follow the steps in
How to Install PostgreSQL 9.1 on Ubuntu 12.04 Linux
Stage 4 Step 1: Download and extract the JIRA Archive
Run the following commands in your console window:
Change to your Home folder.
Download the JIRA WAR distribution using wget:
1
|
wget http: //www .atlassian.com /software/jira/downloads/binary/atlassian-jira-5 .0.6-war. tar .gz
|
Extract the compressed archive:
1
|
tar xvzf atlassian-jira-5.0.6-war. tar .gz
|
The extracted directory is hereafter referred to as your JIRA Installation Directory.
Step 2: Create a dedicated user to run JIRA
JIRA runs under the user it is invoked and therefore can potentially be abused. For this reason, create a dedicated user:
1
|
sudo /usr/sbin/useradd --create-home --comment "Account for running JIRA" --shell /bin/bash jira
|
Step 3: Confine the directories that the new JIRA user can write to
Assign the JIRA user and JIRA group to the JIRA Installation Directory:
1
|
sudo chown jira:jira -R atlassian-jira-5.0.6-war/
|
Assign read/write rights to the owner and group of the JIRA Installation Directory:
1
2
|
sudo chmod u+rwx -R atlassian-jira-5.0.6-war/
sudo chmod g+rwx -R atlassian-jira-5.0.6-war/
|
Add the tomcat6 user to the JIRA group:
1
|
sudo adduser tomcat6 jira
|
Step 4: Customizing files in your JIRA Installation Directory
Please ensure that you only edit files in the edit-webapp directory. If you need to edit files in the webapp directory, copy them from the webapp directory to the edit-webapp directory. Continue to the next step.
Step 5: Ensure that the Transaction Factory has been specified correctly
Edit the entityengine.xml file and ensure that it contains:
1
2
3
4
5
6
|
< 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 >
|
Using this command in your console window:
1
|
nano atlassian-jira-5.0.6-war /edit-webapp/WEB-INF/classes/entityengine .xml
|
Step 6: Create the JIRA Home Directory
The JIRA Home Directory is created under the var
directory. This is a well-known location in the Linux file system for
storing files that can grow, such as application data or log files.
Atlassian also recommends that you create your JIRA Home Directory independently from your JIRA Installation Directory.
Run the following command in your console window to create the JIRA Home directory:
1
2
3
4
|
sudo mkdir -p /var/atlassian/application-data/jira
sudo chown jira:jira /var/atlassian/application-data/jira
sudo chmod u+rwx /var/atlassian/application-data/jira
sudo chmod g+rwx /var/atlassian/application-data/jira
|
Step 7: Configure JIRA with the location of the JIRA Home directory
Edit the jira-application.properties file by running the following command in your console window:
1
|
sudo nano atlassian-jira-5.0.6-war /edit-webapp/WEB-INF/classes/jira-application .properties
|
Now change the jira.home property to:
1
|
jira.home = /var/atlassian/application-data/jira
|
Step 8: Move the JIRA Installation Directory
Move the JIRA Installation Directory from your Home directory to the opt directory on the file system:
1
2
|
sudo mv ~ /atlassian-jira-5 .0.6-war/ /opt
cd /opt
|
Step 9: Build JIRA
We are now going to perform a build in the JIRA Installation
Directory that will produce a deployable WAR file in the
dist-tomcat/tomcat-6 subdirectory of the JIRA Installation Directory.
Navigation to your JIRA Installation Directory:
1
|
cd atlassian-jira-5.0.6-war/
|
Run the build script:
Step 10: Download the PostgreSQL JDBC driver
Tomcat requires an appropriate JDBC driver to allow JIRA to
communicate with the PostgreSQL database. Although there are newer
release drivers available, Atlassian recommends using the 8.4 version.
Navigate back to your Home directory:
Download the PostgreSQL 8.4 JDBC driver:
1
|
wget http: //jdbc .postgresql.org /download/postgresql-8 .4-703.jdbc4.jar
|
Step 11: Configure Tomcat with the PostgreSQL JDBC driver
Move the driver to the shared Java library directory:
1
|
sudo mv postgresql-8.4-703.jdbc4.jar /usr/share/java
|
Navigate to the Tomcat lib directory:
1
|
cd /usr/share/tomcat6/lib
|
Create a soft symbolic link to the driver:
1
|
sudo ln -sT ../.. /java/postgresql-8 .4-703.jdbc4.jar postgresql-8.4-703.jdbc4.jar
|
Step 12: Configure other Tomcat libraries for JIRA
Tomcat does not come with some libraries required by JIRA. They are
made available for download from the Altassian website in a zipped
archive.
Navigate to your Home directory:
Download the zipped archive:
1
|
wget http: //www .atlassian.com /software/jira/downloads/binary/jira-jars-tomcat-distribution-5 .0-rc2-tomcat-6x.zip
|
Install the unzip package:
1
|
sudo apt-get install unzip
|
Unzip the archive:
1
|
unzip jira-jars-tomcat-distribution-5.0-rc2-tomcat-6x.zip
|
List the libraries in the shared Java directory and remove any
versions of the libraries you just extracted from the zipped archive:
Move the extracted libraries to the Java shared directory:
If they are the only jar files in your Home folder, you can move them with one command:
1
|
sudo mv *.jar /usr/share/java
|
If not, you can copy and paste the commands below one by one:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
sudo mv slf4j-api-1.5.8.jar /usr/share/java
sudo mv slf4j-log4j12-1.5.8.jar /usr/share/java
sudo mv jul-to-slf4j-1.5.8.jar /usr/share/java
sudo mv jcl-over-slf4j-1.5.8.jar /usr/share/java
sudo mv log4j-1.2.16.jar /usr/share/java
sudo mv hsqldb-1.8.0.5.jar /usr/share/java
sudo mv jta-1.0.1B.jar /usr/share/java
sudo mv ots-jts-1.0.jar /usr/share/java
sudo mv jotm-1.4.3.jar /usr/share/java
sudo mv jotm-jrmp_stubs-1.4.3.jar /usr/share/java
sudo mv jotm-iiop_stubs-1.4.3.jar /usr/share/java
sudo mv jonas_timer-1.4.3.jar /usr/share/java
sudo mv objectweb-datasource-1.4.3.jar /usr/share/java
sudo mv carol-1.5.2.jar /usr/share/java
sudo mv carol-properties-1.5.2.jar /usr/share/java
sudo mv xapool-1.3.1.jar /usr/share/java
|
Now you need to create soft symbolic links to each library in the Tomcat lib directory.
Navigate to the Tomcat lib directory:
1
|
cd /usr/share/tomcat6/lib
|
Create symbolic soft links to each library:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
sudo ln -sT ../.. /java/slf4j-api-1 .5.8.jar slf4j-api-1.5.8.jar
sudo ln -sT ../.. /java/slf4j-log4j12-1 .5.8.jar slf4j-log4j12-1.5.8.jar
sudo ln -sT ../.. /java/jul-to-slf4j-1 .5.8.jar jul-to-slf4j-1.5.8.jar
sudo ln -sT ../.. /java/jcl-over-slf4j-1 .5.8.jar jcl-over-slf4j-1.5.8.jar
sudo ln -sT ../.. /java/log4j-1 .2.16.jar log4j-1.2.16.jar
sudo ln -sT ../.. /java/hsqldb-1 .8.0.5.jar hsqldb-1.8.0.5.jar
sudo ln -sT ../.. /java/jta-1 .0.1B.jar jta-1.0.1B.jar
sudo ln -sT ../.. /java/ots-jts-1 .0.jar ots-jts-1.0.jar
sudo ln -sT ../.. /java/jotm-1 .4.3.jar jotm-1.4.3.jar
sudo ln -sT ../.. /java/jotm-jrmp_stubs-1 .4.3.jar jotm-jrmp_stubs-1.4.3.jar
sudo ln -sT ../.. /java/jotm-iiop_stubs-1 .4.3.jar jotm-iiop_stubs-1.4.3.jar
sudo ln -sT ../.. /java/jonas_timer-1 .4.3.jar jonas_timer-1.4.3.jar
sudo ln -sT ../.. /java/objectweb-datasource-1 .4.3.jar objectweb-datasource-1.4.3.jar
sudo ln -sT ../.. /java/carol-1 .5.2.jar carol-1.5.2.jar
sudo ln -sT ../.. /java/carol-properties-1 .5.2.jar carol-properties-1.5.2.jar
sudo ln -sT ../.. /java/xapool-1 .3.1.jar xapool-1.3.1.jar
|
To prevent exceptions to logging, ensure that the following files are present in the Tomcat lib directory:
1
2
3
4
5
|
jcl-over-slf4j-x.y.z.jar
jul-to-slf4j-x.y.z.jar
log4j-x.y.z.jar
slf4j-api-x.y.z.jar
slf4j-log4j12-x-y-z.jar
|
You also need to ensure that the files above are not present in the
webapp/jira/WEB-INF/lib subdirectory of the JIRA Installation Directory.
Run the following command to list the content of the lib subdirectory:
1
|
ls /opt/atlassian-jira-5 .0.6-war /webapp/WEB-INF/lib/
|
Step 13: Configure JIRA’s context in Tomcat
Copy the jira.xml file from the dist-tomcat6 subdirectory of your
JIRA Installation Directory to the conf/Catalina/localhost subdirectory
of your Tomcat installation:
1
|
sudo cp /opt/atlassian-jira-5 .0.6-war /dist-tomcat/tomcat-6/jira .xml /etc/tomcat6/Catalina/localhost/
|
Customize the jira.xml file using the command below. Change the value
assigned to docBase to
/opt/atlassian-jira-5.0.6-war/dist-tomcat/tomcat-6/atlassian-jira-5.0.6.war:
1
|
sudo nano /etc/tomcat6/Catalina/localhost/jira .xml
|
Your docBase must look like this:
1
|
< Context path = "/jira" docBase = "/opt/atlassian-jira-5.0.6-war/dist-tomcat/tomcat-6/atlassian-jira-5.0.6.war" debug = "0" useHttpOnly = "true" >
|
Step 14: Modify Tomcat’s server.xml to handle international characters correctly
Since this property must be specified at the connector level for
your application server, this setting will affect all other web
applications deployed to the same application server installation
running JIRA. While this setting should not adversely affect these other
web applications, you should be aware of this point.
JIRA 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.
You need to modify the server.xml file in your Tomcat configuration directory by specifying
Run the following command to edit your server.xml file:
1
|
sudo nano /etc/tomcat6/server .xml
|
Step 15: Fix memory and mail handling settings in Tomcat
Tomcat effectively leaks memory by caching JSPs. This can result
in OutOfMemoryError errors if large pages (such as RSS or Excel pages)
are requested.
JIRA requires more memory than what Tomcat provides by default.
This may lead to OutOfMemory errors when running JIRA if these memory
settings are not increased.
For JIRA’s mail handler to avoid problems with RFC 2231-compliant mail clients, set the mail.mime.decodeparameters start-up parameter in Tomcat to true.
Edit Tomcat’s bin/setenv.sh file (or create this file if it does not exist) and add the following to the file:
1
2
|
sudo nano /usr/share/tomcat6/bin/setenv .sh
export
CATALINA_OPTS= "$CATALINA_OPTSDorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true
-Dmail.mime.decodeparameters=true -Xms128m -Xmx512m
-XX:MaxPermSize=256m"
|
Step 16: View the Tomcat log in a separate console window
This will allow you to follow the Atlassian bootstrap process from
the Tomcat log file. Open another console window and run the following
command in the new window:
|
tail -f /var/lib/tomcat6/logs/catalina .out
|
Step 17: Restart Tomcat
Run the following command in your original console window:
|
sudo service tomcat6 restart
|
Step 18: Create a PostgreSQL user
Run the following commands in your console window:
|
sudo su - postgres
createuser -P jira
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y /n ) n
Shall the new role be allowed to create databases? (y /n ) y
Shall the new role be allowed to create more new roles? (y /n ) n
logout
|
Remember the your user name and password. You will need this information when you run jita for the first time.
Step 19: Create a PostgreSQL database
Run the following commands in your console window:
1
2
3
|
sudo su - jira
createdb jiradb
exit
|
Step 20: Navigate to JIRA in your browser
1
|
http: //servername :8080 /jira
|
Step 21: Congratulations – You have just installed Atlassian JIRA on Ubuntu Linux