Create a staging environment for upgrading Confluence

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.

3. Re-create any database triggers that may still reference the original database name. If you're using SQLServer, the following query may help identifying them:

   SELECT table_name = so.name
   ,trigger_name = st.name
   ,trigger_text = sc.text
   ,create_date = st.create_date
   FROM sys.triggers st
   JOIN sysobjects so ON st.parent_id = so.id
   JOIN syscomments sc ON sc.id = st.[object_id];

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

   Error rendering macro 'includeplus'

   User 'anonymous' does not have permission to view the page with ID 1255454939.

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

   Error rendering macro 'includeplus'

   User 'anonymous' does not have permission to view the page with ID 1255454939.

    > License Details and apply your development license.

9. Go to 

   Error rendering macro 'includeplus'

   User 'anonymous' does not have permission to view the page with ID 1255454939.

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

Bypass single sign-on

If you've configured single sign-on, you might want to bypass this in your staging environment. 

See Enable default login page to bypass SAML in Confluence Data Center. 

Disable CDN

If you've configured a CDN to cache static assets, you may experience problems with broken resources as the CDN configuration is for your production environment, not the staging environment. 

To find out how to disable CDN, see Configure your CDN for Confluence Data Center.

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 

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. 

If you have a Confluence Data Center license, you can do this by enabling the banner that is used by read-only mode (you don't need to enable read-only mode to use the banner). 

If you have a Confluence Server license, you can manually add a banner using HTML. Head to 

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 Data Center 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 Marketplace apps in your site.