Creating a test environment for Jira

When you upgrade Jira, we strongly recommend performing the upgrade in a test environment before upgrading your production site.

Replicate your environment

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

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

Create a test environment

1. 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 test 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 test database has a different name from your production database.
  • Your test 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).


2. Remove production/abandoned nodes from the clusternode table

This is to make sure the production and test nodes do not behave like one cluster. To do that:

  1. Review the content of the clusternode table. This table is the reference used by Jira when it comes to Data Center operations. Execute the following command:

    SELECT * FROM clusternode;
  2. Remove any production node records.

  3. Remove any abandoned node records as them might affect reindexing operations later on. To learn more on how to do that, see this article.

    XML backup also brings abandoned nodes to the clusternode table.

Additionally, make sure the production and the test environment are in a different subnet. This is to prevent the test environment to try and communicate with production. If clusters see each other within network, it might cause issues.

2. Replicate Jira

To replicate Jira, make a copy of your Jira installation and point it to your test database.

  1. Copy your entire production installation directory to your test server. 
  2. Copy your entire production home directory to your test server. 
  3. Edit <installation-directory>/atlassian-jira/WEB-INF/classes/ to point to your test home directory. 
    CLUSTER For DC, make this change on every node.
  4. Edit <home-directory>/dbconfig.xml or  <installation-directory>/server.xml (older versions) to point to your test database. 

    Make sure your test environment is not pointing to your production database.


3. Manage shared home directory

  1. Copy the production shared home directory to the test server. 
  2. Edit <local-home-directory>/ to point to your test shared home directory. Make this change on every test node. 

4. Start Jira in test environment

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


    CLUSTER Start one node at a time.

    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.
  2. Head to  http://localhost:<portand log in to Jira on your test server. 
  3. Go to  > System > General Configuration , and change the base URL of your test site (for example ).
  4. Go to  > Applications > Versions and licensesand apply your development license. To update the license, click the edit icon next to it.
  5. Go to  > System > System info, and check that Jira is correctly pointing to your test database, and test home directory. 

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


5. (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 test environment and point your Jira test site to your test external directory (recommended).
  • provide your test 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 test 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 test server instead.

All good?

Head back to the landing page, and complete the pre-upgrade steps.

Go to landing page

Last modified on Feb 26, 2020

Was this helpful?

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