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.
The suggested license to apply to a non-production environment is a Developer License, not an Evaluation license. You should only use an Evaluation license if you don't have a Developer license tied to your main license. Check out Get a Jira Data Center trial license for details and find out more about license compatibility.
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).
If you’re using the PostgreSQL database, be aware that replication may cause fragmentation of the data and indexes. In its turn, the fragmentation may slow down your environment, especially during the reindex operation.
To improve the environment’s performance, after replicating the database, you should run the following database maintenance commands or tasks.
VACUUM—reclaim the storage space used by stale data. You may also use the ANALYZE command alongside. So, a new query plan will be created for Jira’s database. The queries will be optimized to use the most appropriate indexes.
REINDEX—rebuild the index using the data from the index’s table. So, the old copy of the index will be replaced.
Learn more about the commands in Optimize and Improve PostgreSQL Performance with VACUUM, ANALYZE, and REINDEX.
If you're using Microsoft Teams for Jira, you must manually remove the OAuth key and Jira ID from the MS Teams integration.
The integration data is stored in the database and isn't cleared when removing the app or application link. That's why if you don't remove this data manually, the MS Teams for Jira configuration page will retain the OAuth key and Jira ID from the production instance.
To remove the OAuth key and Jira ID, follow the steps in this Knowledge Base article.
2. Remove production/abandoned nodes from the
After refreshing the database and before starting the Jira backup, remove production nodes from the stage to make sure the production and test nodes don't behave like one cluster. To do this:
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.
The 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.
3. Update the production URL on text gadgets
Text gadgets allow custom html text to be displayed on dashboards.
If you do not update the URL, the dashboard links on the test environment will redirect to the production environment, and users will get a dead page as a result.
Replace the old URL with the new one. For example, use the following command for PostgreSQL:
update gadgetuserpreference set userprefvalue = REPLACE(userprefvalue, '//prod.jira.base.url/', '//test.jira.base.url/') where userprefvalue like '%//prod.jira.base.url/%';
update gadgetuserpreference set userprefvalue = cast(replace(cast(userprefvalue as nvarchar(max)),'//prod.jira.base.url/','//test.jira.base.url/') as text) where userprefvalue like '%//prod.jira.base.url/%';
4. Delete mail server data
To prevent emails being sent from the test environment and issues being created in this environment rather than in production, delete all incoming and outgoing mail servers by truncating the
Additionally, remove all mail handlers by running the following command:
delete from serviceconfig where clazz='com.atlassian.jira.service.services.mail.MailFetcherService'
To make sure no email is sent from the test environment, it's also a good idea to:
- Remove all subscriptions in Jira database with:
delete from filtersubscription;
- Remove notification schemes from all projects in Jira database with:
delete from nodeassociation where sink_node_entity='NotificationScheme
5. (Optional) Remove applinks
It's a good practice to remove any application links between Jira and other Atlassian applications so that the links in production and test environment don't get confused. Alternatively, you can keep the links and just update them (see step 11) however removing them altogether is less problematic. For details, see Remove an application link from Jira server using SQL.
6. 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.
7. 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.
8. Start Jira in test environment
Before starting Jira in the test environment, make sure:
- You've updated the IP value of
ehcache.listener.hostNameto your test server's IP address. Otherwise, the instance may not start.
- Your production and test instances can't communicate over port 40001 and port 40011.
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 Administration () > System > General Configuration , and change the base URL of your test site (for example
- Go to Administration ( > Applications > Versions and licenses, and apply your development license. To update the license, click the edit icon next to it. )
Go to Administration ( > System > System info, and check that Jira is correctly pointing to your test database, and test home directory.)
Go to Administration () > 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.
9. Update webhooks
Your test environment shouldn't be able to trigger production webhooks. This is why you need to edit them in the new environment and either disable them or change to test webhooks.
See how to Manage webhooks. The document will also instruct you on how to ensure that Jira Service Management automation webhooks are updated
10. (Optional) Replicate external user management
If you're managing users in Crowd or an external 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.
11. Modify application links
If you have application links between Jira and other Atlassian applications and you have not deleted them (see step 5), 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.
12. Rebuild Jira index
Since the Jira index from your production environment becomes incompatible with the index on the test environment, you should reindex Jira. Rebuilding the index might take some time, depending on how many issues and apps you have.
- Go to Administration > System.
- In the left panel, select Indexing.
- In the Options, select Full re-index.
- Select the Re-index button.
13. (Optional) Change the look and feel
It's a good practice to change the look and feel of the test instance to have a different logo or color scheme than the production environment. This will help users to distinguish between the two environments and not rely solely on the URL.
See Configuring the look and feel of your Jira applications.
Head back to the landing page, and complete the pre-upgrade steps.