Installing Jira applications on Linux

App installation guidelines in Jira

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Starting from Jira 10, we only support using this manual installation method.

In this guide we'll run you through installing a Jira application in a production environment, with an external database, manually using a tar.gz file.

This method gives you the most control over the installation process.

Other ways to install Jira: 

  • Evaluation - get your free trial up and running in no time.
  • Installer – install Jira using the Linux installer. 
  • Windows – install Jira on a Windows server. 



On this page:

Before you begin

Before you install Jira, there are a few questions you need to answer. 


Are you using a supported operating system and Java version?
Tell me more...

Check the Supported platforms page for the version of Jira you are installing. This will give you info on supported operating systems, databases and browsers.

Good to know:

  • We don't support installing Jira on OS X or mac OS for production environments.
  • You can use OpenJDK the JDK (Java Development Kit) or JRE (Java Runtime Environment).
  • We only support the version of Apache Tomcat that is bundled with Jira.
Are you using a 32-bit operating system?
Tell me more...

If you’re installing Jira on a 32-bit system, you need to decrease the maximum heap size available to Jira. The default for 64-bit systems is 2GB, which is too much for a 32-bit system, and may not fit into the available memory.


Complete these steps after extracting files from the archive, but before starting Jira.

Step 1: Rename the default setenv file.

  1. Go to <Jira-install-directory>/bin, and delete the setenv.bat / .sh file (or change its name).

  2. Rename setenv32.bat / .sh to setenv.bat / .sh. Jira will use this file on startup.

Step 2: Add the properties to the jira-config.properties file.

  1. Go to Jira’s home directory, and edit the jira-config.properties file. If the file isn’t there, you can create it.

  2. Add the following properties:

    jira.index.batch.maxrambuffermb=256
jira.index.interactive.maxrambuffermb=256

Do you want to run Jira as a service?

Tell me more...

Running Jira as a service means that your Jira application will automatically start up when your Linux server is started.

You should use the Linux installer if you want to run Jira as a service.

If you choose not to run Jira as a service:

  • You will start your Jira application by running the start-jira.sh file in your Jira installation directory.
  • We recommend creating a dedicated user to run Jira. This user must have full read, write and execute access to the installation directory and home directory.
  • Jira will need to be restarted manually if your server is restarted.
What database do you plan to use? 
Tell me more...

To run Jira in production you'll need an external database. Check the Supported platforms page for the version you're installing for the list of databases we currently support. If you don't already have a database, PostgreSQL is free, easy to set up and has been extensively tested with Jira.

Good to know:

  • Set up your database before you begin. Step-by-step guides for all supported databases are available in Connecting Jira applications to a database.
  • Use UTF-8 character encoding.
  • If you're using Oracle or MySQL you'll need to download the driver for your database.
  • The embedded H2 database can be used for evaluating Jira, but you'll need to migrate to another database before running in production. You may find it easier to use external database from the start.

Do you have a Jira license?

Tell me more...

You'll need a valid Data Center license for Jira Software, Jira Core, or Jira Service Management to use Jira.

Good to know:

  • If you have not yet purchased a Jira application license you'll be able to create an evaluation license during setup.
  • If you already have a license key you'll be prompted to log in to my.atlassian.com to retrieve it, or you can enter the key manually during setup.
  • If you're migrating from Jira Cloud, you'll need a new licenseJira

Is your JAVA_HOME variable set correctly?
Tell me more...

Before you install Jira, check that you're running a supported Java version and that the JAVA_HOME environment variable is set correctly.

Jira applications can run with OpenJDK, Oracle JDK or JRE.

To check your Java version:

$ java -version

To check your JAVA_HOME variable is set correctly:

$ echo $JAVA_HOME

If you see a path to your Java installation directory, the JAVA_Home environment variable has been set correctly. If a path is not returned you'll need to set your JAVA_HOME environment variable manually before installing Jira.

Have you created a dedicated user to run Jira?

Tell me more...

We strongly recommend running Jira as a dedicated user.

You should create this user before you begin, so that when creating the installation and home directories, you can give this user appropriate read and write permissions.

In this example, we'll create a user called jira:

$ sudo /usr/sbin/useradd --create-home --comment "Account for running Jira Software" --shell /bin/bash jira


Install a Jira application

1. Download Jira

Download the tar.gz file for your operating system:

2. Create the installation directory

  1. Create your installation directory – this is where Jira will be installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your <installation-directory>. 
     

    Show me how to do this...

    In this example we'll call our installation directory jirasoftware:

    $ mkdir jirasoftware

  2. Extract the Jira tar.gz file to your <installation-directory>. We recommend using a GNU version of the archive utility, especially on Solaris.
     

    Show me how to do this...

    Change to the directory where you downloaded Jira then execute these commands:

    $ tar -xzf atlassian-jira-software-X.X.X.tar.gz -C <installation-directory>
$ cd <installation-directory>

    Replace x.x.x with your Jira version and <installation-directory> with the full path to the directory you created in the last step.

  3. Give your dedicated Jira user read, write and execute permission to your <installation-directory>. 
     

    Show me how to do this...

    In this example we're changing ownership of the installation directory and giving the user jira read, write and execute permissions.

    $ chown -R jira <installation-directory>
$ chmod -R u=rwx,go-rwx <installation-directory>

3. Create the home directory

  1. Create your home directory – this is where Jira application data like logs, search indexes and files will be stored. This should be separate to your installation directory, with no spaces or special characters in the path. Each Jira application needs its own home directory. 

    We'll refer to this directory as your <home-directory>. 
     

    Show me how to do this...

    In this example we'll call our home directory jirasoftware-home:

    $ mkdir jirasoftware-home

  2. Give your dedicated Jira user read, write and execute permissions to the <home-directory>.

    Show me how to do this...

    In this example we're changing ownership of the home directory and giving the user jira read, write and execute permissions.

    $ chown -R jira <home-directory>
$ chmod -R u=rwx,go-rwx <home-directory>

  3. Tell Jira where to find your <home-directory> when it starts up.  There are two ways to do this:
      

    (Preferred) Set an environment variable...

    You can set an environment variable named JIRA_HOME in your operating system with the absolute path to your <home-directory>.

    In Terminal, execute the following:

    export JIRA_HOME=/path/to/home-directory

    You can then specify the command above in a script used to start Jira.

    Edit the jira-application.properties file...

    Edit <installation-directory>\atlassian-jira\WEB-INF\classes\jira-application.properties file in any text editor.

    After jira.home add the absolute path to your home directory (not a symlink), for example:

    jira.home=/var/jirasoftware-home

4. Check the ports

By default Jira listens on port 8080. If you have another application running on your server that uses the same ports, you'll need to tell Jira to use a different port. 
 

Show me how to do this...

To change the ports:

  1. Edit <installation-directory>\conf\server.xml

  2. Change the Server port (8005) and the Connector port (8080) to free ports on your server.

    In the example below we've changed the Server port to 5005 and the Connector port to 5050.

    <Server port="5005" shutdown="SHUTDOWN">
...
   <Service name="Catalina">
      <Connector port="5050"
         maxThreads="150"
         minSpareThreads="25"
         connectionTimeout="20000"
         enableLookups="false"
         maxHttpHeaderSize="8192"
         protocol="HTTP/1.1"
         useBodyEncodingForURI="true"
         redirectPort="8443"
         acceptCount="100"
         disableUploadTimeout="true"/>

If you are running on a Unix server and bind the ports below 1024 (such as port 80 for example), you will need to start Jira as root in order to successfully bind to the port.

5. Start Jira

  1. Run <installation-directory>/bin/start-jira.sh to start the setup process.  
     

    Show me how to do this...

    We recommend running Jira as your dedicated user.

    $ su -u <user>
$ ./start-jira.sh

    If you're using Ubuntu the command is a little different:

    $ sudo su <user>
$ ./start-jira.sh
  2. Go to http://localhost:8080/ to launch Jira in your browser (change the port if you've updated the Connector port).


Trouble starting JIRA?
  • Check your JAVA_HOME variable is set correctly.

Set up your Jira application

6. Choose set up method

Choose I'll set it up myself.

7. Connect to your database

  1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of this page for details. 
  2. Choose My own database. 

  3. Choose your database type then enter the details for your database. 
      

    Show me how to do this...

    JIRA connects to your database using a standard JDBC database connection. Connection pooling is handled within JIRA, you can change this using JIRA configuration tool later.

    If you're using Oracle or MySQL there's an extra step: 

    • Download and extract the appropriate database JDBC drivers. See Supported platforms to get the right version.
    • Drop the JAR file into your <jira-installation>/lib folder before continuing with the setup wizard.

    In the setup wizard:

    • Driver Class Name – the Java class name for your database driver. If you're not sure, check the documentation for your database.
    • Database URL – the JDBC URL for your database. If you're not sure, check the documentation for your database.
    • Username and Password – A valid username and password that JIRA can use to access your database.

8. Set application properties

  1. Give your Jira site a name.
  2. Choose whether your site should be private or anyone can sign up. You can change this later. 
  3. Enter your base URL - this is the address people will use to access your Jira site. 

9. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

10. Create your administrator account

Enter details for the administrator account.  You can add more administrators after set up is complete.

11. Set up email notifications

Enter details of your mail server.  This will allow Jira to send notifications when issues change.

12. Start using Jira

That's it! Your Jira site is accessible from your base URL or a URL like this: http://<computer_name_or_IP_address>:<port>

Here's a few things that will help you get your team up and running:

Troubleshooting

Running into problems installing Jira?
  • Check your JAVA_HOME is set correctly.

 Head to Installation Troubleshooting in our Knowledge Base for more help.  

Last modified on Jul 1, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.