Wiki source code of Upgrading
Last modified by Thomas Mortagne on 2025/02/05
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | (% class="label label-default" %)Note 1(%%) XWiki provides migration paths to upgrade from any older version to any newer one. You don't need to upgrade to intermediary versions. | ||
| 6 | |||
| 7 | (% class="label label-default" %)Note 2(%%) It's also good to check the [[Release Notes>>xwiki:ReleaseNotes.WebHome]] for the versions between your old version and the new version you're upgrading to. You should pay an extra care about the section in the release notes entitled ##"Issues specific to XWiki <version>"##. For example, it's important to check if the new version of XWiki you're upgrading to has new [[hardware of software requirements>>Documentation.AdminGuide.Installation.WebHome||anchor="HHardwareandSoftwarerequirements"]]. | ||
| 8 | |||
| 9 | (% class="label label-primary" %)Backup(%%) Before you proceed, be sure to [[backup>>xwiki:Documentation.AdminGuide.Backup]] all of your data, just in case something goes wrong with the update / downgrade. Depending on your usage, you should be backing up your information regularly. | ||
| 10 | |||
| 11 | (% class="label label-primary" %)Extensions(%%) Before upgrading XWiki itself it's generally a good idea to make sure that all your extensions are up to date since new versions might contain compatibility fixes that would have otherwise preventing the new version fully start. | ||
| 12 | |||
| 13 | = Upgrading = | ||
| 14 | |||
| 15 | Keep your XWiki instance up to date to benefit from the best new features and keep your data safe from security threats. There are multiple methods to upgrade XWiki depending on how many data you need to migrate or how experienced you are with different tools. | ||
| 16 | |||
| 17 | In the majority of cases an upgrade consists of two parts: | ||
| 18 | |||
| 19 | * Part 1: Upgrading the //distribution// on the //server / filesystem// and | ||
| 20 | * Part 2: Upgrading the //flavor (wiki pages)// from a //browser//. | ||
| 21 | |||
| 22 | ---- | ||
| 23 | |||
| 24 | == (% class="label label-primary" %)Part 1(%%) Upgrading the distribution == | ||
| 25 | |||
| 26 | {{velocity}} | ||
| 27 | #if ("$!request.get('method')" != '') | ||
| 28 | === (% class="label label-default" %)Method $request.get('method')(%%) Upgrading from the $request.get('method') package === | ||
| 29 | |||
| 30 | {{display reference="Documentation.AdminGuide.Upgrade.Upgrade${request.get('method')}.WebHome"/}} | ||
| 31 | #else | ||
| 32 | === (% class="label label-default" %)Method 1.A(%%) Upgrading from the Debian package (% class="badge fill-gray pull-right" id="HUpgradingfromtheDebianpackage" %).DEB(%%) === | ||
| 33 | |||
| 34 | {{display reference="Documentation.AdminGuide.Installation.InstallationViaAPT.WebHome" section="HUpgrading"/}} | ||
| 35 | |||
| 36 | === (% class="label label-default" %)Method 1.B(%%) Upgrading from Docker (% class="badge fill-gray pull-right" %).Docker(%%) === | ||
| 37 | |||
| 38 | {{display reference="Documentation.AdminGuide.Upgrade.UpgradeDocker.WebHome"/}} | ||
| 39 | |||
| 40 | === (% class="label label-default" %)Method 1.C(%%) Upgrading the WAR (% class="badge fill-gray pull-right" %).WAR(%%) === | ||
| 41 | |||
| 42 | {{display reference="Documentation.AdminGuide.Upgrade.UpgradeWAR.WebHome"/}} | ||
| 43 | |||
| 44 | === (% class="label label-default" %)Method 1.D(%%) Upgrading the demo package (% class="badge fill-gray pull-right" %).ZIP(%%) === | ||
| 45 | |||
| 46 | {{display reference="Documentation.AdminGuide.Upgrade.UpgradeDemo.WebHome"/}} | ||
| 47 | #end | ||
| 48 | {{/velocity}} | ||
| 49 | |||
| 50 | ---- | ||
| 51 | |||
| 52 | == (% class="label label-primary" id="HUpgradingwikidocuments" %)Part 2(%%) Upgrading the flavor == | ||
| 53 | |||
| 54 | === Using Distribution Wizard === | ||
| 55 | |||
| 56 | (% class="label label-success" %)Recommended(%%) The recommended way to upgrade an XWiki installation is to use the [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]] which is automatically triggered after you upgrade the XWiki WAR (you need to be logged with a user having admin rights). It allows you to automatically upgrade extensions installed in your wiki, supporting automatic merges and conflict resolution. | ||
| 57 | |||
| 58 | If you're upgrading an XWiki far (i.e. a wiki with multiple sub-wikis), you'll need to navigate to each subwiki. You'll then be presented with the Distribution Wizard for each wiki that requires an upgrade. | ||
| 59 | |||
| 60 | {{warning}} | ||
| 61 | Make sure you run the Distribution Wizard (DW) with a user having Programming Rights. The following pages require being saved by a user having Programming Rights to work correctly and they may happen to have been modified and thus the DW may need to modify them: | ||
| 62 | |||
| 63 | * ##AppWithinMinutes.DynamicMessageTool## (kept for backward-compatibility, not used) | ||
| 64 | * ##AnnotationCode.Style## | ||
| 65 | * ##AppWithinMinutes.LiveTableEditSheet## | ||
| 66 | * ##AppWithinMinutes.ClassEditSheet## | ||
| 67 | * ##AnnotationCode.Script## | ||
| 68 | * ##XWiki.OfficeImporterAdmin## | ||
| 69 | * ##Filter.WebHome## | ||
| 70 | * ##WikiManager.Translations## | ||
| 71 | |||
| 72 | If you have already done the upgrade with a user not having Programming Rights, then log in with a user having those permissions (or ask someone who has them), [[navigate to those pages>>xwiki:FAQ.How can I navigate to a given page]], edit them (using the wiki editor preferably) and save them without any modification. | ||
| 73 | {{/warning}} | ||
| 74 | |||
| 75 | ---- | ||
| 76 | |||
| 77 | == (% class="label label-default" %)Alternative(%%) Start fresh, plus Export and Reimport your data == | ||
| 78 | |||
| 79 | There are cases when all you can do is [[export your current content as a XAR>>xwiki:Documentation.AdminGuide.ImportExport]] and [[reimport it>>xwiki:Documentation.AdminGuide.ImportExport]] into [[a new instance>>xwiki:Documentation.AdminGuide.Installation]]. You should use this method when you know exactly what content you have created and you manually check to not forget anything on the old instance. | ||
| 80 | |||
| 81 | {{warning}} | ||
| 82 | It's usually not recommended because it means bypassing completely the automatic migration of data which is often not a good idea because it might make some data unreachable because they need to be changed for some reason (the filesystem attachment are stored in a different path, some data changed from String to List, etc.). | ||
| 83 | |||
| 84 | If your use case is that you want to move XWiki to a different server and upgrade it you should do it in two step: | ||
| 85 | * move XWiki to the new verison in the exact same version and make sure all is working as expected | ||
| 86 | * upgrade XWiki as explained in previous sections | ||
| 87 | {{/warning}} | ||
| 88 | |||
| 89 | Some tips: | ||
| 90 | |||
| 91 | * 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. | ||
| 92 | * 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>>extensions:Main.Tags||queryString="do=viewTag&tag=export"]] but you'll need to verify that the one you install will work on your old version of XWiki. | ||
| 93 | |||
| 94 | ---- | ||
| 95 | |||
| 96 | = Downgrading = | ||
| 97 | |||
| 98 | {{warning}} | ||
| 99 | You should try to upgrade to a version that fixes the issue you're facing instead of downgrading. However if you really need to downgrade, read on... | ||
| 100 | {{/warning}} | ||
| 101 | |||
| 102 | 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 using the [[Alternative Method>>.||anchor="HAlternativeStartfresh2CplusExportandReimportyourdata"]], and that consists of [[exporting your wiki pages as XAR>>xwiki:Documentation.AdminGuide.Backup||anchor="HUsingtheXWikiExportfeature"]] (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. | ||
| 103 | |||
| 104 | = Troubleshooting = | ||
| 105 | |||
| 106 | == XWiki won't start without any error in the log and stay stuck on Solr initialization == | ||
| 107 | |||
| 108 | 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 {{code language="properties"}}loadOnStartup=false{{/code}} | ||
| 109 | |||
| 110 | == XWiki startup failed due to previous errors == | ||
| 111 | |||
| 112 | 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: | ||
| 113 | |||
| 114 | {{code langugae="none"}} | ||
| 115 | Context [/xwiki] startup failed due to previous errors | ||
| 116 | {{/code}} | ||
| 117 | |||
| 118 | then it might be the servlet container still uses the previous java version. | ||
| 119 | For Tomcat the path to the java version in use is displayed soon after start in a line like: | ||
| 120 | |||
| 121 | {{code langugage="none"}} | ||
| 122 | [info] JVM Version: 11.0.21+9-post-Ubuntu-0ubuntu122.04 | ||
| 123 | {{/code}} | ||
| 124 | |||
| 125 | Here the first number (the "11" of the "11.0.21+9-...") indicated that tomcat is still running Java11 instead of e.g. Java17 | ||
| 126 | |||
| 127 | This problem can be caused by various sources, like a hard wired ##JAVA_HOME## in some configuration file (like. ##/etc/default/tomcat9##). | ||
| 128 | |||
| 129 | 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: | ||
| 130 | |||
| 131 | {{code language="none"}} | ||
| 132 | # ls -l /usr/lib/jvm/ | ||
| 133 | lrwxrwxrwx 1 root root 25 Dec 30 2018 default-java -> java-1.11.0-openjdk-amd64 | ||
| 134 | lrwxrwxrwx 1 root root 21 Jan 17 2020 java-1.11.0-openjdk-amd64 -> java-11-openjdk-amd64 | ||
| 135 | drwxr-xr-x 7 root root 4096 Jan 24 15:49 java-11-openjdk-amd64 | ||
| 136 | lrwxrwxrwx 1 root root 21 Jan 31 00:08 java-1.17.0-openjdk-amd64 -> java-17-openjdk-amd64 | ||
| 137 | drwxr-xr-x 7 root root 4096 Feb 3 22:59 java-17-openjdk-amd64 | ||
| 138 | {{/code}} | ||
| 139 | |||
| 140 | then you neeed to update the ##default-java## link explicitely e.g. by: | ||
| 141 | |||
| 142 | {{code language="none"}} | ||
| 143 | # cd /usr/lib/jvm | ||
| 144 | # rm default-java; ln -s java-17-openjdk-amd64 default-java | ||
| 145 | {{/code}} |
