Atlanssian：Upgrading Confluence

Atlanssian：Upgrading Confluence

In this guide we'll run you through using the installer to upgrade your Confluence site to the latest Confluence version on Windows or Linux. 

Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more. 

 

Other ways to upgrade Confluence:

• Manually – upgrade Server or single-node Data Center without using the installer.

• Cluster with downtime – upgrade your Data Center cluster.

• Cluster without downtime - rolling upgrade to a compatible bug fix version, with no downtime.

XML backups should not be used to upgrade Confluence.

Before you begin

Before you upgrade Confluence, there's a few questions you need to answer. 

Which upgrade method is the best option?	You can choose to upgrade using the installer, or manually using a zip or tar.gz file. In most cases the installer is the easiest way to upgrade your Confluence instance. You will need to upgrade manually if you are: moving to another operating system or file location as part of this upgrade. upgrading from Confluence 3.5 or earlier upgrading from Confluence 5.6 or earlier and previously used the EAR/WAR distribution to deploy Confluence into an existing application server.  performing a rolling upgrade, and you need to upgrade each node individually.
Are you eligible to upgrade?	To check if software maintenance is current for your license, go to  > General Configuration > Troubleshooting and support tools and make sure the license support period has not expired.   Software maintenance: upgrade at any time during this period.  If your support period has expired, follow the prompts to renew your license and reapply it before upgrading.
Have our supported platforms changed?	Check the Supported Platforms page for the version of Confluence you are upgrading to. This will give you info on supported operating systems, databases and browsers. Good to know: The Confluence installer includes Java (JRE) and Tomcat, so you won't need to upgrade these separately. If you need to upgrade your database, be sure to read the upgrade notes for the Confluence version you plan to upgrade to (and any in-between) to check for any database configuration changes that you may need to make.
Do you need to make changes to your environment?	Newer Confluence versions sometimes require changes to your environment, such as providing more memory or adjusting your reverse proxy settings. Good to know: We use Upgrade Notes to communicate changes that will impact you, such as: Changes to supported databases, memory requirements or other changes that will impact your environment. Features that have significantly changed or been removed in this release. Actions you may need to take in your instance or environment immediately after the upgrade. It's important to read the notes for the version you're upgrading to and those in-between. For example, if you are upgrading from 5.8 to 5.10 you should read the upgrade notes for 5.9 and 5.10.

 

Plan your upgrade

Create a custom upgrade plan

Planning an upgrade? You can instantly generate a tailored upgrade plan from within Confluence. Head to  > General Configuration > Plan your upgrade

You'll need to have a compatible version of the Troubleshooting and Support tools app installed. 

1. Determine your upgrade path

Use the table below to determine the most efficient upgrade path from your current version to the latest versions of Confluence.

Your Version	Recommended upgrade path to Confluence 7
2.7 or earlier	Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.
2.8 to 3.4	Upgrade to 3.5.17, and follow paths below.
3.5	Upgrade to 5.0.3, and follow paths below.
4.0 to 4.3	Upgrade to 5.10.x, and follow paths below.
5.0 to 7.x	Upgrade directly to the latest version of Confluence 7.

If you are upgrading to the next bug fix update (for example, from 7.9.0 to 7.9.4), you can upgrade with no downtime.

 

 

Confluence 7 is a major upgrade

Be sure to check the Confluence Upgrade Matrix, take a full backup, and test your upgrade in a non-production environment before upgrading your production site.

Enterprise releases

A Long Term Support release is a feature release that gets backported critical security updates and critical bug fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading to a Long Term Support release. 

Long Term Support releases were originally referred to as Enterprise Releases.

2. Complete the pre-upgrade checks

• Check the Upgrade Notes for the version you plan to upgrade to (and any in between). 

• Go to  > General Configuration > Plan your upgrade then select the version you want to upgrade to. This will run some pre-upgrade checks. 

• Go to  > General Configuration > Troubleshooting and support tools to run the health check. 

• If the software maintenance period included in your license has expired you can keep using Confluence, but you'll need to renew before you can upgrade.

• Go to  > General Configuration > License Details and follow the prompts to renew your license.

• If you are using the embedded (trial) database you should migrate to a different database before upgrading. See Embedded H2 Database for more information.

• Database character encoding must be set to UTF+8 (or AL32UTF8 for Oracle databases). You will not be able to upgrade to current Confluence versions unless you have the correct character encoding.

• Go to   > Manage apps and scroll down to the Confluence Update Check to check the compatibility of your Marketplace apps.

• Choose the version you plan to upgrade to then hit Check.

 

If you have incompatible add-ons...

If your users rely on particular Marketplace apps, you may want to wait until they are compatible before upgrading Confluence. Vendors generally update their apps very soon after a major release.

Good to know:

• You can disable an app temporarily while you upgrade if it is not yet compatible.

• Compatibility information for Atlassian Labs and other free apps is often not available immediatley after a new release. In many cases the app will still work, so give it a try in a test site before upgrading your production site.

 

3. Upgrade Confluence in a test environment

• Create a staging copy of your current production environment. 
  See Create a staging environment for upgrading Confluence for help creating an environment to test your upgrade in.

• Follow the steps below to upgrade your test environment.  

• Test any unsupported user-installed apps, customizations (such as custom theme or layouts) and proxy configuration (if possible) before upgrading your production environment.   

Upgrade Confluence

4. Back up 

• Back up your database and confirm the backup was created properly. 
  If your database does not support online backups you'll need to stop Confluence first.  

Once you've confirmed your database backup was successful, you can choose to disable the automatic generation of an upgrade recovery file, as this process can take a long time for sites that are medium sized or larger.

• Back up your installation directory
  The installer will completley replace this directory, so any files you've added (such as a keystore or SSL certificate) won't be retained. The installation wizard will back up this directory before starting the upgrade, but you should also back it up manually first. 

• Back up your home directory. 
  The installation wizard gives you the option to also back up your home directory as part of the installation process, but you should also back up this directory manually before starting the upgrade. 
    

Where is my home directory?

You can find the location of your home directory in the <installation-directory>/confluence/WEB-INF/classes/confluence-init.properties file.

This is where your search indexes and attachments are stored. If you store attachments outside the Confluence Home directory, you should also backup your attachments directory. 

 

5. Download Confluence

Download the installer for your operating system. 

6. Run the installer

• Run the installer. 
    

Run the .exe file. We recommend using a Windows administrator account.

If prompted to allow the upgrade wizard to make changes to your computer, choose 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.

 

• Change to the directory where you downloaded Confluence then execute this command to make the installer executable:

$ chmod a+x atlassian-confluence-X.X.X-x64.bin

Where X.X.X is is the Confluence version you downloaded.

Next, run the installer – we recommend using sudo to run the installer:

$ sudo ./atlassian-confluence-X.X.X-x64.bin

You can also choose to run the installer with root user privileges.

  

• Follow the prompts to upgrade Confluence:

  • When prompted choose Upgrade an existing Confluence installation (for Linux users this is option 3).
      

  • Make sure the Existing Confluence installation directory suggested by the wizard is correct (especially important if you have multiple Confluence installations on the same machine).
      

  • Back up Confluence home is strongly recommended. This will create a .zip backup of the Confluence home and installation directories.
      

The installation wizard notifies you of customizations in the Confluence Installation directory. Make a note of these as you'll need to reapply them later.

The installation wizard's ability to notify you about customizations will depend on how your existing Confluence instance was installed: 

• If your current Confluence instance was installed using the installer, the wizard will check the entire Confluence Installation directory.

• If your current Confluence instance was installed manually it will only check the confluence subdirectory of the Confluence Installation directory. The installation wizard will not notify you of modifications in any other directory, for example modifications to start-up scripts under the bin directory or modifications to the server.xml file (such as an SSL configuration). 

You won't be notified about files you've added to the installation directory, so be sure to back them up first.

• The wizard will shut down your Confluence instance and proceed with the upgrade. Once complete, it will restart Confluence and you can then launch Confluence in your browser to confirm the upgrade was successful.
   
  Depending on the size of your instance and the number of upgrade tasks to be run, this step may take a few minutes or several hours.

After the upgrade

7. Copy your database driver

If you're using an Oracle or MySQL database, you'll need to copy the jdbc driver jar file from your existing Confluence installation directory to confluence/WEB-INF/lib in your new installation directory.

Microsoft SQL and Postgres users can skip this step. 

8. Reinstall the service if required (Windows only)

If you run Confluence as a service on Windows you should delete the existing service then re-install the service by running <install-directory>/bin/service.bat.

This makes sure the service gets the most recent JVM options. 

9. Re-apply any modifications

During the upgrade the wizard migrated the following from your existing Confluence installation:

• TCP port values in your <install-directory>/conf/server.xml file. 

• Location of your Confluence home directory in <install-directory>/confluence/WEB-INF/classes/confluence-init.properties.
    

All other customizations, including CATALINA_OPTS  parameters in your  <install-directory>/bin/setenv.sh / setenv.bat  files, need to be reapplied manually.  

 

Any other configurations, customizations (including any other modifications in the  <install-directory>/conf/server.xml file), the path to your own Java installation in <install-directory>/bin/setjre.sh, or setjre.bat, or additional files added to the installation directory are  not migrated during the upgrade and need to be reapplied manually.

• Stop your upgraded Confluence instance.

• Edit each file, and reapply the customizations in your upgraded Confluence Installation directory.

• Copy over any additional files (such as keystore or SSL certificate)

• Restart the upgraded Confluence instance.

We strongly recommend you test your customizations in a test instance prior to upgrading your production instance as changes may have been made to Confluence that make your customizations unusable.

 

Edit the new file manually, rather than copying over the old file, as the default configuration in these files may have changed between Confluence versions.

 

10. Update your apps (add-ons)

You can update any apps that are compatible with the new version of Confluence.

• Go to 

 > Manage apps

• Update your apps to the supported versions.

At this stage, it can be useful to clear your plugin cache. 

This is optional, but can be useful to avoid any issues with third-party apps and plugins.

 

11. Update your reverse proxy and check you can access Confluence

If you are upgrading from Confluence 5.x to Confluence 6.x you will need to modify your reverse proxy (if used) to add Synchrony, which is required for collaborative editing. See Proxy and SSL considerations for more information on the changes you'll need to make to your proxy config.

Once your upgrade is complete, you should access Confluence (via your reverse proxy, not directly) and:

• Head to  > General Configuration > Collaborative editing and check the Synchrony status is running. 

• Edit any page to check that your browser can connect to Synchrony.

See Troubleshooting Collaborative Editing for suggested next steps if Synchrony is not running or you see an error in the editor, as you may have a misconfigured reverse proxy. 

Troubleshooting

Did something go wrong?

If you need to retry the upgrade, you must restore your pre-upgrade backups first.  Do not attempt to run an upgrade again, or start the older version of Confluence again after an upgrade has failed. 

 

• Can't proceed with upgrade because license has expired
  If your license has expired and was not renewed and reapplied before upgrading you will receive errors during the upgrade process. See upgrading beyond current license period for information on how to resolve this problem.

• Can't proceed with upgrade because of a conflict with anti virus
  Some anti-virus or other Internet security tools may interfere with the Confluence upgrade process and prevent the process from completing successfully, particularly if you run Confluence as a Windows service. If you experience or anticipate experiencing such an issue with your anti-virus / Internet security tool, disable this tool first before proceeding with the Confluence upgrade.

• Database does not support online backups
  The upgrade wizard will prompt you to backup your database using your database's backup utilities. If your database does not support online backups, stop the upgrade process, shut down Confluence, perform your database backup and then run the installer again to continue with the upgrade.

• Upgrade is taking a very long time
  If you have a very large database (i.e. database backups take a very long time to complete), setting the confluence.upgrade.recovery.file.enabled system property to false will speed up the upgrade process. It should be used only when there is a process to back up database and verify the backup before performing an upgrade.

• Confluence doesn't start
  Incompatible Marketplace apps can occasionally prevent Confluence from starting successfully. You can troubleshoot the problem by starting Confluence with all user installed apps temporarily disabled. See Start and Stop Confluence for more info.

• Collaborative editing errors
  If Synchrony is not running or you see an error, head to Troubleshooting Collaborative Editing for info on how to get collaborative editing up and running in your environment. The most common problems are a misconfigured reverse proxy or port 8091 not being available for Synchrony.   

Space directory is empty after the upgrade
If you are upgrading from Confluence 6.3 or earlier, there's a known issue where spaces do not appear in the space directory. You'll need to reindex your site after upgrading to fix this.

You can also refer to the Upgrade Troubleshooting guide in the Confluence Knowledge Base, or check for answers from the community at Atlassian Answers.