Upgrading

See Upgrade.

Part 1 Upgrading the distribution

Method Debian Upgrading from the Debian package

• Update packages index:

  sudo apt update

• Package upgrade:

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

  Troubleshooting

  apt upgrade won't upgrade xwiki packages

  Sometimes (especially in case of new cycle), apt upgrade might report that it refuse to upgrade some xwiki packages.

  This is generally the sign that either:

  • a new dependency cannot be found: it generally means that XWiki starts requiring a more recent version of Java and the Debian repository you have don't have any implementation of this Java versions. See No package can be found for Java for more details on how to resolve this situation.
  • some xwiki package name changed: this generally happen when XWiki stops supporting some version of Tomcat and you need to install a different xwiki-tomcat* package (for example XWiki 17 does not support tomcat9 and requires the tomcat10 package)
• Pages upgrade:

  However after upgrading you still need to install the new UI; see next step Upgrading the flavor below.

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