Distribution Wizard

Last modified by Thomas Mortagne on 2023/10/10

The Distribution Wizard (also known as DW) is a feature which has several purposes:

  • It allows provisioning an empty wiki by allowing the administrator to select a Flavor on the first run of XWiki
  • It allows to create an administration user account in the wiki.
  • It also allows upgrading an existing XWiki instance to a new version by upgrading all required Extensions

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.

Clean Install

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 and you can access if either the wiki is empty (first install) or you are logged with a user having ADMIN right (upgrade). If the wizard fails to appear check the troubleshooting section.

Welcome Step

Upon first access, you will be greeted by the Distribution Wizard, offering you the 3 possible options:

  • Continue: when choosing this option, you will move to the next step of the Distribution Wizard
  • 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 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.
  • Never: Discards the DW and you will have to manually import the XAR

dw-welcomeStep.png

Admin user

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.

dw-firstadminuserStep.png

User Interface

Since 7.1 there is two modes for the Distribution Wizard: Flavor and Default User Interface.

Since 9.5 the default mode is Flavor.

To switch to Default User Interface mode you can do one of the following:

  • [since 10.2] have the following properties set properly in the file WEB-INF/xwiki.properties of the web app:
    • distribution.defaultUI: the extension ID[/version] of the application to use on the main wiki
    • distribution.defaultWikiUI: the extension ID[/version] of the application to use on other wikis
  • [since 8.4] have the following properties set properly in the file META-INF/extension.xed of the web app:
    • xwiki.extension.distribution.ui: the extension ID of the application to use on the main wiki
    • xwiki.extension.distribution.ui.version: the version of the application to use on the main wiki
    • xwiki.extension.distribution.wikiui: the extension ID of the application to use on other wikis
    • xwiki.extension.distribution.wikiui.version: the version of the application to use on other wikis
  • [only when 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:
    • xwiki.extension.distribution.ui: the extension ID of the application to use on the main wiki
    • xwiki.extension.distribution.ui.version: the version of the application to use on the main wiki
    • xwiki.extension.distribution.wikiui: the extension ID of the application to use on other wikis
    • xwiki.extension.distribution.wikiui.version: the version of the application to use on other wikis

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.

Flavor step

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.

dw-flavor-step1.png

  • Select a flavor in the list of flavors.
  • Click on "install flavor".

    dw-flavor-step2.png

  • You can also select to let the wiki be empty.

    dw-noflavor.png

  • In the case you have selected a flavor, the following steps are similar to those described in the previous section (User Interface).

Default User Interface

The first step will check your XWiki version and will propose a version of the UI which is suited for your version.

  • Click on Install to install the proposed UI. This will resolve the extensions that are going to be installed.

    dw-uiStep.png

  • Click on the Continue button. This will start the actual installation of the previously resolved extensions.

    dw-uiStep-installPlan.png

  • You will be prompted to insert credentials for the Administrator, which are Admin/admin.

    dw-uiStep-login.png

  • After the instalation is complete, you can click on the Continue button to proceed to the next step.
  • Since this is a clean install, steps 2 and 3 are skipped.

Report step

Since 5.4

The last step display all changes brought to the wiki.

dw-report.png

Upgrade

Distribution Wizard also allows you to perform an upgrade without having to manually import the XAR file.

User Interface

Since 7.1 there is two modes for the Distribution Wizard: Flavor and Default User Interface.

Since 9.5 the default mode is Flavor.

To switch to Default User Interface mode you can do one of the following:

  • [since 10.2] have the following properties set properly in the file WEB-INF/xwiki.properties of the web app:
    • distribution.defaultUI: the extension ID[/version] of the application to use on the main wiki
    • distribution.defaultWikiUI: the extension ID[/version] of the application to use on other wikis
  • [since 8.4] have the following properties set properly in the file META-INF/extension.xed of the web app:
    • xwiki.extension.distribution.ui: the extension ID of the application to use on the main wiki
    • xwiki.extension.distribution.ui.version: the version of the application to use on the main wiki
    • xwiki.extension.distribution.wikiui: the extension ID of the application to use on other wikis
    • xwiki.extension.distribution.wikiui.version: the version of the application to use on other wikis
  • [only when 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:
    • xwiki.extension.distribution.ui: the extension ID of the application to use on the main wiki
    • xwiki.extension.distribution.ui.version: the version of the application to use on the main wiki
    • xwiki.extension.distribution.wikiui: the extension ID of the application to use on other wikis
    • xwiki.extension.distribution.wikiui.version: the version of the application to use on other wikis

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.

Flavor step

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.

dw-flavor-step1.png

  • Select a flavor in the list of flavors.
  • Click on "install flavor".

    dw-flavor-step2.png

  • You can also select to let the wiki be empty.

    dw-noflavor.png

  • In the case you have selected a flavor, the following steps are similar to those described in the previous section (User Interface).

Default User Interface

The first step will check your XWiki version and will propose a version of the UI which is suited for your version.

  • Click on Install to install the proposed UI. This will resolve the extensions that are going to be installed.

    dw-uiStep.png

  • Click on the Continue button. This will start the actual installation of the previously resolved extensions.

    dw-uiStep-installPlan.png

  • You will be prompted to insert credentials for the Administrator, which are Admin/admin.

    dw-uiStep-login.png

  • After the instalation is complete, you can click on the Continue button to proceed to the next step.
  • Since this is a clean install, steps 2 and 3 are skipped.

Orphaned dependencies step

Since 11.10

orphaned.png

This step is executed right after the Flavor step.

Its job is to make sure no orphaned dependency (extension installed as dependency but which don't have any backward dependency left) is left in the installed extensions. The step suggest to uninstalled the invalid ones by default and make the others top level extensions (i.e. taken into account by the upgrade job).

Wikis

Since 5.3 and only if there is a default UI configured.

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.

dw-wikisStep.png

Extensions

dw-extensionsStep-checkForUpdates.png

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:

  • computing the upgrade plan only for the main wiki + global namespace
  • computing the upgrade plan for the entire farm (all wikis + global namespace)

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.

dw-extensionsStep-computingUpgradePlan.png

After the upgrade plan is computed there are two categories of extensions listed, as you can see in the image below:

  • invalid: they don't work with the current XWiki version so they must be upgraded
  • 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

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 section in the administration.

dw-extensionsStep.png

Upgrade with Repair

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.

dw-uiStep-repair-upgradeQuestion.png

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.

dw-uiStep-repair-selectPreviousVersion.png

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.

dw-uiStep-repair-suggestPreviousId.png

If it's not the right extension id then you should click on the pencil icon to change it.

dw-uiStep-repair-editPreviousId.png

Next you need to repair the previous UI extension. Just click on the Repair button.

dw-uiStep-repair.png

Finally you should be able to upgrade the default set of wiki pages like in a normal upgrade.

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.

dw-wikisStep-repairPreviousUI.png

Replay Install or Upgrade

Starting with version 7.1 you can record an install or upgrade and replay it on a different wiki:

  • You start by following the steps described in the Clean Install, Upgrade or Upgrade with Repair 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+).
  • After you finished with the install/upgrade of the default/recommended UI (XAR), you can install/upgrade additional extensions.
  • Then you go to the Extension History section in the wiki administration and export the actions that you wish to be replayed on a different wiki
  • 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.

    dw-welcomeStep-replayRecordedActions.png

  • 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)

    extensionHistory.png

  • 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.
  • The Distribution Wizard should not appear next time you restart XWiki, but if it does, just click continue.

Automatic mode

By default you get a wizard when there is things to finish (usually install the user interface) but it's also possible to disable the interactive mode and let the Distribution job runs and take decision automatically.

The is several ways to do it:

  • since 10.2RC1 it's possible to disable interactive more in xwiki.properties using the distribution.job.interactive and distribution.job.interactive.wiki properties
  • since 9.1RC1 it's possible start the distribution job trough the Job REST API

If you enable automatic mode you might also want to indicate a default UI since the default mode (flavors) won't do much (because it does not know which flavor you want). See User Interface for more details.

Troubleshooting

The wizard fails to appear at startup

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).

In this case only, you can remove the .../jobs/status/distribution/status.xml.zip file located inside your permanent directory (/var/lib/xwiki/data/... for APT installation or /var/lib/tomcatX/webapps/... for WAR installation).

XWiki <13.7 The status file was not zipped and named: .../jobs/status/distribution/status.xml.

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.

In order for the Distribution Wizard to be triggered, you have to log in as administrator (or superadmin if database is empty).

Setting up new XWiki instance without reinstalling

To set up empty/new XWiki instance you need to clear its database and local file storage.

  1. Empty the main database.
    For example with MySQL server, you can execute the command:

    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';"

    where 'password' is password for xwiki user in MySQL database.

    You should also delete the subwikis databases if any.

  2. To clear local data in filesystem empty or remove the permanent directory (see environment.permanentDirectory property in xwiki.properties file).

    For example if you have installed XWiki using APT, execute command:

    sudo rm -fr /var/lib/xwiki/data /var/cache/tomcat7/Catalina/localhost/xwiki/
  3. Restart the application server, open e.g. http://localhost:8080/xwiki and rerun distribution wizard again.

Disable the automatic start of Distribution Wizard (Since 7.1RC1)

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:

#-------------------------------------------------------------------------------------
# Distribution Wizard
#-------------------------------------------------------------------------------------

#-# [Since 7.1RC1] Enable or disable the automatic start of Distribution Wizard on empty/outdated wiki.
#-#
#-# The default is:
# distribution.automaticStartOnMainWiki=true
# distribution.automaticStartOnWiki=true

You just need to uncomment the above two lines and to set the options to false.

Get Connected