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.
  • Rolling upgrade - upgrade your Data Center cluster to the latest available bug fix version, with no downtime.

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

Error rendering macro 'includeplus'

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

Are you eligible to upgrade?

Tell me more...

Error rendering macro 'includeplus'

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

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 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?
Tell me more...

Error rendering macro 'includeplus'

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

Plan your upgrade

1. Determine your upgrade path

Error rendering macro 'includeplus'

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

2. Complete the pre-upgrade checks

Error rendering macro 'includeplus'

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

3. Upgrade Confluence in a test environment

Error rendering macro 'includeplus'

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

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. 
     
    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.
      
  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.
    See Using read-only mode for site maintenance if you need to provide uninterrupted access.
      
  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. If you're using an Oracle or MySQL database, you'll need to 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 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. Reinstall the service (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. 

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

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

Error rendering macro 'includeplus'

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

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

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

Last modified on Oct 6, 2021

Was this helpful?

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