Last updated May 22, 2024

Building Jira from source

Status:

LEGACY. This tutorial applies to Jira versions that have reached end of life.

Commercial users at any level receive access to Jira's source code (note, evaluation license holders are not permitted access to Jira's source code). This topic explains how to build this source code into a deployable Jira application.

Building all of Jira from source is only necessary if you need to make extensive modifications to Jira's source code and are using a WAR approach.

You should not need to rebuild Jira if:

  • You need to change many JSP files. JSP files are the template files for many Jira webpages. They can also be more easily changed directly in the standalone Jira installation directory.
  • Create a Jira plugin that adds functionality to Jira. For more information, read the Jira Plugin Guide. Changes and enhancements to Jira's functionality can often be made with Jira plugins without requiring core Jira source code modifications.
  • Recompiling a small number of source files can be done using the instructions in the standalone external-source directory.

If you want to browse through the Jira Core source code, you can download it from our Core source downloads page. You must have a valid Jira license and be logged in to my.atlassian.com with your Atlassian Id. You can download the Jira Software source code from the Software source downloads page. The Jira Core source code is also available in this location. The only difference is that the Jira Software source code has additional plugins available in the dependencySources directory.

Before you begin

Building a Jira WAR file from a Jira Source release

  1. Ensure you have JDK 1.8 or higher.

  2. Download Maven 3.8.8 or higher from the Apache archives of the Maven website.

  3. Ensure the JAVA_HOME environment variable is set and points to your JDK installation. For example,
    On Windows:

    1
    2
    > set JAVA_HOME=[your JDK installation directory]
    

    Alternatively, the Windows environment variables can be configured by choosing My Computer > Properties > Advanced > Environment Variables.

    On Mac/Linux:

    1
    2
    export JAVA_HOME=[your JDK installation directory]
    
  4. Extract Maven to an appropriate location on your operating system. For example,
    On Windows, extract to:

    1
    2
    C:\apache-maven
    

    On Mac/Linux, extract to:

    1
    2
    /usr/local/apache-maven
    
  5. Add Maven's bin directory to your path. For example,
    On Windows:

    1
    2
    > set PATH=C:\apache-maven\bin
    

Again, you can also set this via My Computer > Properties > Advanced > Environment Variables.

On Mac/Linux:

1
2
export PATH=$PATH:/usr/local/apache-maven/bin

Third-party libraries

Install all of the following restricted third-party (.jar) libraries to your local Maven repository (.m2), ensuring that you download the version specified below. All of these libraries are required to successfully build Jira from source. If any of these libraries are missing, the build process will fail.

Due to licensing restrictions, we can't distribute these libraries from Atlassian's public Maven repository. If you have built previous versions of Jira from source, you may already have some of these libraries in your local Maven repository.

Libraries

Download URL

jms

http://repository.jboss.org/nexus/content/groups/public-jboss/javax/jms/jms/1.1/

Maven groupId and artifactId: javax.jms:jms.

Version: 1.1

jmxri and jmxtools

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#7657-jmx-1.2.1-oth-JPR

Maven groupId and artifactId: com.sun.jmx:jmxri and com.sun.jdmk:jmxtools.

 Version: 1.2.1

jndi

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR

(Download 'JNDI 1.2.1 Class Libraries' under 'Java Naming and Directory Interface 1.2.1')

Maven groupId and artifactId: jndi:jndi.

Version: 1.2.1

jta

http://www.oracle.com/technetwork/java/javaee/jta/index.html

(Download 'Class Files 1.0.1B')

Maven groupId and artifactId: jta:jta.

Version: 1.0.1B

Ojdbc8

https://mvnrepository.com/artifact/com.oracle.ojdbc/ojdbc8/19.3.0.0 

(Download jar)

Maven groupId and artifactId: com.oracle.ojdbc:ojdbc8.

Version: 19.3.0.0

To install the libraries, download each one of them (using the links above) into a directory on your file system, for example downloads in your home directory area.

The jmxrijmxtoolsjndi, and jta libraries are downloaded as .zip archives and before you can install them into your local Maven repository, you'll need to either extract the key .jar file, or change the libraries into the .jar form.

  • For jmxri and jmxtools:

    • On Windows:
      Open the downloads directory and extract the jmxri.jar and jmxtools.jar files from the jmx-1_2_1-bin\lib subdirectory of the downloaded jmx-1_2_1-ri.zip file.

    • On Linux:

      1
      2
      cd $HOME/Downloads
      unzip jmx-1_2_1-ri.zip jmx-1_2_1-bin/lib/jmxri.jar jmx-1_2_1-bin/lib/jmxtools.jar
      
  • For jndi:

    • On Windows:
      Open the downloads directory and extract the jndi.jar file from the lib subdirectory of the downloaded jndi-1_2_1.zip file.

    • On Mac/Linux:

      1
      2
      cd $HOME/Downloads
      unzip jndi-1_2_1.zip lib/jndi.jar
      
  • For jta:

    • On Windows:
      Open the downloads directory and rename the jta-1_0_1B-classes.zip file to jta-1_0_1B-classes.jar.

    • On Mac/Linux:

      1
      2
      cd $HOME/Downloads
      mv jta-1_0_1B-classes.zip jta-1_0_1B-classes.jar
      
  1. Download the Jira Core source archive from our Core source downloads page. To download Jira Software, go to Software source downloads.

    To access this page, you'll need to log in as a user with a commercial license.

  2. Extract the Jira source archive to a location of your choice

    This will create a Jira source directory with the name atlassian-jira-X.Y.Z-source, where X.Y.Z is your version of Jira. For example, C:\atlassian-jira-9.12.7-source.

  3. In the Jira source directory, create the localrepo directory. 

  4. Set appropriate permissions for installing the node modules. In your Jira source directory, enter the following commands:

    Code block

    1
    2
    chmod a+x jira-project/conf/frontend/node
    chmod a+x jira-project/jira-components/jira-webapp/src/main/resources/johnson-page/bin/node
    
  5. Install libraries into your local Maven repository. In your Jira source directory, enter the following commands:

    1
    2
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=javax.jms -DartifactId=jms -Dversion=1.1 -Dpackaging=jar -Dfile=$HOME/Downloads/jms-1.1.jar
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=com.sun.jmx -DartifactId=jmxri -Dversion=1.2.1 -Dpackaging=jar -Dfile=$HOME/Downloads/jmx-1_2_1-bin/lib/jmxri.jar
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=com.sun.jdmk -DartifactId=jmxtools -Dversion=1.2.1 -Dpackaging=jar -Dfile=$HOME/Downloads/jmx-1_2_1-bin/lib/jmxtools.jar
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=jndi -DartifactId=jndi -Dversion=1.2.1 -Dpackaging=jar -Dfile=$HOME/Downloads/jndi.jar
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=jta -DartifactId=jta -Dversion=1.0.1 -Dpackaging=jar -Dfile=$HOME/Downloads/jta-1_0_1B-classes.jar
    mvn install:install-file -Dmaven.repo.local=localrepo -DgroupId=com.oracle -DartifactId=ojdbc8-atlassian-hosted -Dversion=19.3.0.0 -Dpackaging=jar -Dfile=$HOME/Downloads/ojdbc8-19.3.0.0.jar
    
  6. Build Jira by executing the following Maven 2 command:
    On Windows:

    1
    2
    C:\atlassian-jira-9.12.7-source\> build.bat
    

    On Mac/Linux:

    1
    2
    > ./build.sh
    
  7. A WAR file called jira-webapp-dist-X.Y.Z.war (where X.Y.Z is your version of Jira), will be built in the jira-project/jira-distribution/jira-webapp-dist/target subdirectory of your extracted Jira source directory.

    For example, if the subdirectory created above (Extract the Jira source archive to a location of your choice) was C:\atlassian-jira-9.12.7-source, the WAR file will be found in: C:\atlassian-jira-9.12.7-source\jira-project\jira-distribution\jira-webapp-dist\target\jira-webapp-dist-9.12.7.war

    You can also find an unpacked version of your Jira source build in the jira-project/jira-distribution/jira-webapp-dist/target/jira-webapp-dist-X.Y.Z subdirectory of your extracted Jira source directory.

  8. The WAR file generated can now be installed into your application server to run the Jira application you just built.

Obtaining the source of Jira's dependencies

When building Jira from source, Maven will automatically fetch the binary (compiled) dependencies that it requires during the build process, so you don't have to do it manually (with the exception of the third-party libraries mentioned above (Third-party libraries)).

Other dependencies are available on Atlassian's public repository. The source of these dependencies is usually available on the library's website (try googling for the library name), or can be identified in the SCM information of the relevant library.

If you have any questions regarding the build process, try searching/posting to the Atlassian Community, which is monitored by the development community, and by Atlassian as often as possible.

Troubleshooting

When you see Java compilation errors

Check java version that is used for building Jira.

When the build process ‘hangs’ on yarn install

1
2
[INFO] — frontend-maven-plugin:1.15.0:yarn (yarn install) @ jira-project —
[INFO] Running 'yarn install --production --frozen-lockfile --prefer-offline --mutex network --no-progress' in ...

There may be an issue with yarn handling --mutex network. If the problem persists, you can remove this parameter from the following maven properties in the project pom.xml: frontend.install.cmd.noDevDependencies and frontend.install.cmd.forDevelopment.

When the build process fails with an error similar to the one encountered when an Atlassian product is unable to install a plugin from Atlassian's public Maven repository

The build script will download several dependencies from Atlassian's public Maven repository.

On rare occasions, the build process may fail and you may receive an error similar to the one encountered when an Atlassian product is unable to install a plugin from Atlassian's public Maven repository. This problem is caused by the JVM being unable to access its default 'cacerts' file, which contains a certificate that trusts Atlassian's public Maven repository.

To resolve this problem:

Rate this page: