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. How to get a Confluence Developer 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:
- 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.
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 only apply non-clustered (single node) instances of Confluence Data Center. If you run Confluence Data Center in a cluster, there are some additional steps to follow.
- Copy your entire production installation directory to your staging server.
- Copy your entire production home directory to your staging server.
- Edit
<installation-directory>/confluence/WEB-INF/classes/confluence-init.properties
to point to your staging home directory. Edit
<home-directory>/confluence.cfg.xml
or<installation-directory>/server.xml
to point to your staging database.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
- Head to
http://localhost:<port>
and log in to Confluence on your staging server. - Go to Administration menu , then General Configuration. and change the base URL of your staging site (for example
mysite.staging.com
) - Go to Administration menu , then General Configuration. > License Details and apply your development license.
Go to Administration menu , then 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 in a cluster
If you have Confluence Data Center running in a cluster, the process is much the same as when running Confluence on a single server as mentioned above. The only difference is that you will have to copy the 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>/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 Administration menu , then 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.
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).
You can also manually add a banner using HTML. Head to Administration menu , then 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 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.