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:
- 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 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).
- Copy your entire production installation directory to your staging server.
- Copy your entire production home directory to your staging server.
- Edit
<installation-directory>/atlassian-jira/WEB-INF/classes/jira-application.properties
to point to your staging home directory. 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.
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.
-Datlassian.notifications.disabled=true -Datlassian.mail.senddisabled=true -Datlassian.mail.fetchdisabled=true -Datlassian.mail.popdisabled=true
- Head to
http://localhost:<port>
and log in to JIRA on your staging server. - Go to > System > General Configuration , and change the base URL of your staging site (for example
mysite.staging.com
). - 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 staging database, and staging home directory.
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:
- Copy the production shared home directory to the staging server.
- Edit
<local-home-directory>/cluster.properties
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/jira-application.properties
and <local-home-directory>/cluster.properties
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.
5. Modify application links
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.