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:
- Back up your production database. Refer to the documentation for your database for more info on the best way to do this.
- 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
This is to make sure the production and test nodes do not behave like one cluster. To do that:
Review the content of the
clusternodetable. This table is the reference used by Jira when it comes to Data Center operations. Execute the following command:
SELECT * FROM clusternode;
Remove any production node records.
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
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.
- Copy your entire production installation directory to your test server.
- Copy your entire production home directory to your test server.
<installation-directory>/atlassian-jira/WEB-INF/classes/jira-application.propertiesto point to your test home directory.
CLUSTER For DC, make this change on every node.
<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
- Copy the production shared home directory to the test server.
<local-home-directory>/cluster.propertiesto point to your test shared home directory. Make this change on every test node.
4. Start Jira in test environment
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.
-Datlassian.notifications.disabled=true -Datlassian.mail.senddisabled=true -Datlassian.mail.fetchdisabled=true -Datlassian.mail.popdisabled=true
CLUSTER Start one node at a time.
- Head to
http://localhost:<port>and log in to Jira on your test server.
- Go to > System > General Configuration , and change the base URL of your test site (for example
- Go to > Applications > Versions and licenses, and apply your development license. To update the license, click the edit icon next to it.
Go to > System > System info, and check that Jira is correctly pointing to your test database, and test home directory.
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.
6. Modify application links
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.
Head back to the landing page, and complete the pre-upgrade steps.