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).

CLUSTER

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.

   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.

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/%';

For MSSQL:

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/%';

Remember to replace the production and test.jira.base.url in the command with your production and test Jira base URLs. For example, jira.atlassian.com and jira-test.atlassian.com.

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 mailserver table.

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.

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/jira-application.properties 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.

CLUSTER

7. Manage shared home directory

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

8. 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.   

   -Datlassian.notifications.disabled=true
   -Datlassian.mail.senddisabled=true
   -Datlassian.mail.fetchdisabled=true
   -Datlassian.mail.popdisabled=true

   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:<port> and log in to Jira on your test server. 
3. Go to Administration () > System > General Configuration , and change the base URL of your test site (for example  mysite.test.com ).
4. Go to Administration () > Applications > Versions and licenses, and apply your development license. To update the license, click the edit icon next to it.

5. Go to Administration () > System > System info, and check that Jira is correctly pointing to your test database, and test home directory. 

6. 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.

CLUSTER

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. (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.

All good?

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

Go to landing page