Hide last authors
Sorin Burjan 1.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
Marius Dumitru Florea 16.1 2 {{toc/}}
Sorin Burjan 1.1 3 {{/box}}
4
Vincent Massol 92.1 5 The Distribution Wizard (also known as DW) is a feature which has 2 purposes:
Ecaterina Moraru (Valica) 93.1 6
Vincent Massol 92.1 7 * It allows provisioning an empty wiki by allowing the administrator to select a [[Flavor>>platform:Features.Applications||anchor="#HFlavors"]] on the first run of XWiki
8 * It also allows upgrading an existing XWiki instance to a new version by upgrading all required Extensions
Sorin Burjan 1.1 9
Vincent Massol 92.1 10 It works using XWiki's Extension Manager to automatically detect your XWiki version to search, resolve, download and install the UI corresponding to your version. It requires an internet connection in order to work.
Sorin Burjan 1.1 11
Marius Dumitru Florea 15.1 12 = Clean Install =
Sorin Burjan 1.1 13
Vincent Massol 93.3 14 After putting your XWiki WAR inside your Servlet Container (Tomcat, Jetty, etc.) you start XWiki. When XWiki is first accessed, it will trigger the Distribution Wizard. If the wizard fails to appear check the [[troubleshooting section>>platform:Features.DistributionWizard||anchor="troubleshooting"]].
Sorin Burjan 1.1 15
Marius Dumitru Florea 15.1 16 == Welcome Step ==
Sorin Burjan 1.1 17
18 Upon first access, you will be greeted by the Distribution Wizard, offering you the 3 possible options:
Marius Dumitru Florea 15.1 19
Marius Dumitru Florea 36.1 20 * **Continue**: when choosing this option, you will move to the next step of the Distribution Wizard
Marius Dumitru Florea 84.1 21 * **Later**: DW will prompt you again after XWiki is restarted; note that the Later button has a sub-option "Replay recorded actions" that has the same effect on the Distribution Wizard, but instead of redirecting you to the page that was requested initially, it redirects you to the [[Extension History>>extensions:Extension.Extension Manager Application||anchor="HExtensionHistory"]] where you can upload and replay a history file (e.g. you can replay an install or upgrade performed on a different wiki). If the database is empty you'll have to login with the ##superadmin## user.
Marius Dumitru Florea 36.1 22 * **Never**: Discards the DW and you will have to manually import the XAR
Sorin Burjan 1.1 23
Valdis Vitolins 57.1 24 {{image reference="dw-welcomeStep.png"/}}
Sorin Burjan 1.1 25
Thomas Mortagne 91.1 26 == Admin user ==
27
28 Since 8.0 the first step allows you to register the owner of the wiki. You will then be automatically registered with it and it will be used to install anything that need to be installed.
29
30 {{image reference="dw-firstadminuserStep.png"/}}
31
Marius Dumitru Florea 15.1 32 == User Interface ==
33
Thomas Mortagne 96.1 34 Since 7.1 there is two modes for the Distribution Wizard: **Flavor** and **Default User Interface**.
Sorin Burjan 1.1 35
Thomas Mortagne 96.1 36 Since 9.5 the default mode is **Flavor**.
Sorin Burjan 1.1 37
Thomas Mortagne 97.1 38 To switch to **Default User Interface** mode you can do one of the following:
Guillaume Delhumeau 81.1 39
Thomas Mortagne 97.1 40 * [since 10.2] have the following properties set properly in the file ##WEB-INF/xwiki.properties## of the web app:
41 ** ##distribution.defaultUI##: the extension ID[/version] of the application to use on the main wiki
42 ** ##distribution.defaultWikiUI##: the extension ID[/version] of the application to use on other wikis
Thomas Mortagne 94.1 43 * [since 8.4] have the following properties set properly in the file ##META-INF/extension.xed## of the web app:
44 ** ##xwiki.extension.distribution.ui##: the extension ID of the application to use on the main wiki
45 ** ##xwiki.extension.distribution.wikiui##: the extension ID of the application to use on other wikis
Thomas Mortagne 97.1 46 * [only no extension.xed exist] have the following properties set properly in the file ##META-INF/maven/org.xwiki.enterprise/xwiki-enterprise-web/pom.xml## of the web app:
Thomas Mortagne 94.1 47 ** ##xwiki.extension.distribution.ui##: the extension ID of the application to use on the main wiki
48 ** ##xwiki.extension.distribution.wikiui##: the extension ID of the application to use on other wikis
49
Thomas Mortagne 96.1 50 If you build a custom WAR using Maven, you will set those properties in your project pom and let the Extension plugin generate the right extension.xed file.
Guillaume Delhumeau 81.1 51
Thomas Mortagne 96.1 52 === Flavor step ===
Guillaume Delhumeau 81.1 53
Thomas Mortagne 96.1 54 If there is no default UI set as explained just above, you will have the Flavor Step. A flavor is a collection of applications according to different needs. You can have a flavor for a knowledge base or a public website, for example.
Guillaume Delhumeau 81.1 55
56 {{image reference="dw-flavor-step1.png"/}}
57
58 * Select a flavor in the list of flavors.
59 * Click on "install flavor".(((
60 {{image reference="dw-flavor-step2.png"/}}
61 )))
62 * You can also select to let the wiki be empty.(((
63 {{image reference="dw-noflavor.png"/}}
64 )))
65 * In the case you have selected a flavor, the following steps are similar to those described in the previous section (User Interface).
66
Thomas Mortagne 96.1 67 === Default User Interface ===
68
69 The first step will check your XWiki version and will propose a version of the UI which is suited for your version.
70
71 * Click on **Install** to install the proposed UI. This will resolve the extensions that are going to be installed.(((
72 {{image reference="dw-uiStep.png"/}}
73 )))
74 * Click on the **Continue** button. This will start the actual installation of the previously resolved extensions.(((
75 {{image reference="dw-uiStep-installPlan.png"/}}
76 )))
77 * You will be prompted to insert credentials for the Administrator, which are **Admin/admin**.(((
78 {{image reference="dw-uiStep-login.png"/}}
79 )))
80 * After the instalation is complete, you can click on the Continue button to proceed to the next step.
81 * Since this is a clean install, steps 2 and 3 are skipped.
82
Thomas Mortagne 26.1 83 == Report step ==
84
Valdis Vitolins 57.1 85 {{info}}
86 Since 5.4
87 {{/info}}
Thomas Mortagne 28.1 88
Thomas Mortagne 26.1 89 The last step display all changes brought to the wiki.
90
91 {{image reference="dw-report.png"/}}
92
Marius Dumitru Florea 20.1 93 = Upgrade =
Sorin Burjan 1.1 94
95 Distribution Wizard also allows you to perform an upgrade without having to manually import the XAR file.
96
Marius Dumitru Florea 15.1 97 == User Interface ==
Sorin Burjan 1.1 98
Manuel Smeria 62.2 99 * The Distribution Wizard detects that the UI version is not the latest and proposes to upgrade. Click on the **Upgrade** button. After the required dependencies are resolved, click **Continue** button to begin the actual installation of the new UI:(((
Marius Dumitru Florea 41.1 100 {{image reference="dw-uiStep-upgrade.png"/}}
Marius Dumitru Florea 15.1 101 )))
Manuel Smeria 62.2 102 * During the instalation you might get merge conflicts. Although XWiki does automatically a 3 way merge, sometimes the merge might fail. Solve your conflict and click on **Continue**:(((
103 {{image reference="DW_Upgrade_4.png"/}}
Marius Dumitru Florea 15.1 104 )))
Marius Dumitru Florea 20.1 105
Thomas Mortagne 28.1 106 == Wikis ==
Marius Dumitru Florea 20.1 107
Valdis Vitolins 57.1 108 {{info}}
109 Since 5.3
110 {{/info}}
Marius Dumitru Florea 20.1 111
Thomas Mortagne 28.1 112 Distribution Wizard list all the existing wikis with the recommended user interface version that needs to be installed in order to update the default set of wiki pages.
Marius Dumitru Florea 20.1 113
Valdis Vitolins 57.1 114 {{image reference="dw-wikisStep.png"/}}
Marius Dumitru Florea 23.1 115
Marius Dumitru Florea 20.1 116 == Extensions ==
Marius Dumitru Florea 23.1 117
Valdis Vitolins 57.1 118 {{image reference="dw-extensionsStep-checkForUpdates.png"/}}
Marius Dumitru Florea 24.1 119
Marius Dumitru Florea 53.1 120 In the last step you can upgrade the extensions that you may have installed on your wikis. If you are on a subwiki then you can only check for updates for the extensions installed on that subwiki. On the main wiki global administrators can choose between:
121
Marius Dumitru Florea 56.1 122 * computing the upgrade plan only for the main wiki + global namespace
Marius Dumitru Florea 53.1 123 * computing the upgrade plan for the entire farm (all wikis + global namespace)
124
Marius Dumitru Florea 56.1 125 The first option is suited when each wiki in the farm is managed by a different entity while the second option is suited when the farm is managed by a single entity. Obviously computing the upgrade plan for the entire farm takes longer (with the number of wikis) than computing the upgrade plan only for the main wiki.
Marius Dumitru Florea 53.1 126
Valdis Vitolins 57.1 127 {{image reference="dw-extensionsStep-computingUpgradePlan.png"/}}
Marius Dumitru Florea 53.1 128
129 After the upgrade plan is computed there are two categories of extensions listed, as you can see in the image below:
130
Marius Dumitru Florea 24.1 131 * invalid: they don't work with the current XWiki version so they must be upgraded
132 * outdated: they should work with the current XWiki version but there is a newer version available that probably has bug fixes, improvements or new features
133
Marius Dumitru Florea 56.1 134 Under each category, the extensions are sorted by their name, grouped by the namespace (wiki) where they are installed and paginated. In order to complete this step you have to upgrade the invalid extensions. Upgrading the outdated extensions is optional as you can do it later from the [[Extension Updater>>doc:extensions:Extension.Extension Manager Application||anchor="HExtensionUpdater"]] section in the administration.
Marius Dumitru Florea 24.1 135
Valdis Vitolins 57.1 136 {{image reference="dw-extensionsStep.png"/}}
Marius Dumitru Florea 49.1 137
138 = Upgrade with Repair =
139
140 In order to be able to do 3-way automatic merges, the Extension Manager, used by the Distribution Wizard, needs to know the user interface version (i.e. default set of wiki pages) that was previously installed. When this information is not available the Distribution Wizard asks the user. This can happen for instance when you upgrade from a very old XWiki version where the default set of wiki pages wasn't installed through the Extension Manager. First you need to tell the Distribution Wizard if you are performing an upgrade or not.
141
Valdis Vitolins 57.1 142 {{image reference="dw-uiStep-repair-upgradeQuestion.png"/}}
Marius Dumitru Florea 49.1 143
144 Then you need to select the previous version. You should find your version in the provided list. Otherwise you can click on the pencil icon to enter a different version.
145
Valdis Vitolins 57.1 146 {{image reference="dw-uiStep-repair-selectPreviousVersion.png"/}}
Marius Dumitru Florea 49.1 147
148 Once you select a version the Distribution Wizard shows you the extension id that corresponds to that version. Make sure it is the right id.
149
Valdis Vitolins 57.1 150 {{image reference="dw-uiStep-repair-suggestPreviousId.png"/}}
Marius Dumitru Florea 49.1 151
152 If it's not the right extension id then you should click on the pencil icon to change it.
153
Valdis Vitolins 57.1 154 {{image reference="dw-uiStep-repair-editPreviousId.png"/}}
Marius Dumitru Florea 49.1 155
156 Next you need to repair the previous UI extension. Just click on the Repair button.
157
Valdis Vitolins 57.1 158 {{image reference="dw-uiStep-repair.png"/}}
Marius Dumitru Florea 49.1 159
160 Finally you should be able to upgrade the default set of wiki pages like in a normal upgrade.
161
162 If you have multiple wikis, then the **Wikis** step will allow you to repair the user interface on each of the available wikis. The process is the same as for the main wiki, the one described above.
163
Valdis Vitolins 57.1 164 {{image reference="dw-wikisStep-repairPreviousUI.png"/}}
Vincent Massol 50.1 165
Vincent Massol 51.1 166 {{id name="troubleshooting"/}}
Valdis Vitolins 57.1 167
Marius Dumitru Florea 85.1 168 = Replay Install or Upgrade =
169
170 Starting with version 7.1 you can record an install or upgrade and replay it on a different wiki:
Dmitry Bakbardin 88.1 171
Vincent Massol 93.3 172 * You start by following the steps described in the [[Clean Install>>platform:Features.DistributionWizard||anchor="HCleanInstall"]], [[Upgrade>>platform:Features.DistributionWizard||anchor="HUpgrade"]] or [[Upgrade with Repair>>platform:Features.DistributionWizard||anchor="HUpgradewithRepair"]] sections. The decisions you take (e.g. which extension to repair, which extensions to upgrade, merge conflict resolution, page cleanup) are automatically recorded (the XWiki WAR must have version 7.1+).
Marius Dumitru Florea 85.1 173 * After you finished with the install/upgrade of the default/recommended UI (XAR), you can install/upgrade additional extensions.
174 * Then you go to the [[Extension History>>extensions:Extension.Extension Manager Application||anchor="HExtensionHistory"]] section in the [[wiki administration>>extensions:Extension.Administration Application]] and export the actions that you wish to be replayed on a different wiki
175 * Access the wiki where you want to replay the recorded actions. When the Distribution Wizard appears, skip it by choosing the "Replay recorded actions" sub-option of the "Later" button from the Welcome step.(((
176 {{image reference="dw-welcomeStep-replayRecordedActions.png"/}}
177 )))
178 * This will take you to the Extension History (works even if the database is empty, but in this case you'll have to login with the ##superadmin## user)(((
179 {{image reference="extensionHistory.png"/}}
180 )))
181 * Import the history file you have previously exported, select the records to replay and replay them. Note that you can replay on multiple wikis at the same time, if you have Programming Rights. If there are questions (e.g. a merge conflict) that don't have an answer in the recorded history file then you will be prompted to answer them.
182 * The Distribution Wizard should not appear next time you restart XWiki, but if it does, just click continue.
183
Vincent Massol 50.1 184 = Troubleshooting =
185
186 == The wizard fails to appear at startup ==
187
188 If you're doing a first time install and the Distribution Wizard doesn't appear it's probably because you've copied some directories from an existing install. Namely, the Distribution Wizard looks for status files located in your permanent directory (the ##environment.permanentDirectory## property in ##xwiki.properties##).
189
Vincent Massol 93.3 190 Thus you'll need to remove the ##.../jobs/status/distribution/status.xml## file located inside your permanent directory (##/var/lib/xwiki/...## for [[APT installation>>platform:AdminGuide.InstallationViaAPT]] or ##/var/lib/tomcatX/webapps/...## for [[WAR installation>>platform:AdminGuide.InstallationWAR]]).
Vincent Massol 50.1 191
192 Now, if you have done an upgrade of the XWiki WAR, you'll need to be logged with a user having Admin rights to see the Distribution Wizard appear.
Valdis Vitolins 59.1 193
Dmitry Bakbardin 88.1 194 {{warning}}
195 In order for the Distribution Wizard to be triggered, you have to log in as administrator (or superadmin if database is empty).
196 {{/warning}}
197
Valdis Vitolins 59.1 198 == Setting up new XWiki instance without reinstalling ==
199
Valdis Vitolins 61.2 200 To set up empty/new XWiki instance you need to clear its database and local file storage.
Valdis Vitolins 59.1 201
202 1. (((
Thomas Mortagne 61.1 203 Empty the main database.
204 For example with MySQL server, you can execute the command:
Valdis Vitolins 59.1 205
206 {{code language="none"}}
207 mysql -uroot -p -e "drop database xwiki; CREATE DATABASE xwiki CHARACTER SET utf8 COLLATE utf8_general_ci; GRANT ALL PRIVILEGES ON xwiki.* TO 'xwiki'@'localhost' IDENTIFIED BY 'password';"
208 {{/code}}
209
Thomas Mortagne 61.1 210 where ##'password'## is password for xwiki user in MySQL database.
211
212 You should also delete the subwikis databases if any.
Valdis Vitolins 59.1 213 )))
Valdis Vitolins 60.1 214 1. (((
Thomas Mortagne 61.1 215 To clear local data in filesystem empty or remove the permanent directory (see environment.permanentDirectory property in xwiki.properties file).
Valdis Vitolins 59.1 216
Vincent Massol 93.3 217 For example if you have installed XWiki using [[APT>>platform:AdminGuide.InstallationViaAPT]], execute command:
Thomas Mortagne 61.1 218
Valdis Vitolins 59.1 219 {{code language="none"}}
Valdis Vitolins 62.1 220 sudo rm -fr /var/lib/xwiki/data /var/cache/tomcat7/Catalina/localhost/xwiki/
Valdis Vitolins 59.1 221 {{/code}}
Valdis Vitolins 60.1 222 )))
Thomas Mortagne 61.1 223 1. Restart the application server, open e.g. [[http://localhost:8080/xwiki]] and rerun distribution wizard again.
Guillaume Delhumeau 74.1 224
Guillaume Delhumeau 81.1 225 == Disable the automatic start of Distribution Wizard {{info}}(Since 7.1RC1){{/info}} ==
226
Guillaume Delhumeau 74.1 227 If, for some reason, you need to disable the Distribution Wizard when you start the wiki for the first time, you can change the configuration in ##xwiki.properties##:
228
229 {{code language="cfg"}}
230 #-------------------------------------------------------------------------------------
231 # Distribution Wizard
232 #-------------------------------------------------------------------------------------
233
234 #-# [Since 7.1RC1] Enable or disable the automatic start of Distribution Wizard on empty/outdated wiki.
235 #-#
236 #-# The default is:
237 # distribution.automaticStartOnMainWiki=true
238 # distribution.automaticStartOnWiki=true
239 {{/code}}
240
241 You just need to uncomment the above two lines and to set the options to ##false##.

Get Connected