Upgrading

See Upgrade.

Part 1 Upgrading the distribution

Method 1.A Upgrading from the Debian package .DEB

Upgrading

Update the packages index

sudo apt update

[Optional] Uninstall conflicting version of tomcat packages

In the case of the tomcat based packages, if you are moving from one version of Tomcat to another (which is generally needed when XWiki increase its minimum supported version), you may need to first uninstall the previous version. This is because two different versions of Tomcat cannot run at the same time by default.

Of course, you can skip this step if you are not using the Tomcat based package, not changing the version of Tomcat, or if you configured Tomcat specifically to allow having several versions running at the same time.

• Stop the running instance of tomcat (Warningchange the version to match the previous version of Tomcat you are upgrading from):

  sudo systemctl stop tomcat9

• Uninstall Tomcat (which will also uninstall the xwiki packages which rely on this version of Tomcat):

  sudo apt remove tomcat9

• Then you will need to install the new package (Warningmodify the package name to match the version of Tomcat you are upgrading to, and the database you were already using):

  sudo apt install xwiki-tomcat10-mariadb

Upgrade the packages

sudo apt upgrade

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 install xwiki-tomcat10-mariadb (change xwiki-tomcat10-mariadb for the top level package you installed if you installed something else).

Upgrade the pages

Like in the case of the install, you still have to go through the Distribution Wizard. See more details on Upgrading the flavor.

Method 1.B Upgrading from Docker .Docker

• If you've installed XWiki by using the official XWiki Docker image, follow the instructions there for upgrading it.

Method 1.C Upgrading the WAR .WAR

• 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).
• 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.
• See Database Upgrade.

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

  2013-12-02 11:43:01,688 [localhost-startStop-1] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.enterprise:xwiki-enterprise-ui-common-5.2.1] on namespace [wiki:xwiki]
  2013-12-02 11:43:01,688 [localhost-startStop-1] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.platform:xwiki-platform-workspace-ui-5.2.1] on namespace [wiki:xwiki]
  2013-12-02 11:43:01,688 [localhost-startStop-1] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.enterprise:xwiki-enterprise-ui-mainwiki-5.2.1] on namespace [wiki:xwiki]
  2013-12-02 11:43:01,689 [localhost-startStop-1] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.enterprise:xwiki-enterprise-ui-wiki-all-5.2.1] on namespace [wiki:workspacetemplate]

  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.

Method 1.D Upgrading the demo package .ZIP

See Upgrade the demo package. 

See Unix Merge Configuration Files.

See Database Upgrade.

Part 2 Upgrading the flavor

Using Distribution Wizard

Recommended

See Upgrade the Standard Flavor of the Wiki using the Distribution Wizard.

See Programming Rights Impact on Distribution Wizard.

Alternative Start fresh, plus Export and Reimport your data

See Upgrade the Flavor using the Export/Import Method.

Downgrading

See Downgrade your Wiki.

Troubleshooting

XWiki won't start without any error in the log and stay stuck on Solr initialization

Solr has a tendency to lock itself when it has several cores to initialize. To workaround that, XWiki started creating new cores with an option to disable loading the core during Solr init (it's loaded during its first use), but you might still have some existing cores without this option set, in which case you will have to set it by hand: go to <permdir>/store/solr/ and edit each core core.properties file to add loadOnStartup=false

XWiki startup failed due to previous errors

If XWiki fails to start after an upgrade that requires an upgrade of the java version (i.e. when upgrading to 16.x, which requires a switch to Java17), and the servlet container only shows a failue when starting the webapp, like:

  Context [/xwiki] startup failed due to previous errors

then it might be the servlet container still uses the previous java version.
For Tomcat the path to the java version in use is displayed soon after start in a line like:

  [info] JVM Version:           11.0.21+9-post-Ubuntu-0ubuntu122.04

Here the first number (the "11" of the "11.0.21+9-...") indicated that tomcat is still running Java11 instead of e.g. Java17

This problem can be caused by various sources, like a hard wired JAVA_HOME in some configuration file (like. /etc/default/tomcat9).

For Debian based distributions it seems one symbolic link in /usr/lib/jvm is not changed an needs to be updated manually. If you get an output like:

# ls -l /usr/lib/jvm/
lrwxrwxrwx 1 root root   25 Dec 30  2018 default-java -> java-1.11.0-openjdk-amd64
lrwxrwxrwx 1 root root   21 Jan 17  2020 java-1.11.0-openjdk-amd64 -> java-11-openjdk-amd64
drwxr-xr-x 7 root root 4096 Jan 24 15:49 java-11-openjdk-amd64
lrwxrwxrwx 1 root root   21 Jan 31 00:08 java-1.17.0-openjdk-amd64 -> java-17-openjdk-amd64
drwxr-xr-x 7 root root 4096 Feb  3 22:59 java-17-openjdk-amd64

then you neeed to update the default-java link explicitely e.g. by:

# cd /usr/lib/jvm
# rm default-java; ln -s java-17-openjdk-amd64 default-java