Upgrading Confluence

This document describes the procedure for upgrading to the latest version of Confluence on Windows or Linux.

Step 1 Determine your upgrade path and method

There are several factors that will determine the upgrade method you should use. If you:

• Are upgrading from a version earlier than Confluence 3.5 you will need to upgrade manually. You can contact Support for help determining an appropriate upgrade path.
• Are moving to a different operating system or file location you should upgrade manually.
• Currently use the EAR/WAR distribution to deploy Confluence into an existing application server, you can only upgrade manually.
• Are moving to a different database you should upgrade using the installer first and then follow the procedure outlined in migrating to a different database.
• Have a clustered instance of Confluence you should follow the procedure outlined in Upgrading Confluence Data Center.
• 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 HSQLDB database for more information.

otherwise you should follow the instructions below and use the Windows or Linux installer to upgrade Confluence.

Step 2 Upgrade Confluence in a test environment

We strongly recommend you recreate your production instance and test the upgrade in this cloned environment.

1. Create a snapshot of your current production Confluence environment on a test server - see Moving Confluence Between Servers for how to do this.
2. Follow the steps below to perform the upgrade on your cloned environment.
3. Test all your unsupported add-ons (plugins) and any customisation (for example custom themes and layouts) with the new version before proceeding with the upgrade in your production environment.

Step 3 Back up 

Before you begin the Confluence upgrade you must back up:

• your external database
  You must perform a manual backup of your external database and confirm that the backup was created properly. If you are unfamiliar with the backup-restore facilities of your database, you can simply restore the backup to a different system to ensure the backup worked before proceeding.
• your Confluence Home directory
  The Confluence Home directory is the folder where Confluence stores its configuration information, search indexes and page attachments.  The location of the Home directory is stored in a configuration file called confluence-init.properties, which is located inside the confluence/WEB-INF/classes directory in your Confluence Installation directory.
  if you store attachments outside the Confluence Home directory, you should also backup your attachments directory. 
• the Confluence installation directory 
  This is where the Confluence application files and libraries were unpacked (unzipped) when Confluence was originally installed.

The installation wizard will back up your Confluence directories as part of the installation process, but you should also back these directions up manually before starting the upgrade. 

Step 4 Upgrade Confluence in your production environment

1. Download the appropriate Windows or Linux installer from the Confluence Download Center.
2. Start the installer:
   • Windows Users:  run the .exe file.
     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.
   • Linux users: open a Linux console and change directory (cd) to the directory you saved the '.bin' file and then execute the '.bin' file. 
     If the '.bin' file is not executable after downloading it, make it executable, for example chmod a+x atlassian-confluence-5.6.1-x64.bin (specify the exact filename of the installer you downloaded).
3. The installation wizard will guide you through the upgrade process.  Some things to note:
   1. When prompted choose Upgrade an existing Confluence installation (for Linux users this is option 3).
   2. Verify that the Existing Confluence installation directory suggested by the wizard is correct. This is especially important if you have multiple Confluence installations running on the same machine.
   3. At the 'Back up Confluence directories' step, ensure 'Back up Confluence home' is selected. This will create a .zip backup of the Confluence home and installation directories. This is strongly recommended.
   4. The installation wizard will notify you of customisations in the Confluence Installation directory. Make a note of these before proceeding as you will need to manually reapply these customisations after the upgrade is complete.
   5. If you have not already done so, the wizard will prompt you to backup your external database and check plugin compatibility. If your database does not support online backups you will need to stop the installation wizard at this point.
4. 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.

During the upgrade the wizard will migrate following from your existing Confluence installation:

• TCP port values in your server.xml file. 
• Custom values in your confluence-init.properties (confluence.home property) and setenv.sh / setenv.bat files (CATALINA_OPTS or JAVA_OPTS parameters) 

If you are 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.

 Other configurations or customisations (including any other modifications in the server.xml file) are not migrated during the upgrade and need to be reapplied manually. See below for more information.

Additional steps when customisations are present

The installation wizard's ability to notify you about customisations 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). 

If customisations are present you will need to perform the following steps after the upgrade is complete:

1. Stop the upgraded Confluence instance.
2. Reapply the customisations to the relevant files in the upgraded Confluence Installation directory.
3. Restart the upgraded Confluence instance.

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

Troubleshooting

Some common issues encountered while upgrading:

• Cannot proceed with upgrade because license has expired
   If your licence 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.
• Unable to 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.

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