There are different parts of XWiki that you may want to upgrade:

• Upgrading the standard distribution
• Upgrading from the Debian package
  • Update packages index
  • Package upgrade
  • Pages upgrade
• Upgrading the webapp
  • Invalid Extensions
• Upgrading wiki documents
  • Manual Upgrade
  • Let's clean it up
• Alternative: Export and Reimport
• Downgrading

Upgrading the standard distribution

If you've installed the standard distribution (exe, zip or jar distribution) and you wish to upgrade it, the simplest is to download the new version and install it as you did the first time. Just make sure you don't install the new version over the old one (both installations need to exist).

Then copy the configuration files and the permanent directory from the old installation to the new one (WarningBest is to not copy the solr/ subdirectory since the SOLR schema could have changed and it's best to let XWiki reindex using the new schema). Ideally you should not copy over the configuration files exactly since the new version could have added new configuration options and thus ideally you should do a merge instead of a pure copy. Another strategy is to use the new configuration files, not copy over the old configuration files and instead manually edit the new configuration to make the same changes as you have may done before (If you've never touched the configuration files then there's nothing to do obviously!).

If you're on a unix system here are some commands that may help you doing the merge instead of doing it fully manually:

Upgrading from the Debian package

Update packages index

Package upgrade

Usually you will do:

This will upgrade all packages, not just XWiki. If you want to avoid all the other packages and only update XWiki, you can use sudo apt-get install xwiki-tomcat8-mysql (change xwiki-tomcat8-mysql for the top level package you installed if you installed something else).

Pages upgrade

However after upgrading you still need to install the new UI; see Upgrading wiki documents below.

Upgrading the webapp

The general strategy is to download the new WAR distribution and to replace your current installed WAR with it. However make sure you don't copy on top since this could leave some old files around which would make XWiki fail (like if old JARs are lying around in WEB-INF/lib). In addition you would override some XWiki configuration files located in WEB-INF (xwiki.properties and xwiki.cfg to name just two).

Thus, before replacing your current WAR, make sure you back it up, including configuration and data files.

Also you need to ensure that you use the same XWiki Permanent directory (configured in WEB-INF/xwiki.properties using the environment.permanentDirectory property). WarningBest is to not copy the solr/ subdirectory since the SOLR schema could have changed and it's best to let XWiki reindex using the new schema

Some additional operations may be required for upgrading and you must check the release notes for all the versions from the version you're upgrading from up to the new version you're installing. It's also possible that new features are available and that some configuration files need to be modified. If this is the case then it'll be specified in the release notes.

Invalid Extensions

Also note that when you upgrade, some extensions that were previously valid may become invalid  (for example they may have been renamed, removed or have versions that do not match the version of the WAR you've installed as is the case with the example below). In this case you'll see in the console messages such as:

These are just warnings and don't affect that stability of your instance. Actually the Distribution Wizard you get (see the next section on "Upgrading wiki documents") will ask you to upgrade those invalid extensions and will remove the old versions that became invalid.

Upgrading wiki documents

Starting with XWiki 4.3+ the recommended way to upgrade an XWiki installation is to use the Distribution Wizard which is automatically triggered after you upgrade the XWiki WAR. It allows you to automatically upgrade extensions installed in your wiki, supporting automatic merges and conflict resolution.

Prior to XWiki 4.3 you had to perform this manually as explained below.

Manual Upgrade

As mentioned in the Installing the Default Wiki XAR section you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:

• XWiki.XWikiPreferences: This page contains some configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll lose any customization you may have made such as the skin to use, the rights for your wiki, etc.
• XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space
• XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups
• XWiki.Admin: This page contains the Admin user with the default password. If you import it you'll create a security hole. Thus it's very important not to import this page
• *.*Config: These are configuration pages and thus must not be overwritten. Some examples:
  • XWiki.RegistrationConfig: Contains Registration configuration of your wiki
  • Invitation.InvitationConfig: Configuration for the Invitation Application
• XWiki.XWikiServerXwiki (multi wiki): This page contains the server descriptors and wiki properties
• Any other page you have modified, such as Main.WebHome, a modified Panel, etc.

Let's clean it up

• Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using jar xvf xwiki-enterprise-web-3.1.war or avoid this step if you performed an export/import data migration (you already expanded it)
• Merge your old configuration files you have backed up (see above) with the new versions. Take care that if some changes were already made (probably because of database configuration when you installed the JDBC drivers) they could be lost, so take care when making these changes
• Install this new folder as the xwiki application in your servlet container (by copying the folder to the servlet filesystem space or by packing it in a WAR file and deploying it in the container's administration interface)

At this point all is set and you can experience your old wiki data over the new XWiki core!

Alternative: Export and Reimport

There are cases when it's a better solution to export your current content as a XAR and reimport it into a new instance. For example this would be a good solution if you have a very old version of XWiki and wish to move to a new version.

This solution should work because the XWiki project takes great pride in being careful about backward compatibility and content created several years ago should still work well in new versions of XWiki. For example as of now, we still support XWiki Syntax 1.0 (even though it's been replaced by XWiki Syntax 2.0+ several years ago).

Some tips:

• Make sure to only import your own content pages and not the default XWiki pages since you’d overwrite the ones provided in new XWiki install.
• You may get issues when trying to export a large XAR. In that case you may want to try installing one of the Export Extensions but you'll need to verify that the one you install will work on your old version of XWiki.

Downgrading

A previous upgrade may have modified the database schema and the data saved in the permanent directory may also have incompatible changes. Thus the best strategy for downgrading is to export your wiki pages as XAR (the ones having your content, not the default wiki pages provided by the XWiki distribution or installed Extensions). Then install the older XWiki version and re-install optional Extensions that you need. Then reimport your XAR in it.