Wiki source code of Distribution Wizard
Version 54.1 by Marius Dumitru Florea on 2014/04/03
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | Starting with XWiki 4.2, the Distribution Wizard (also known as DW) was introduced as an experimental feature which helps users migrate their XWiki instances to newer versions without having to manually import the XAR (wiki pages) corresponding to their new version. | ||
| 6 | |||
| 7 | XWiki's Distribution Wizard comes as an aid to ease the migration and installation of the desired user interface (UI, the default set of wiki pages) in your flavour. 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. | ||
| 8 | |||
| 9 | = Clean Install = | ||
| 10 | |||
| 11 | 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>>||anchor="troubleshooting"]]. | ||
| 12 | |||
| 13 | == Welcome Step == | ||
| 14 | |||
| 15 | Upon first access, you will be greeted by the Distribution Wizard, offering you the 3 possible options: | ||
| 16 | |||
| 17 | * **Continue**: when choosing this option, you will move to the next step of the Distribution Wizard | ||
| 18 | * **Later**: DW will prompt you again after XWiki is restarted | ||
| 19 | * **Never**: Discards the DW and you will have to manually import the XAR | ||
| 20 | |||
| 21 | {{image reference="dw-welcomeStep.png" /}} | ||
| 22 | |||
| 23 | == User Interface == | ||
| 24 | |||
| 25 | The first step will check your XWiki version and will propose a version of the UI which is suited for your version. | ||
| 26 | |||
| 27 | * Click on **Install** to install the proposed UI. This will resolve the extensions that are going to be installed.((( | ||
| 28 | {{image reference="dw-uiStep.png" /}} | ||
| 29 | ))) | ||
| 30 | * Click on the **Continue** button. This will start the actual installation of the previously resolved extensions.((( | ||
| 31 | {{image reference="dw-uiStep-installPlan.png" /}} | ||
| 32 | ))) | ||
| 33 | * You will be prompted to insert credentials for the Administrator, which are **Admin/admin**.((( | ||
| 34 | {{image reference="dw-uiStep-login.png" /}} | ||
| 35 | ))) | ||
| 36 | * After the instalation is complete, you can click on the Continue button to proceed to the next step. | ||
| 37 | * Since this is a clean install, steps 2 and 3 are skipped. | ||
| 38 | |||
| 39 | == Report step == | ||
| 40 | |||
| 41 | {{info}}Since 5.4{{/info}} | ||
| 42 | |||
| 43 | The last step display all changes brought to the wiki. | ||
| 44 | |||
| 45 | {{image reference="dw-report.png"/}} | ||
| 46 | |||
| 47 | = Upgrade = | ||
| 48 | |||
| 49 | Distribution Wizard also allows you to perform an upgrade without having to manually import the XAR file. | ||
| 50 | |||
| 51 | == User Interface == | ||
| 52 | |||
| 53 | * 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.((( | ||
| 54 | {{image reference="dw-uiStep-upgrade.png"/}} | ||
| 55 | ))) | ||
| 56 | * During the instalation you might get merge conflicts. Althrough XWiki does automatically a 3 way merge, sometimes the merge might fail. Solve your conflict and click on **Continue**((( | ||
| 57 | {{image reference="DW_Upgrade_4.png"/}} | ||
| 58 | ))) | ||
| 59 | |||
| 60 | == Wikis == | ||
| 61 | |||
| 62 | {{info}}Since 5.3{{/info}} | ||
| 63 | |||
| 64 | 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. | ||
| 65 | |||
| 66 | {{image reference="dw-wikisStep.png" /}} | ||
| 67 | |||
| 68 | == Extensions == | ||
| 69 | |||
| 70 | {{image reference="dw-extensionsStep-checkForUpdates.png" /}} | ||
| 71 | |||
| 72 | 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: | ||
| 73 | |||
| 74 | * computing the upgrade plan for the entire farm (all wikis + global namespace) | ||
| 75 | * computing the upgrade plan only for the main wiki + global namespace | ||
| 76 | |||
| 77 | The first option is suited when the farm is managed by a single entity while the second option is suited when each wiki in the farm is managed by a different 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. | ||
| 78 | |||
| 79 | {{image reference="dw-extensionsStep-computingUpgradePlan.png" /}} | ||
| 80 | |||
| 81 | After the upgrade plan is computed there are two categories of extensions listed, as you can see in the image below: | ||
| 82 | |||
| 83 | * invalid: they don't work with the current XWiki version so they must be upgraded | ||
| 84 | * 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 | ||
| 85 | |||
| 86 | Under each category, the extensions are sorted by their name and grouped by the namespace (wiki) where they are installed. 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. | ||
| 87 | |||
| 88 | {{image reference="dw-extensionsStep.png" /}} | ||
| 89 | |||
| 90 | = Upgrade with Repair = | ||
| 91 | |||
| 92 | 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. | ||
| 93 | |||
| 94 | {{image reference="dw-uiStep-repair-upgradeQuestion.png" /}} | ||
| 95 | |||
| 96 | 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. | ||
| 97 | |||
| 98 | {{image reference="dw-uiStep-repair-selectPreviousVersion.png" /}} | ||
| 99 | |||
| 100 | 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. | ||
| 101 | |||
| 102 | {{image reference="dw-uiStep-repair-suggestPreviousId.png" /}} | ||
| 103 | |||
| 104 | If it's not the right extension id then you should click on the pencil icon to change it. | ||
| 105 | |||
| 106 | {{image reference="dw-uiStep-repair-editPreviousId.png" /}} | ||
| 107 | |||
| 108 | Next you need to repair the previous UI extension. Just click on the Repair button. | ||
| 109 | |||
| 110 | {{image reference="dw-uiStep-repair.png" /}} | ||
| 111 | |||
| 112 | Finally you should be able to upgrade the default set of wiki pages like in a normal upgrade. | ||
| 113 | |||
| 114 | 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. | ||
| 115 | |||
| 116 | {{image reference="dw-wikisStep-repairPreviousUI.png" /}} | ||
| 117 | |||
| 118 | {{id name="troubleshooting"/}} | ||
| 119 | = Troubleshooting = | ||
| 120 | |||
| 121 | == The wizard fails to appear at startup == | ||
| 122 | |||
| 123 | 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##). | ||
| 124 | |||
| 125 | Thus you'll need to remove the ##jobs/status/distribution/status.xml## file located inside your permanent directory. | ||
| 126 | |||
| 127 | 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. |
