Changes for page Upgrading

Last modified by Vincent Massol on 2023/11/14

<
From version < 29.1 >
edited by Vincent Massol
on 2018/06/19
To version < 30.1 >
edited by Ecaterina Moraru (Valica)
on 2018/10/12
>
Change comment: Improving Upgrade layout

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.evalica
Content
... ... @@ -2,52 +2,77 @@
2 2  {{toc/}}
3 3  {{/box}}
4 4  
5 -= Forewords =
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 6  
7 -* XWiki provides migration paths to upgrade from any older version to any newer one. You don't need to upgrade to intermediary versions.
8 -* 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>".
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>"##.
9 9  
10 -= Upgrading from the Debian package =
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.
11 11  
12 -== Update packages index ==
11 += Upgrading =
13 13  
13 +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.
14 +
15 +In the majority of cases an upgrade consists of two parts:
16 +
17 +* Part 1: Upgrading the //distribution// on the //server / filesystem// and
18 +* Part 2: Upgrading the //flavor (wiki pages)// from a //browser//.
19 +
20 +----
21 +
22 +== (% class="label label-primary" %)Part 1(%%) Upgrading the distribution ==
23 +
24 +=== (% class="label label-default" %)Method 1.A(%%) Upgrading from the Debian package (% class="badge fill-gray pull-right" %).DEB(%%) ===
25 +
26 +* (((
27 +Update packages index:
28 +
14 14  {{code language="bash"}}
15 15  sudo apt-get update
16 16  {{/code}}
32 +)))
17 17  
18 -== Package upgrade ==
34 +* (((
35 +Package upgrade:
19 19  
20 -Usually you will do:
21 -
22 22  {{code language="bash"}}
23 23  sudo apt-get upgrade
24 24  {{/code}}
25 25  
26 -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-get install xwiki-tomcat8-mysql## (change xwiki-tomcat8-mysql for the top level package you installed if you installed something else).
41 +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).
27 27  
28 28  {{warning}}
29 -When upgrading from pre 9.5 version ##apt-get upgrade## won't find anything because the package name changed ([[XWiki Enterprise does not exist anymore>>Blog.XWiki Enterprise is dead, long live XWiki!]]).
44 +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!]]).
30 30  
31 -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 langage="bash"}}sudo apt-get install xwiki-tomcat8-mysql{{/code}}.
46 +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}}.
32 32  {{/warning}}
48 +)))
33 33  
34 -== Pages upgrade ==
50 +* (((
51 +Pages upgrade:
35 35  
36 -However after upgrading you still need to install the new UI; see [[Upgrading wiki documents>>Documentation.AdminGuide.Upgrade#HUpgradingwikidocuments]] below.
53 +However after upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
54 +)))
37 37  
38 -= Upgrading the webapp =
56 +=== (% class="label label-default" %)Method 1.B(%%) Upgrading from Docker (% class="badge fill-gray pull-right" %).Docker(%%) ===
39 39  
40 -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).
58 +* If you've installed XWiki by using the official XWiki Docker image, [[follow the instructions there>>https://hub.docker.com/_/xwiki/]] for upgrading it.
41 41  
42 -Thus, before replacing your current WAR, make sure you [[back it up, including configuration and data files>>Documentation.AdminGuide.Backup]].
60 +=== (% class="label label-default" %)Method 1.C(%%) Upgrading the webapp (% class="badge fill-gray pull-right" %).WAR(%%) ===
43 43  
62 +* 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).
63 +
64 +* Thus, before replacing your current WAR, make sure you [[back it up, including configuration and data files>>xwiki:Documentation.AdminGuide.Backup]].
65 +
66 +* (((
44 44  Also you need to ensure that you use the same XWiki Permanent directory (configured in ##WEB-INF/xwiki.properties## using the ##environment.permanentDirectory## property). {{warning}}Best is to not copy the ##solr/## subdirectory since the SOLR schema could have changed and it's best to let XWiki reindex using the new schema{{/warning}}
68 +)))
45 45  
46 -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.
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.
47 47  
48 -{{include reference="UpgradeDatabase"/}}
72 +* {{include reference="xwiki:Documentation.AdminGuide.UpgradeDatabase"/}}
49 49  
50 -== Invalid Extensions ==
74 +* (((
75 +**Invalid Extensions**
51 51  
52 52  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:
53 53  
... ... @@ -59,17 +59,17 @@
59 59  {{/code}}
60 60  
61 61  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.
87 +)))
62 62  
63 -= Upgrading from Docker =
89 +* After upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
64 64  
65 -If you've installed XWiki by using the official XWiki Docker image, [[follow the instructions there>>https://hub.docker.com/_/xwiki/]] for upgrading it.
91 +=== (% class="label label-default" %)Method 1.D(%%) Upgrading the demo package (% class="badge fill-gray pull-right" %).ZIP(%%) ===
66 66  
67 -= Upgrading the demo package =
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).
68 68  
69 -If you've installed the standard distribution (##zip## or ##jar## distribution) and you wish to upgrade it, the simplest is to 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).
95 +* Then copy [[the configuration files and the permanent directory>>xwiki:Documentation.AdminGuide.Backup]] from the old installation to the new one ({{warning}}Best is to not copy the ##solr/## subdirectory since the SOLR schema could have changed and it's best to let XWiki reindex using the new schema{{/warning}}). 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!).
70 70  
71 -Then copy [[the configuration files and the permanent directory>>Documentation.AdminGuide.Backup]] from the old installation to the new one ({{warning}}Best is to not copy the ##solr/## subdirectory since the SOLR schema could have changed and it's best to let XWiki reindex using the new schema{{/warning}}). 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!).
72 -
97 +* (((
73 73  If you're on a unix system here are some commands that may help you doing the merge instead of doing it fully manually:
74 74  
75 75  {{code language="none"}}
... ... @@ -82,13 +82,20 @@
82 82  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
83 83  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
84 84  {{/code}}
110 +)))
85 85  
86 -{{include reference="UpgradeDatabase"/}}
112 +* {{include reference="xwiki:Documentation.AdminGuide.UpgradeDatabase"/}}
87 87  
88 -= Upgrading wiki documents =
114 +* After upgrading you still need to install the new UI; see next step [[Upgrading the flavor>>.||anchor="HPart2Upgradingtheflavor"]] below.
89 89  
90 -The recommended way to upgrade an XWiki installation is to use the [[Distribution Wizard>>platform:Features.DistributionWizard]] which is automatically triggered after you upgrade the XWiki WAR. It allows you to automatically upgrade extensions installed in your wiki, supporting automatic merges and conflict resolution.
116 +----
91 91  
118 +== (% class="label label-primary" %)Part 2(%%) Upgrading the flavor ==
119 +
120 +=== (% class="label label-default" %)Method 2.A(%%) Using Distribution Wizard ===
121 +
122 +(% class="label label-success" %)Recommended(%%) The recommended way to upgrade an XWiki installation is to use the [[Distribution Wizard>>platform:Features.DistributionWizard]] which is automatically triggered after you upgrade the XWiki WAR. It allows you to automatically upgrade extensions installed in your wiki, supporting automatic merges and conflict resolution.
123 +
92 92  {{warning}}
93 93  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:
94 94  
... ... @@ -104,14 +104,14 @@
104 104  * ##XWiki.DeletedDocuments## (Fixed in XWiki 9.8RC1)
105 105  * ##WikiManager.Translations##
106 106  
107 -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>>FAQ.How can I navigate to a given page]], edit them (using the wiki editor preferably) and save them without any modification.
139 +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.
108 108  {{/warning}}
109 109  
110 -Prior to XWiki 4.3 you had to perform this manually as explained below.
142 +=== (% class="label label-default" %)Method 2.B(%%) Using Manual Import ===
111 111  
112 -== Manual Upgrade ==
144 +(% class="label label-warning" %)Old versions < 4.3(%%) Prior to XWiki 4.3, Distribution Wizard didn't existed and you had to perform the upgrade manually as explained below.
113 113  
114 -As mentioned in the [[Installing the Default Wiki XAR section>>Documentation.AdminGuide.InstallationWAR#HInstallingtheDefaultWikiXAR]] you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:
146 +As mentioned in the [[Installing the Default Wiki XAR section>>xwiki:Documentation.AdminGuide.InstallationWAR||acnhor="HInstallingtheDefaultWikiXAR"]] you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:
115 115  
116 116  * XWiki.XWikiPreferences: This page contains some configuration of your wiki (it overrides the configuration defined in ##xwiki.cfg##). If you import a new version of this page you'll lose any customization you may have made such as the skin to use, the rights for your wiki, etc.
117 117  * XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space
... ... @@ -123,25 +123,20 @@
123 123  * XWiki.XWikiServerXwiki (multi wiki): This page contains the server descriptors and wiki properties
124 124  * Any other page you have modified, such as Main.WebHome, a modified Panel, etc.
125 125  
126 -== Let's clean it up ==
158 +----
127 127  
128 -* Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using ##jar xvf xwiki-<suffix>.war## or avoid this step if you performed an export/import data migration (you already expanded it)
129 -* Merge your old configuration files you have backed up (see above) with the new versions. Take care that if some changes were already made (probably because of database configuration when you installed the JDBC drivers) they could be lost, so take care when making these changes
130 -* Install this new folder as the ##xwiki## application in your servlet container (by copying the folder to the servlet filesystem space or by packing it in a WAR file and deploying it in the container's administration interface)
160 +== (% class="label label-default" %)Alternative(%%) Start fresh, plus Export and Reimport your data ==
131 131  
132 -At this point all is set and you can experience your old wiki data over the new XWiki core!
162 +There are cases when it's a better solution to [[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]]. For example this would be a good method if you have a very old version of XWiki and wish to move to a new version. 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.
133 133  
134 -= Alternative: Export and Reimport =
135 -
136 -There are cases when it's a better solution to [[export your current content as a XAR>>Documentation.AdminGuide.ImportExport]] and [[reimport it>>Documentation.AdminGuide.ImportExport]] into [[a new instance>>Documentation.AdminGuide.Installation]]. For example this would be a good solution if you have a very old version of XWiki and wish to move to a new version.
137 -
138 -This solution should work because the XWiki project takes great pride in being careful about backward compatibility and content created several years ago should still work well in new versions of XWiki. For example as of now, we still support XWiki Syntax 1.0 (even though it's been replaced by XWiki Syntax 2.0+ several years ago).
139 -
140 140  Some tips:
141 141  
166 +* This method should work because the XWiki project takes great pride in being careful about backward compatibility and content created several years ago should still work well in new versions of XWiki. There are some configurations you need to change in case you have content written in the old [[XWiki Syntax 1.0>>extensions:Extension.Old XWiki 1\.0 syntax renderer]].
142 142  * 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.
143 -* 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?do=viewTag&tag=export]] but you'll need to verify that the one you install will work on your old version of XWiki.
168 +* 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.
144 144  
170 +----
171 +
145 145  = Downgrading =
146 146  
147 147  {{warning}}
... ... @@ -148,4 +148,4 @@
148 148  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...
149 149  {{/warning}}
150 150  
151 -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 to [[export your wiki pages as XAR>>Documentation.AdminGuide.Backup#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.
178 +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.

Get Connected