Wiki source code of Upgrading

Last modified by Vincent Massol on 2023/11/14

Hide last authors
Ecaterina Moraru (Valica) 21.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
Thomas Mortagne 2.1 2 {{toc/}}
Ecaterina Moraru (Valica) 21.2 3 {{/box}}
Guillaume Fenollar 1.1 4
Ecaterina Moraru (Valica) 30.1 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.
Vincent Massol 29.1 6
Vincent Massol 45.2 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"]].
Vincent Massol 29.1 8
Ecaterina Moraru (Valica) 30.1 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.
Clemens Robbenhaar 14.1 10
Alex Cotiugă 43.1 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.
Thomas Mortagne 37.1 12
Ecaterina Moraru (Valica) 30.1 13 = Upgrading =
Thomas Mortagne 18.1 14
Ecaterina Moraru (Valica) 30.1 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
Vincent Massol 45.2 17 In the majority of cases an upgrade consists of two parts:
Ecaterina Moraru (Valica) 30.1 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
Ecaterina Moraru (Valica) 31.3 26 === (% class="label label-default" %)Method 1.A(%%) Upgrading from the Debian package (% class="badge fill-gray pull-right" id="HUpgradingfromtheDebianpackage" %).DEB(%%) ===
Ecaterina Moraru (Valica) 30.1 27
28 * (((
29 Update packages index:
30
Thomas Mortagne 18.1 31 {{code language="bash"}}
Clemens Robbenhaar 14.1 32 sudo apt-get update
Thomas Mortagne 18.1 33 {{/code}}
Ecaterina Moraru (Valica) 30.1 34 )))
Thomas Mortagne 18.1 35
Ecaterina Moraru (Valica) 30.1 36 * (((
37 Package upgrade:
Thomas Mortagne 18.1 38
39 {{code language="bash"}}
Clemens Robbenhaar 14.1 40 sudo apt-get upgrade
41 {{/code}}
42
Ecaterina Moraru (Valica) 30.1 43 This will upgrade all packages, not just XWiki. If you want to avoid all the other packages and only update XWiki, you can use {{code}}sudo apt-get install xwiki-tomcat8-mysql{{/code}} (change xwiki-tomcat8-mysql for the top level package you installed if you installed something else).
Clemens Robbenhaar 14.1 44
Thomas Mortagne 18.1 45 {{warning}}
Ecaterina Moraru (Valica) 30.1 46 When upgrading from pre 9.5 version {{code}}apt-get upgrade{{/code}} won't find anything because the package name changed ([[XWiki Enterprise does not exist anymore>>xwiki:Blog.XWiki Enterprise is dead, long live XWiki!]]).
Clemens Robbenhaar 14.1 47
Ecaterina Moraru (Valica) 30.1 48 All you have to do in this case is install the ##xwiki-tomcat*## package corresponding to the top level ##xwiki-enterprise-tomcat*## one you installed previously. For example if you had ##xwiki-enterprise-tomcat8-mysql## 9.4 you should do {{code}}sudo apt-get install xwiki-tomcat8-mysql{{/code}}.
Thomas Mortagne 18.1 49 {{/warning}}
Ecaterina Moraru (Valica) 30.1 50 )))
Thomas Mortagne 18.1 51
Ecaterina Moraru (Valica) 30.1 52 * (((
53 Pages upgrade:
Thomas Mortagne 18.1 54
Ecaterina Moraru (Valica) 30.1 55 However after upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
56 )))
Thomas Mortagne 18.1 57
Ecaterina Moraru (Valica) 30.1 58 === (% class="label label-default" %)Method 1.B(%%) Upgrading from Docker (% class="badge fill-gray pull-right" %).Docker(%%) ===
Guillaume Fenollar 1.1 59
Vincent Massol 35.2 60 * If you've installed XWiki by using the official XWiki Docker image, [[follow the instructions there>>https://github.com/xwiki-contrib/docker-xwiki/blob/master/README.md#upgrading-xwiki]] for upgrading it.
Guillaume Fenollar 1.1 61
Ecaterina Moraru (Valica) 30.1 62 === (% class="label label-default" %)Method 1.C(%%) Upgrading the webapp (% class="badge fill-gray pull-right" %).WAR(%%) ===
Guillaume Fenollar 1.1 63
Ecaterina Moraru (Valica) 30.1 64 * The general strategy is to [[download the new WAR distribution>>xwiki:Main.Download]] 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).
65
66 * Thus, before replacing your current WAR, make sure you [[back it up, including configuration and data files>>xwiki:Documentation.AdminGuide.Backup]].
67
Vincent Massol 41.3 68 * Also you need to ensure that you use the same XWiki Permanent directory (configured in ##WEB-INF/xwiki.properties## using the ##environment.permanentDirectory## property).
Vincent Massol 13.1 69
Ecaterina Moraru (Valica) 30.1 70 * Some additional operations may be required for upgrading and you must check the [[release notes>>xwiki:ReleaseNotes.WebHome]] 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.
Vincent Massol 3.1 71
Ecaterina Moraru (Valica) 30.1 72 * {{include reference="xwiki:Documentation.AdminGuide.UpgradeDatabase"/}}
Guillaume Fenollar 1.1 73
Ecaterina Moraru (Valica) 30.1 74 * (((
75 **Invalid Extensions**
Vincent Massol 9.1 76
77 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:
78
79 {{code language="noformat"}}
Thomas Mortagne 45.1 80 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]
81 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]
82 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]
83 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]
Vincent Massol 9.1 84 {{/code}}
85
86 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.
Ecaterina Moraru (Valica) 30.1 87 )))
Vincent Massol 9.1 88
Ecaterina Moraru (Valica) 30.1 89 * After upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
Vincent Massol 19.1 90
Ecaterina Moraru (Valica) 30.1 91 === (% class="label label-default" %)Method 1.D(%%) Upgrading the demo package (% class="badge fill-gray pull-right" %).ZIP(%%) ===
Vincent Massol 19.1 92
Ecaterina Moraru (Valica) 30.1 93 * If you've installed the standard distribution (##zip## or ##jar## distribution) and you wish to upgrade it, the simplest is to [[download>>xwiki:Main.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).
Thomas Mortagne 28.1 94
Vincent Massol 41.3 95 * Then copy [[the configuration files and the permanent directory>>xwiki:Documentation.AdminGuide.Backup]] from the old installation to the new one. 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!).
Thomas Mortagne 28.1 96
Ecaterina Moraru (Valica) 30.1 97 * (((
Thomas Mortagne 28.1 98 If you're on a unix system here are some commands that may help you doing the merge instead of doing it fully manually:
99
100 {{code language="none"}}
101 ## Note: We're assuming that "xwiki.new" is a symbolic link that points to the location
102 ## where the new xwiki version is located and that "xwiki" is the location of the previous
103 ## xwiki installation.
104 mv xwiki.new/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori; sudo sdiff xwiki/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori -B -W -E -o xwiki.new/WEB-INF/web.xml
105 mv xwiki.new/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori; sudo sdiff xwiki/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.cfg
106 mv xwiki.new/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori; sudo sdiff xwiki/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.properties
107 mv xwiki.new/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori; sudo sdiff xwiki/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori -B -W -E -o xwiki.new/WEB-INF/struts-config.xml
108 mv xwiki.new/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori; sudo sdiff xwiki/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori -B -W -E -o xwiki.new/WEB-INF/classes/logback.xml
109 {{/code}}
Ecaterina Moraru (Valica) 30.1 110 )))
Thomas Mortagne 28.1 111
Ecaterina Moraru (Valica) 30.1 112 * {{include reference="xwiki:Documentation.AdminGuide.UpgradeDatabase"/}}
Thomas Mortagne 28.1 113
Ecaterina Moraru (Valica) 30.1 114 * After upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
Guillaume Fenollar 1.1 115
Ecaterina Moraru (Valica) 30.1 116 ----
Guillaume Fenollar 1.1 117
Ecaterina Moraru (Valica) 34.1 118 == (% class="label label-primary" id="HUpgradingwikidocuments" %)Part 2(%%) Upgrading the flavor ==
Ecaterina Moraru (Valica) 30.1 119
Thomas Mortagne 31.1 120 === Using Distribution Wizard ===
Ecaterina Moraru (Valica) 30.1 121
Thomas Mortagne 44.1 122 (% 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.
Ecaterina Moraru (Valica) 30.1 123
Vincent Massol 42.1 124 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.
125
Vincent Massol 25.1 126 {{warning}}
127 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:
Vincent Massol 26.1 128
Vincent Massol 26.2 129 * ##AppWithinMinutes.DynamicMessageTool## (kept for backward-compatibility, not used)
130 * ##AnnotationCode.Style##
131 * ##AppWithinMinutes.LiveTableEditSheet##
132 * ##AppWithinMinutes.ClassEditSheet##
133 * ##AnnotationCode.Script##
134 * ##XWiki.OfficeImporterAdmin##
135 * ##Filter.WebHome##
Vincent Massol 28.2 136 * ##WikiManager.Translations##
Thomas Mortagne 35.1 137
Ecaterina Moraru (Valica) 30.1 138 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.
Vincent Massol 25.1 139 {{/warning}}
140
Ecaterina Moraru (Valica) 30.1 141 ----
Guillaume Fenollar 1.1 142
Ecaterina Moraru (Valica) 30.1 143 == (% class="label label-default" %)Alternative(%%) Start fresh, plus Export and Reimport your data ==
Guillaume Fenollar 1.1 144
Thomas Mortagne 40.1 145 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.
Vincent Massol 11.1 146
Thomas Mortagne 40.1 147 {{warning}}
Thomas Mortagne 41.1 148 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.).
149
150 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:
151 * move XWiki to the new verison in the exact same version and make sure all is working as expected
152 * upgrade XWiki as explained in previous sections
Thomas Mortagne 40.1 153 {{/warning}}
154
Vincent Massol 11.1 155 Some tips:
Thomas Mortagne 18.1 156
Vincent Massol 11.1 157 * 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.
Ecaterina Moraru (Valica) 33.2 158 * 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.
Vincent Massol 11.1 159
Ecaterina Moraru (Valica) 30.1 160 ----
161
Vincent Massol 17.1 162 = Downgrading =
163
164 {{warning}}
165 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...
166 {{/warning}}
167
Ecaterina Moraru (Valica) 30.1 168 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.
Thomas Mortagne 38.1 169
Thomas Mortagne 40.1 170 = Troubleshooting =
Thomas Mortagne 38.1 171
Thomas Mortagne 40.1 172 == XWiki won't start without any error in the log and stay stuck on Solr initialization ==
Thomas Mortagne 38.1 173
174 Solr has a tendency to lock itself when it has several cores to initialize. To workaround that XWiki started created new cores with an option to disable loading the core during Solr init (it's loaded during it's first use) but you might still have existing core 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}}

Get Connected