Wiki Markup

One of the the major differences between Confluence 3.5 and newer versions is the migration of wiki markup to our new editor. We understand that you may still require wiki markup from time to time and we feel that the following resources will make things easier:

• Confluence 4 Editor - What's Changed for Users of the Old Rich Text Editor
  
  • The editor auto converts wiki markup to the new formatting.
  • The editor has the ability to Insert > Wiki Markup.
• Bob Swift's Wiki Markup Addon allows you to preserve wiki markup if necessary.  This plugin is currently offered free of charge.
• API Changes - Confluence now stores information in an XHTML format, which means that scripted behavior against the Confluence API will break.  We have provided the convertWikiToStorageFormat method to ease the transition.

Preparing to upgrade

1. Check if your currently installed Plugins are compatible with the chosen target Confluence version

Verify whether a compatible version of the plugin is available in Confluence 5.1.4.  We've made this easy for you: This information is available via the Confluence Upgrade Check in the plugin administration section of Confluence. See the documentation: Checking app compatibility with application updates. You can also check the respective home pages for these plugins on the Atlassian Marketplace.

2. Test the upgrade in a staging environment before upgrading your production instance

This will allow you to anticipate any unexpected behavior during the upgrade. Testing will also allow you to plan the upgrade of the production instance, as it will give you a better understanding of how long the upgrade will take and how much time you will need to re-install Plugins and re-apply any customisation.

3. Check the Upgrade Notes for the 3.5 to 5.1 Upgrade

Make sure that you are aware of the changes listed in the Simplified Upgrade Notes - Upgrading from 3.5 to 5.1 page. These Upgrade Notes are a summary of important changes in the platforms supported by Confluence and information to be considered during the upgrade.

4. Prepare your team

Confluence 5 introduced significant changes to the user experience. To help you manage the change in your organization, we have provided the Planning for Confluence 5 guide to help prepare your team. 

Upgrading Confluence

This is a simplified version of the Confluence Upgrade process. A more detailed guide is available here.

The following instructions will help you to run the upgrade in two steps, on Windows or Linux environments:

1. Upgrade from 3.5 to 5.0.3.
2. Upgrade from 5.0.3 to 5.1.4.

This means that you will run the following steps twice. First, to upgrade from 3.5 to 5.0.3 and then a second time to upgrade from 5.0.3 to 5.1.4.

Upgrading Confluence on Windows

1. Download the Confluence Windows Installer (.exe) file (for the new version of Confluence) from the Confluence Download Center.
2. Run the .exe file to start the upgrade wizard.
   If a Windows 7 (or Vista) 'User Account Control' dialog box requests if you want to allow the upgrade wizard to make changes to your computer, specify 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.
3. At the 'Upgrading Confluence?' step, choose the 'Upgrade an existing Confluence installation' option.
4. In the 'Existing Confluence installation directory' field, specify the Confluence Installation Directory of your Confluence installation to be upgraded.
   The upgrade wizard will attempt to find an existing Confluence installation and use its location to pre-populate this field. However, always verify this location, particularly if you have multiple Confluence installations running on the same machine.
5. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
   1. At the 'Back up Confluence directories' step, ensure the 'Back up Confluence home' option is selected. This creates 'zip' archive file backups of your existing Confluence Installation and Confluence Home Directories in their respective parent directory locations.
      Please Note: Choosing this option is strongly recommended!
   2. At this point, the upgrade wizard notes any customisations in your existing installation directory which it cannot automatically migrate to your upgraded Confluence installation. If you are notified by the installer about any files containing such customisations, please make a note of the locations of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded Confluence installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the Confluence Installation Directory.
      Please Note: when upgrading from the version that was not installed by the installer the customisations can only be detected  in the confluence subdirectory of your existing Confluence Installation Directory. Modifications to files in directories other than confluence will not be detected when you upgrade, for example, modifications to conf/server.xml. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover modifications across the whole Confluence Installation Directory.
   3. At the 'Upgrade Check List' step, perform the following steps if you have not already done so:
      
      • Back up your external database.
      • If your Confluence site includes third-party plugins (add-ons), check that they will be compatible with your upgraded Confluence version. See the documentation: Checking app compatibility with application updates.
   4. Choose 'Next', your existing Confluence installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing Confluence installation.
      2. Delete the contents of the existing Confluence Installation Directory.
      3. Install the new version of Confluence to the existing Confluence Installation Directory.
      4. Starts your new (upgraded) Confluence installation.
         If you noted any files that contain customisations which must be migrated manually to your upgraded Confluence installation (above), then:
         1. Stop the upgraded Confluence installation.
         2. Migrate the customisations from these files into the upgraded installation directory. 
         3. Restart the upgraded Confluence installation.
6. At the last step of the upgrade wizard, select the option to launch the upgraded Confluence installation in a browser so you can check the upgrade.

Congratulations, you have completed upgrading your Confluence installation on Windows!

Upgrading Confluence on Linux

1. Download the appropriate Confluence 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your operating system (for the new version of Confluence) from the Confluence Download Center.
2. Open a Linux console and change directory (cd) to the '.bin' file's directory.
   If the '.bin' file is not executable after downloading it, make it executable, for example:
   chmod a+x atlassian-confluence-X.Y.bin
   (where X.Y represents your version of Confluence)
3. Execute the '.bin' file to start the upgrade wizard.
4. When prompted to choose between creating a new Confluence installation or upgrading an existing installation, choose the 'Upgrade an existing Confluence installation' option.
5. Specify the Confluence Installation Directory of your Confluence installation to be upgraded.
   The upgrade wizard will attempt to find an existing Confluence installation and will provide its location as a choice. However, always verify this location, particularly if you have multiple Confluence  installations running on the same machine.
6. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
   1. Choose the option to back up Confluence's directories. This creates 'zip' archive file backups of your existing Confluence Installation and Confluence Home directories in their respective parent directory locations.
      Please Note: Choosing this option is strongly recommended!
   2. At this point, the upgrade wizard notes any customisations in your existing Confluence Installation Directory which it cannot automatically migrate to your upgraded Confluence installation. If you are notified of any files containing such customisations, please make a note of the locations of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded Confluence installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the Confluence Installation Directory.
      Please Note: when upgrading from the version that was not installed by the installer the customisations can only be detected  in the confluence subdirectory of your existing Confluence Installation Directory. Modifications to files in directories other than confluence will not be detected when you upgrade, for example, modifications to conf/server.xml. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover modifications across the whole Confluence Installation Directory.
   3. At the 'Upgrade Check List' step, perform the following steps if you have not already done so:
      
      • Back up your external database.
      • If your Confluence site includes third-party plugins (add-ons), check that they will be compatible with your upgraded Confluence version. See the documentation: Checking app compatibility with application updates.
   4. Upon proceeding, your existing Confluence installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing Confluence installation.
      2. Delete the contents of the existing Confluence installation directory.
      3. Install the new version of Confluence to the existing Confluence installation directory.
      4. Starts your new (upgraded) Confluence installation.
         If you noted any files that contain customisations which must be migrated manually to your upgraded Confluence installation (above), then:
         1. Stop the upgraded Confluence installation.
         2. Migrate the customisations from these files into the upgraded Confluence Installation Directory.
         3. Restart the upgraded Confluence installation.
7. The last step of the upgrade wizard provides you with a link to launch the upgraded Confluence installation in a browser, so you can check the upgrade.

Congratulations, you have completed upgrading your Confluence installation on Linux!

Possible issues during the upgrade

Known issues upgrading to Confluence 5

CONF-26596 - Getting issue details... STATUS

CONF-23287 - Getting issue details... STATUS

CONF-28495 - Getting issue details... STATUS

CONF-28818 - Getting issue details... STATUS

Getting help

• Check for known issues. Please check the known issues for the relevant release on this page of the Knowledge Base and follow the instructions to solve the problem.
• Check for answers from the community. Other users may have encountered the same issue. You can check for answers from the community at Atlassian Answers.
• Did you encounter a problem during the Confluence upgrade? Please refer to the guide to troubleshooting upgrades in the Confluence Knowledge Base.
• If you encounter a problem and cannot solve it, please create a support ticket and one of our support engineers will help you.