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/confluence-init.properties 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"
         username="postgres"
         password="postgres"
         driverClassName="org.postgresql.Driver"
         url="jdbc:postgresql://localhost:5432/confluencestaging"
         maxTotal="60"
         maxIdle="20"
         validationQuery="select 1" />
  5. Start Confluence with the following System Properties to make sure your staging site does not send notifications to real users.   

    -Datlassian.notifications.disabled=true
    -Datlassian.mail.senddisabled=true
  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 mysite.staging.com)
  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/confluence-init.properties  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. 

Additional configuration options

There are a number of additional things you may want to change in your staging environment, to make sure it does not interact with your production environment, or to clearly differentiate it for users. 

Modify application links (recommended)

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.

To review the Application Links manually in the database, use the following  following SQL query:

select * from bandana where bandanakey like 'applinks%';

Modify external gadgets 

If you have external gadgets configured, you can update these from the database, using the following SQL query:

select * from bandana where bandanakey = 'confluence.ExternalGadgetSpecStore.specs'

Change the global color scheme

If can be helpful to use a different color scheme on your staging site, to differentiate it from your production site. See Customizing Color Schemes for how to do this. 

You can also find this data in the database using the following SQL query:

select * from bandana where bandanakey = 'atlassian.confluence.colour.scheme';


Change the instance name (recommended)

It is a good idea to change the name of your staging site, to differentiate it from your production site. Head to  > General Configuration and update the Site Title if Confluence is running. 

If Confluence is not running, you can do this from the database. You can find the site title using the following SQL query:

select * from bandana where bandanakey = 'atlassian.confluence.settings';

The attribute you are looking for is setTitle.

Add a banner

It can be useful to add a banner to your staging site, to provide useful information like the date of the last refresh, or who to contact if you want to make changes. 

You can manually add a banner using HTML. Head to  > General Configuration > Custom HTML.  Remember to close your tags properly, or Confluence may not display correctly. 

If you want to add a banner before starting Confluence, you can do it in the database. You can find the custom HTML using the following SQL query:

select * from bandana where bandanakey = 'atlassian.confluence.settings';

The attribute you are looking for is customHtmlSettings → afterBodyStart

Disable specific plugins 

You might want to disable specific plugins or check whether these plugins are already disabled or not. See the How to reset all Confluence plugins back to their default state through the database knowledge base article to find how to do this. 

You can also disable plugins in Confluence in 6.1+ using Java system properties.  

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 Jun 20, 2019

Was this helpful?

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