Create a staging environment for upgrading Confluence

When you upgrade Confluence 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 Confluence licenses include a free developer license for use in a staging environment. See How to get a Confluence Developer license to find out how to access your license. 

On this page:

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

2 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 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 Confluence

To replicate Confluence, make a copy of your Confluence installation and point it to your staging database. These instructions are for Confluence Server (for Data Center there are some additional steps before you start Confluence). 

  1. Copy your entire production installation directory to your staging server. 
  2. Copy your entire production home directory to your staging server. 
  3. Edit <installation-directory>/confluence/WEB-INF/classes/ to point to your staging home directory. 
  4. Edit <home-directory>/confluence.cfg.xml or <installation-directory>/server.xml to point to your staging database.

    If you're using a direct JDBC connection, the line you need to update in confluence.cfg.xml will look something like this...
    <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/confluencestaging</property>
    If you're using a datasource connection, the lines you need to update in server.xml will look something like this...
    <Resource name="jdbc/confluence" auth="Container" type="javax.sql.DataSource"
         validationQuery="select 1" />
  5. Start Confluence with the following System Properties to make sure your staging site does not send notifications to real users.   

  6. Head to http://localhost:<port> and log in to Confluence on your staging server. 
  7. Go to

     > General Configuration

     and change the base URL of your staging site (for example
  8. Go to 

     > General Configuration

     > License Details and apply your development license.
  9. Go to 

     > General Configuration

     > System Information and check that Confluence is correctly pointing to your staging database, and staging home directory.  

    It's essential to check that you are not still connected to your production database.

Additional steps for Data Center

If you have Confluence Data Center, the process is much the same as for Confluence Server described above. You will copy each local home and installation directory to each staging node, and then:   

  1. Copy the production shared home directory to the staging server. 
  2. Edit<local-home-directory>/confluence.cfg.xml to point to your staging shared home directory. This change must be made on every staging node. 

Changes to the  <installation-directory>/confluence/WEB-INF/classes/  and  <home-directory>/confluence.cfg.xml  must be made on every staging node. 

When it comes time to start Confluence, start one node at a time, as usual. 

4 Replicate external user management (optional)

If you're managing users in JIRA, Crowd, or in an external LDAP directory you can:

  • replicate JIRA, Crowd, or your external directory in your staging environment and point your Confluence 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 (optional)

If you have application links between Confluence and other Atlassian applications you should change the server ID on each staging application. See How to change the server ID of Confluence and Change the server ID for an instance of Jira server 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. 

Last modified on Sep 10, 2017

Was this helpful?

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