Upgrading Confluence Manually

In this guide we'll run you through upgrading your Confluence site to the latest Confluence version on Windows or Linux using the zip / tar.gz file. 

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:

  • Installer – the simplest way to upgrade Confluence.
  • Data Center – upgrade your Data Center cluster.

XML backups should not be used to upgrade Confluence.

On this page:

Before you begin

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

Is manual the right upgrade method for you?
  Tell me more...

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.
  • you are upgrading from Confluence 3.5 or earlier
  • you are upgrading from Confluence 5.6 or earlier and previously used the EAR/WAR distribution to deploy Confluence into an existing application server. 

Are you eligible to upgrade?

  Tell me more...

To check if software maintenance is current for your license, go to   > General Configuration >  Support Tools and make sure the license support period has not expired.


If your support period has expired, follow the prompts to renew your license and reapply it before upgrading.

Have our supported platforms changed?

  Tell me more...

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:

  • If you need to upgrade Java, remember to update your JAVA_HOME variable to the new version.
  • The Confluence installer includes Tomcat, so you won't need to upgrade it seperately.
  • 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?
  Tell me more...

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

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 6

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 then upgrade to the latest version of Confluence 6.

4.0 to 4.3 

Upgrade to 5.10.x then upgrade to the latest version of Confluence 6.

5.0 to 6.x

Upgrade directly to the latest version of Confluence 6.

 

 

Confluence 6 is a major upgrade

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

2. Complete the pre-upgrade checks

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

  2. Go to  > General Configuration > Support Tools to run the health check (available in Confluence 5.5 or later). 

      License expired?

    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.

      Still using the embedded database?

    If you are using the embedded (trial) database you should migrate to a different database before upgrading.

    This database is supplied for evaluation purposes only and is not recommended for production environments. See Embedded H2 Database for more information.

      Database character encoding incorrect?

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

      

  3. Go to   > Add-ons > add-ons and scroll down to the Confluence Update Check to check the compatibility of your add-ons.
      

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

      If you have incompatible add-ons...

    If your users rely on particular add-ons, you may want to wait until they are compatible before upgrading Confluence. Add-on vendors generally update their add-ons very soon after a major release.

    Good to know:

    • You can disable an add-on temporarily while you upgrade if it is not yet compatible.
    • Compatibility information for Atlassian Labs and other free add-ons is often not available immediatley after a new release. In many cases the add-on will still work, so give it a try in a test site before upgrading your production site.

3. Upgrade Confluence in a test environment

  1. 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.
      
  2. Follow the steps below to upgrade your test environment.  
      

  3. Test any unsupported add-ons, customizations (such as custom theme or layouts) and proxy configuration (if possible) before upgrading your production environment.   

Upgrade Confluence

4. Back up 

  1. 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. 
      
  2. Back up your installation directory and home directory
      

      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 appropriate file for your operating system - https://www.atlassian.com/software/confluence/download

6. Extract the file and upgrade Confluence

  1. Stop Confluence.
      
  2. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to your existing installation directory)
    Note: There are some known issues with unzipping the archive on Windows. We recommend using 7Zip or Winzip.
      
  3. Edit  <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.properties file to point to your existing Confluence home directory.
      

  4. Copy your jdbc driver jar file from your existing Confluence installation directory to confluence/WEB-INF/lib in your new installation directory. 
      
  5. There are some additional steps you make need to take if:
    • you are running Confluence as a Windows Service

        Click here to expand...

      If you are running Confluence as a Windows service, go to the command prompt and type:  

      <Installation-Directory>\bin\service.bat remove Confluence

      It is vital that you stop and remove the existing service prior to uninstalling the old instance of Confluence. For more information on running Confluence as Windows service, please refer to Start Confluence Automatically on Windows as a Service.

      (warning) To remove the service installed by the Confluence installer, you'll need to run <confluence auto installer installation folder>\UninstallService.bat.

    • you use a JIRA application or LDAP for user management

        Click here to expand...

      If you use JIRA or LDAP for user management, copy the following files from your existing installation directory to your new installation directory:

      • <Installation-Directory>/confluence/WEB-INF/classes/osuser.xml

      • <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml

    • you use Crowd for user management

        Click here to expand...

      If you are using Crowd for user management, copy the following files from your existing installation directory to your new installation directory:

      • <Installation-Directory>/confluence/WEB-INF/classes/osuser.xml

      • <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml (if you are upgrading from Confluence 2.2 or later).

      • <Installation-Directory>/confluence/WEB-INF/classes/crowd.properties
    • You are running Confluence on a different port (not the default 8090)
       

        Click here to expand...

      If you are not running Confluence on port 8090 update  <Installation-Directory>\conf\server.xml file to include your ports.

  6. Start your new Confluence. You should not see the setup wizard.  

After the upgrade

7. Re-apply any modifications

If you have customized Confluence (such as an SSL configuration in the server.xml file, or CATALINA_OPTS or JAVA_OPTS parameters in your confluence-init.properties file), you'll need to perform the following steps after the upgrade is complete:

  1. Stop your upgraded Confluence instance.
  2. Reapply the customizations to the relevant files in the newly upgraded Confluence Installation directory.
  3. 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 unsuable.

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

  Some common issues while upgrading...

 

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

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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport