Establishing staging server environments for JIRA applications

This document describes best practices for an enterprise environment setup for JIRA applications:

  • Best-practice recommendations for procedural governance around rolling out changes
  • Recommendations for development / staging / production architecture
  • Technical steps for how to deploy non-production servers


  • For this document we are assuming that as an administrator, you would rather script changes. Therefore we have omitted UI-based changes or separate tools such as the database configuration tool in favor of specifying file system locations.

On this page:

(warning) Please note:

  • The procedures described in this document will work with JIRA platform version 4.0 and later.
  • Please read the entire document before bringing a staging server live. There are risks associated with connecting to production instances that require attention, which are called out in the document.

1. Architecture strategy

Often, systems administration teams will have an established architecture for enterprise applications, including staging environments and failover setups. We offer these recommendations in this section not to supplant or change those company-wide strategies, but rather to help illustrate what some of the considerations will be with Atlassian applications in staging environments.


For the purpose of this document, we'll assume the following definitions:

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

If Atlassian applications are critical systems, we recommend this 3-tier strategy for development, staging, and production.

  • The staging environment is primarily for system administrators to test changes and upgrades before going into production.
  • The development environment is for different business units to test changes on their own, before requesting a production rollout.

2. Governance strategy

In addition to an architecture, we also recommend establishing a governance strategy for changes. This could include:

  • Create a strategy for deploying and testing plugin installation requests. Note that some plugins that are extremely useful in some environments are not appropriate for high-volume critical systems.
  • Publish a timeline for refreshing the development environment, so users know when to remove their changes.
  • Set up a source control repository to house any file system changes, so you can track when changes were made and by whom, historically. If you don't have one already established, Bitbucket is an option. In addition to file system customizations, record your procedures for upgrades, staging refresh (see below) and any other scripted changesets in your source control.
    (tick) Tip: JIRA applications have a tool to manage any changes in your installation. Check the System Information page in the UI for "modified files." This will tell you which files have been customized in your installation directory.

  • For changes such as creating new workflows (that require administrative access), you have two options:
    1. Create an administrative user which has temporary access to administrative functions, on a per-request basis. Add this user to the appropriate groups so they can perform the necessary administrative functions. When the user has completed their administrative functions, remove the user from these groups.
    2. Keep your development server devoid of production data and give more administrative privilege on this server. Require end-users to document specific workflow or scheme setups, then repeat these steps in production. 

3. How to refresh a staging server

We're assuming that you have an existing staging installation. If not, you can use these instructions to set up your staging environment now. 

Take care to make sure your staging server setup does not interfere with your production environment. Read the tips below before launching your staging (or development) server.

3.1 Create a complete production backup

  1. Back up your home directory. See Setting your JIRA Home Directory for the location of your production home directory. 
    (warning) Back up your production attachments and index directories if located outside your JIRA applications home directory. If you're unsure where these are stored, refer to Configuring File Attachments and Search Indexing to determine these locations.
    (info) Refer to Backing Up Data for more information about backing up attachments in JIRA applications.
  2. Back up your installation directory. The 'JIRA Installation Directory' is the directory into which the JIRA application files and libraries were extracted when the JIRA applications were installed.
  3. Back up your production database. Use your native backup tools to take a snapshot of your production database.

3.2 Copy your complete production backup to a staging environment

  1. Shut down your staging server.
  2. Restore your installation and home directories on the staging server.
  3. Point the newly restored installation directory to the newly restored JIRA application home directory.
    1. Edit the file located within the <jira-application-dir>/WEB-INF/classes subdirectory of your new Installation Directory.
    2. Update the jira.home property in this file to the path of the new JIRA application home directory to the path of your copied JIRA applications home directory.
    3. Save your updated file.
    (tick) You can also set your JIRA application home Directory's location by defining an operating system environment variable JIRA_HOME. This value of this variable takes precedence over the value of the jira.home property in the file in your JIRA installation directory. See Setting your JIRA Home Directory for details.
  4. Restore your database to a staging database.
    (warning) If you are using a database (called jiradb for example) with your existing JIRA application installation and the database for your new JIRA application installation is running on the same machine or database server, create your new database with a different name (e.g. something intuitive like jiradb_440 for JIRA 4.4.0). Oracle does not support schema names with periods or underscores. Ensure the new database has identical access permissions to the old JIRA application database.

3.3 Modify your staging environment for the unique configurations

  1. Configure your database connection to point to your staging database.  Edit the dbconfig.xml file at the root of your JIRA home directory, or the datasource in <jira-install>/conf/server.xml for older versions. 
    (warning) This is extremely important! Make sure your staging environment is not pointing to your production database. 
  2. There are two options to handling email:
    1. Disable mail on your staging server. If you need to perform some initial tests on your new JIRA application installation, you can disable its email access to prevent unintended emails being sent. You can leave emails on, if you're wanting to test email functionality. If you choose to do keep emails enabled, watch particularly for:
      1. Create or comment handlers, which can pull mail from your production mail servers. You can disable these from Administration > Advanced > Services, or delete them from 'serviceconfig' table in the database. 
      2. Filter subscriptions, as your users will receive notifications for filters they're subscribed to. Delete filter subscriptions from the 'filtersubscription' table in the database.
      3. Notifications on tickets that are updated. For these, dissociate any notification schemes to projects you wish to test without email notifications.
    2. Keep email enabled and configure your staging instance to test email:
      1. See the guide here: How to Prepare a Development Server's Mail Configuration

3.4 Restart your staging server

You are now ready to restart your server. Once you've restarted, perform the following checks to verify you've done the above steps safely:

  1. Ensure the database is not pointing to production. To check this, see Viewing your System Information. Check the 'Database URL' to ensure it's pointing to the right place.
  2. Ensure emails are disabled or configured for dev server. Also when viewing your system information, check the 'JVM Input Arguments' for the line 'atlassian.mail.senddisabled'.  If you configured the email for a dev server as described above, this line will not be there.

3.5 Post-startup modifications

  1. Modify the instance colors. See Configuring the look and feel of your JIRA applications. This is a good practice for users to identify that they're on the staging server.
  2. Modify the instance base URL. See Configuring JIRA options and change the Instance URL to the staging URL.
  3. Consider the URL whitelist. You may wish to change some of the approved URLs. See Configuring the whitelist.
  4. Apply a development license.  See our licensing FAQ to generate a license for the staging server. Refer to Licensing your JIRA applications to apply it.
  5. Reconfigure applinks. If you are connecting to other servers via applinks, you'll need to change the server ID for those instances. 
    (warning) If you leave applinks in place, it's possible to have your production instance point back to the staging server, if a link is generated.
    1. Confluence: How to change the server ID of Confluence
    2. JIRA applications: Changing Server ID for Test Installations
Last modified on Oct 30, 2015

Was this helpful?

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