Upgrading

See Upgrade.

Part 1 Upgrading the distribution

Method Demo Upgrading from the Demo package

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