Establishing staging server environments for JIRA applications

When you upgrade JIRA, we strongly recommend performing the upgrade in a test environment before upgrading your production site. In this guide we'll refer to this test environment as staging

Most JIRA licenses include a free developer license for use in a staging environment. See How to get a JIRA Developer license to find out how to access your license. 


On this page:

Architecture strategy

This page describes how to create a single staging environment for testing your upgrade. However, if Atlassian applications are critical systems for your organization, we recommend a 3-tier architecture that additionally includes a development environment. With this architecture, you have more flexibility when it comes to testing new changes, and can be sure that these changes are safe when you need to roll them out into production. A 3-tier architecture includes the following environments:

  • Production: your live instance, expecting minimal downtime and well tested changes.
  • Staging: a pre-production environment, where the systems administration team can establish exact procedures prior to rollout.
  • Development: a free-for-all environment where users can play with cutting-edge or risky changes. 

The procedure described below can be applied both to creating a staging and development environment. Both of them are identical copies of your production, although used in a different way.


Create a staging environment

1. Replicate your environment

Your staging environment should closely replicate your real-live environment (production), including any reverse proxies, SSL configuration, or load balancer (for Data Center). You may decide to use a different physical server or a virtualized solution. The main thing is to make sure it is an appropriate replica of your production environment. 

For the purposes of these instructions, we assume your staging environment is physically separate from your production environment, and has the same operating system (and Java version if you've installed JIRA manually). 

2. Replicate your database

To replicate your database:

  1. Back up your production database. Refer to the documentation for your database for more info on the best way to do this. 
  2. Install your database on the staging server and restore the backup. 

The steps for restoring your database backup will differ depending on your chosen database and backup tool. Make sure:

  • Your new staging database has a different name from your production database.
  • Your staging database user account has the same username and password as your production database user account.
  • Character encoding and other configurations are the same as your production database (for example character encoding should be Unicode UTF-8 (or AL32UTF8 for Oracle databases). 

3. Replicate JIRA

To replicate JIRA, make a copy of your JIRA installation and point it to your staging database. These instructions are for JIRA Server (for Data Center there are some additional steps before you start JIRA). 

  1. Copy your entire production installation directory to your staging server. 
  2. Copy your entire production home directory to your staging server. 
  3. Edit <installation-directory>/atlassian-jira/WEB-INF/classes/ to point to your staging home directory. 
  4. Edit <home-directory>/dbconfig.xml or  <installation-directory>/server.xml (older versions) to point to your staging database. 

    This is extremely important! Make sure your staging environment is not pointing to your production database.

  5. Start JIRA with the following System Properties to make sure your staging site does not send or receive notifications and emails. For more info about disabling email, see Disable email sending/receiving.   


    What if I need to test email notifications?
    If that's the case, you can keep email notifications enabled and prepare a development server's mail configuration.
  6. Head to  http://localhost:<portand log in to JIRA on your staging server. 
  7. Go to  > System > General Configuration , and change the base URL of your staging site (for example
  8. Go to  > Applications > Versions and licensesand apply your development license. To update the license, click the edit icon next to it.
  9. Go to  > System  > System info, and check that JIRA is correctly pointing to your staging database, and staging home directory. 

  10. Go to  > System > Look and feel, and change the colors of the staging instance to make it different from the production instance. That's a small change, but it might help you avoid big mistakes.

Additional steps for Data Center

If you have JIRA Data Center, the process is much the same as for JIRA Server described above. You will copy each local home and installation directory to each staging node, and then:   

  1. Copy the production shared home directory to the staging server. 
  2. Edit <local-home-directory>/ to point to your staging shared home directory. This change must be made on every staging node. 

Changes to the  <installation-directory>/jira-atlassian/WEB-INF/classes/ and <local-home-directory>/ must be made on every staging node. 

When it comes time to start JIRA, start one node at a time, as usual. 

4. (Optional) Replicate external user management

If you're managing users in Crowd or an external LDAP directory you can:

  • replicate Crowd or your external directory in your staging environment and point your JIRA staging site to your staging external directory (recommended).
  • provide your staging server with network or local access to the same hosts as your production server. 

If you have application links between JIRA and other Atlassian applications, you should change the server ID on each staging application. See How to change the server ID of Confluence and Changing Server ID for Test Installations for JIRA. 

If you don't change the server ID and update your application links there is a chance that when you create a new application link in production it will point to your staging server instead.

Upgrade your staging environment

Once you have created your staging environment, you can upgrade it in the same way you would your production environment. 

Make a note of how long the upgrade takes, as this information will help you plan your production system outage and communicate with your users. 

You can also use your staging environment to test any customizations or essential add-ons in your site. 


Last modified on Mar 26, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.