Skip to Content

Ready for review

Convert the Distribution Wizard documentation into the documentation tree

Last modified by Eleni Cojocariu on 2026/08/14 13:37

Converts the legacy Distribution Wizard page into a new documentation.xs.admin.distribution-wizard topic, without duplicating the flavor-upgrade How-to that already exists in the tree.

What this change request contains

Eight new pages, one Diataxis type each:

  • Distribution Wizard (Explanation, the topic page): what the wizard is, that it drives the Extension Manager, and a decision diagram of when it starts and which mode it runs in.
  • Distribution Wizard Steps (Reference): every step, when it appears and what it does, plus the "Continue" / "Later" / "Never" / "Replay recorded actions" options.
  • Install the Flavor Using the Distribution Wizard (How-to).
  • Repair the Previously Installed Flavor (How-to).
  • Replay a Recorded Install or Upgrade (How-to).
  • Distribution Wizard Configuration (Reference): the six xwiki.properties properties, the four extension.xed keys and their precedence, and the Job REST API route.
  • Distribution Wizard Does Not Appear at Startup (Explanation).
  • Rerun the Distribution Wizard on an Empty Instance (How-to).

The existing Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard stays where it is and is completed instead of being duplicated: its Welcome-step options move to the new Steps Reference, its screenshot is re-captured at 960px so its size becomes extra, and the Flavor step it never showed is added, which is the step the page is named after.

The legacy page is stripped to a pointer, keeping every anchor still in use (HCleanInstall, HUserInterface, HUpgrade, HUpgradewithRepair, troubleshooting) as explicit {{id}} macros, since four of them were generated from headings this change removes. Its ten backlinks in the new tree are repointed, along with the FAQ entry that answered by linking into it.

Corrections to the legacy content

Established from the xwiki-platform sources and reproduced on live 18.6.0 instances, not carried over from the legacy prose:

  • The distribution job status file is at <permanent directory>/jobs/status/3/distribution/status.xml.zip. The legacy troubleshooting text omits the store-version folder.
  • The "Admin user" step is skipped when you are already logged in with an administrator, and "Orphaned dependencies" when nothing is orphaned.
  • The "Extensions" step only appears when an installed extension is invalid; merely outdated ones do not bring it back, contrary to "in the last step you can upgrade the extensions".
  • The "Wikis" step never appears in flavor mode.
  • "Welcome" and "Report" exist in interactive mode only.

Dropped as obsolete: the META-INF/maven/org.xwiki.enterprise/... fallback, and every [since 5.3]...[since 11.10] badge together with the XWiki <13.7 

 block, all far below the LTS.

Notes for the reviewer

  • 24 screenshots were captured on 18.6.0 instances at the exact size width, each with the red box on the element the step names.
  • The Replay How-to ends on the Replay Plan and describes the status screen in prose: a truthful status screenshot needs a replay against a namespace other than the one it was recorded on, which has not been produced.
  • Technical ID is empty on all eight pages, and the topic page carries no link to an Extensions-wiki page: there is none for the Distribution Wizard, as for the neighbouring upgrade and installation topic pages.
  • Highlights are empty: seven children is well under the threshold where they help.
  • The navigation order of the new topic will be pinned after the merge.

All changes

Creation of Distribution Wizard

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Distribution Wizard
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,42 @@
1 +The Distribution Wizard is the tool XWiki opens in the browser when an instance is not ready to be used yet. It provisions an empty wiki with a [[flavor>>doc:Documentation.UserGuide.Features.Applications||anchor="HFlavors"]], registers the user who owns the wiki, and brings the wiki content up to date after the [[distribution has been upgraded>>doc:documentation.xs.admin.upgrade.distribution.WebHome]].
2 +
3 +The wizard carries no content of its own: it drives the [[Extension Manager>>doc:extensions:Extension.Extension Manager Application]], which resolves the extensions matching the running XWiki version and downloads them from the remote repositories. An instance with no access to the Internet needs those extensions [[available locally>>doc:documentation.xs.admin.installation.install-offline.WebHome]] before the wizard can complete.
4 +
5 +Whether the wizard opens, and what it offers once it does, depends on the state of the instance and on its [[configuration>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]]:
6 +
7 +{{plantuml}}
8 +@startuml
9 +!theme bluegray
10 +start
11 +:XWiki starts;
12 +if (Wiki empty, or extensions\nto install for this version?) then (no)
13 + :The wizard stays closed;
14 + stop
15 +endif
16 +if (Automatic start enabled\nfor this wiki?) then (no)
17 + :The wizard stays closed;
18 + stop
19 +endif
20 +if (Default user interface\nconfigured?) then (yes)
21 + :Default user interface mode:\nthe "User Interface" and "Wikis" steps;
22 +else (no)
23 + :Flavor mode:\nthe "Flavor" step;
24 +endif
25 +if (Interactive mode?) then (yes)
26 + :The wizard opens in the browser,\nfrom "Welcome" to "Report";
27 +else (no)
28 + :The distribution job runs on its own\nand takes the decisions automatically;
29 +endif
30 +stop
31 +@enduml
32 +{{/plantuml}}
33 +
34 +Every run walks through the same sequence of [[steps>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]]. What the run achieves is the reason it was started:
35 +
36 +* [[Install the Flavor Using the Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.install-flavor.WebHome]], on the first start of a freshly installed instance.
37 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]], on the first start after the distribution was upgraded.
38 +* [[Repair the Previously Installed Flavor>>doc:documentation.xs.admin.distribution-wizard.repair-previous-flavor.WebHome]], when the Extension Manager has no record of the user interface that was installed before and the wizard asks for it.
39 +* [[Replay a Recorded Install or Upgrade>>doc:documentation.xs.admin.distribution-wizard.replay-recorded-actions.WebHome]], to apply on another wiki the decisions taken during one of the runs above.
40 +* [[Rerun the Distribution Wizard on an Empty Instance>>doc:documentation.xs.admin.distribution-wizard.rerun-empty-instance.WebHome]], to start over on a wiki that has already been set up.
41 +
42 +If the wizard does not open when you expect it, see [[Distribution Wizard Does Not Appear at Startup>>doc:documentation.xs.admin.distribution-wizard.not-appearing-startup.WebHome]].
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Who is allowed to run the Distribution Wizard? ==
2 +
3 +A user with administration rights on the wiki, or the ##superadmin## user while the database is still empty. Upgrading the flavor also requires [[Programming Rights>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.programming-rights-impact-distribution-wizard.WebHome]].
4 +
5 +== Can the Distribution Wizard be removed from the wiki? ==
6 +
7 +No. It is part of the XWiki distribution rather than an extension, so it can only be [[configured not to start>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]].
Related
... ... @@ -1,0 +1,3 @@
1 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
2 +* [[Programming Rights Impact on Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.programming-rights-impact-distribution-wizard.WebHome]].
3 +* [[Install XWiki Offline>>doc:documentation.xs.admin.installation.install-offline.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +explanation
DocApp.Code.DocumentationExtensionClass[0]

Creation of Distribution Wizard Steps

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Distribution Wizard Steps
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,19 @@
1 +The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] runs the same sequence of steps on every instance. A step that has nothing to do is marked as completed and skipped, so a given run shows only a subset of them.
2 +
3 +|=Step|=When it appears|=What it does
4 +|"Welcome"|In interactive mode only, before the numbered steps|Presents, under the "Distribution Wizard" heading, the steps that follow, and offers the options listed below.
5 +|"Admin user"|On the main wiki, unless you are already logged in with a user who has administration rights|Registers the user who owns the wiki. You are then logged in with that user, which is the one used to install everything that follows.
6 +|"Flavor"|In flavor mode, which is the default|Installs the [[flavor>>doc:Documentation.UserGuide.Features.Applications||anchor="HFlavors"]] you select.
7 +|"User Interface"|In [[default user interface mode>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]] only|Proposes the version of the configured user interface that matches the running XWiki version, and installs it.
8 +|"Orphaned dependencies"|Only when an extension installed as a dependency has no extension depending on it any more|Offers to uninstall the orphans that are invalid, and to turn the others into top level extensions so that the upgrade takes them into account.
9 +|"Wikis"|In default user interface mode only, for the other wikis of the farm|Installs on each of the other wikis the user interface version recommended for them.
10 +|"Extensions"|Only when an installed extension is invalid for the running XWiki version|Computes an upgrade plan and upgrades the extensions it lists. On a subwiki the plan covers that subwiki; on the main wiki, "Check for updates" computes it for the main wiki and the global namespace, and "Check for updates on farm" for every wiki of the farm, which takes longer. Extensions that are merely outdated are upgraded later, from the [[Extension Updater>>doc:extensions:Extension.Extension Manager Application||anchor="HExtensionUpdater"]] in the wiki administration.
11 +|"Report"|In interactive mode only, after the last numbered step|Lists every change the run brought to the wiki.
12 +
13 +The first step offers three ways to proceed, and the "Later" button carries a fourth:
14 +
15 +|=Option|=Effect
16 +|"Continue"|Moves to the next step.
17 +|"Later"|Leaves the wizard, which opens again the next time XWiki is restarted.
18 +|"Never"|Discards the wizard, leaving you to [[import the XAR>>doc:documentation.xs.admin.imports.import-xwiki-pages.WebHome]] yourself.
19 +|"Replay recorded actions"|A sub-option of "Later" which leaves the wizard and opens the [[Extension History>>doc:extensions:Extension.Extension Manager Application||anchor="HExtensionHistory"]] instead, where a [[recorded install or upgrade>>doc:documentation.xs.admin.distribution-wizard.replay-recorded-actions.WebHome]] can be replayed.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,3 @@
1 +== Does a step that was skipped come back later? ==
2 +
3 +Yes, on the next run, as soon as its condition holds again. An extension that a distribution upgrade made invalid brings the "Extensions" step back, for instance.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Distribution Wizard Configuration>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]].
2 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Install the Flavor Using the Distribution Wizard
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,19 @@
1 +Installing a [[flavor>>doc:Documentation.UserGuide.Features.Applications||anchor="HFlavors"]] with the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] fills a freshly installed, empty instance with the wiki Pages of a ready-made set of applications.
2 +
3 +1. Start XWiki and open it in a browser.
4 +1. Click "Continue" in the [[Welcome step>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]]:(((
5 +{{image reference="wizard-continue-button.png" size="medium" alt="The Continue button of the Distribution Wizard Welcome step"/}}
6 +)))
7 +1. Fill in the account of the user who owns the wiki, then click "Register and login":(((
8 +{{image reference="admin-user-step.png" size="extra" alt="The Admin user step of the Distribution Wizard, with the registration form of the wiki owner"/}}
9 +)))
10 +1. Select a flavor in the list, then click "Install this flavor":(((
11 +{{image reference="flavor-step-select.png" size="extra" alt="The Flavor step of the Distribution Wizard, with a flavor selected and the Install this flavor button"/}}
12 +)))
13 +1. Click "Install" to resolve the extensions to install, then "Continue" to install them:(((
14 +{{image reference="flavor-step-confirm.png" size="extra" alt="The Distribution Wizard asking to confirm the installation of the selected flavor"/}}
15 +)))
16 +1. Click "Continue" to leave the report of the changes the installation brought.
17 +1. The wiki is ready to be used, as follows:(((
18 +{{image reference="install-flavor-done.png" size="extra" alt="The home page of a wiki on which the flavor has just been installed"/}}
19 +)))
admin-user-step.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +47.1 KB
Content
flavor-step-confirm.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +45.7 KB
Content
flavor-step-select.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +62.9 KB
Content
install-flavor-done.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +105.7 KB
Content
wizard-continue-button.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +3.4 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Can the wiki be left empty instead? ==
2 +
3 +Yes. The "Flavor" step also offers to install no flavor at all, and the wiki is then created without any application Page.
4 +
5 +== Why is the list of flavors empty? ==
6 +
7 +The flavors are resolved from the remote extension repositories, so the list stays empty on an instance that cannot reach the Internet. [[Install XWiki offline>>doc:documentation.xs.admin.installation.install-offline.WebHome]] to make them available locally.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Install a Standalone (Demo) Distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]].
2 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Creation of Repair the Previously Installed Flavor

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Repair the Previously Installed Flavor
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,15 @@
1 +The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] asks which user interface was installed previously when the Extension Manager holds no record of it, which happens when upgrading from a version old enough that the wiki Pages were not installed as an extension. The repair is offered in [[default user interface mode>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]] only.
2 +
3 +1. Answer "Yes, this is an upgrade" to the question the wizard opens on:(((
4 +{{image reference="repair-upgrade-question.png" size="extra" alt="The Distribution Wizard asking whether the instance is being upgraded or newly installed"/}}
5 +)))
6 +1. Select the version that was installed previously, or click the pencil icon to enter a version the list does not offer:(((
7 +{{image reference="repair-select-previous-version.png" size="extra" alt="The Distribution Wizard offering the list of versions that could have been installed previously"/}}
8 +)))
9 +1. Check the extension id the wizard resolved from that version, and correct it with the pencil icon next to it if it is not the right one.
10 +1. Click "Repair" to register the previous user interface:(((
11 +{{image reference="repair-previous-flavor.png" size="extra" alt="The Repair button of the Distribution Wizard, registering the previously installed user interface"/}}
12 +)))
13 +1. The wizard now offers the upgrade of the wiki Pages, as follows:(((
14 +{{image reference="repair-then-upgrade.png" size="extra" alt="The Distribution Wizard offering to upgrade the user interface once the previous one has been repaired"/}}
15 +)))
repair-previous-flavor.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +76.8 KB
Content
repair-select-previous-version.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +91.3 KB
Content
repair-then-upgrade.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +92.7 KB
Content
repair-upgrade-question.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +77.9 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Why does the wizard need to know the previous version? ==
2 +
3 +The Extension Manager merges your own changes into the new wiki Pages by comparing both with the Pages of the previous version, and it has nothing to compare with until that version is known.
4 +
5 +== How are the other wikis of the farm repaired? ==
6 +
7 +The "Wikis" step repairs each of them the same way, once the main wiki is done.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Distribution Wizard Configuration>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]].
2 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Creation of Replay a Recorded Install or Upgrade

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Replay a Recorded Install or Upgrade
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,18 @@
1 +The decisions taken during a run of the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]], such as the extensions to upgrade or the way a merge conflict was resolved, are recorded as they are taken, and the recording can be replayed on another wiki so that the same run does not have to be answered again there.
2 +
3 +1. Open the [[Extension History>>doc:extensions:Extension.Extension Manager Application||anchor="HExtensionHistory"]] of the wiki the install or upgrade was performed on, and click "Export" to download the actions to replay:(((
4 +{{image reference="extension-history-export.png" size="extra" alt="The Export button of the Extension History, downloading the recorded actions"/}}
5 +)))
6 +1. Open the wiki to replay them on, and choose "Replay recorded actions" in the "Later" button of the [[Welcome step>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]]:(((
7 +{{image reference="wizard-replay-option.png" size="large" alt="The Replay recorded actions option of the Later button of the Distribution Wizard"/}}
8 +)))
9 +1. Import the file exported above, select the records to replay and click "Replay":(((
10 +{{image reference="extension-history-replay.png" size="extra" alt="The Replay button of the Extension History, applying the imported records"/}}
11 +)))
12 +1. Click "Continue" under the replay options:(((
13 +{{image reference="extension-history-replay-options.png" size="extra" alt="The replay options of the Extension History, with the Continue button"/}}
14 +)))
15 +1. Click "Start" to run the replay plan:(((
16 +{{image reference="extension-history-replay-plan.png" size="extra" alt="The replay plan computed by the Extension History, with the Start button"/}}
17 +)))
18 +1. Follow the replay in the status screen that opens. It reports each replayed action, and prompts for any question the recording holds no answer for.
extension-history-export.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +14.5 KB
Content
extension-history-replay-options.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +23.9 KB
Content
extension-history-replay-plan.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +14.0 KB
Content
extension-history-replay.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +14.5 KB
Content
wizard-replay-option.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +6.2 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Can the actions be replayed on several wikis at once? ==
2 +
3 +Yes, provided the user replaying them has Programming Rights.
4 +
5 +== How is the Extension History reached on a wiki whose database is empty? ==
6 +
7 +The "Replay recorded actions" option opens it even then, but you have to log in with the ##superadmin## user first.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Distribution Wizard Steps>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]].
2 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Creation of Distribution Wizard Configuration

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Distribution Wizard Configuration
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,29 @@
1 +The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] reads its configuration from the ##WEB-INF/xwiki.properties## file of the web application.
2 +
3 +|=Property|=Default|=Description
4 +|##distribution.automaticStartOnMainWiki##|##true##|Start the wizard automatically on the main wiki when it has something to do.
5 +|##distribution.automaticStartOnWiki##|##true##|The same, for the other wikis of the farm.
6 +|##distribution.job.interactive##|##true##|Run the wizard in the browser on the main wiki. Set to ##false##, the distribution job runs on its own and takes the decisions automatically, without the "Distribution Wizard" and "Report" steps.
7 +|##distribution.job.interactive.wiki##|##true##|The same, for the other wikis of the farm.
8 +|##distribution.defaultUI##|(none)|The id of the extension to install as the user interface of the main wiki, optionally followed by a slash and a version. Setting it switches the wizard to default user interface mode.
9 +|##distribution.defaultWikiUI##|(none)|The same, for the other wikis of the farm.
10 +
11 +That mode changes the [[list of steps>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]], as follows:
12 +
13 +{{image reference="wizard-default-ui-steps.png" size="extra" alt="The Distribution Wizard in default user interface mode, showing the User Interface and Wikis steps instead of the Flavor step"/}}
14 +
15 +When neither property is set, the user interface is the one the WAR declares in its ##META-INF/extension.xed## file:
16 +
17 +|=Key|=Description
18 +|##xwiki.extension.distribution.ui##|The id of the extension to install as the user interface of the main wiki.
19 +|##xwiki.extension.distribution.ui.version##|Its version.
20 +|##xwiki.extension.distribution.wikiui##|The id of the extension to install as the user interface of the other wikis.
21 +|##xwiki.extension.distribution.wikiui.version##|Its version.
22 +
23 +A WAR built with Maven declares those keys in its own ##pom.xml## and lets the Extension plugin generate the ##extension.xed## file from them. An id configured in ##xwiki.properties## without a version takes the version of the WAR itself.
24 +
25 +The distribution job can also be started without the browser, through the [[Job REST API>>doc:Documentation.UserGuide.Features.XWikiRESTfulAPI||anchor="HJobresources"]]:
26 +
27 +{{code language="none"}}
28 +PUT /rest/jobs?jobType=distribution&async=true
29 +{{/code}}
wizard-default-ui-steps.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +29.7 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,3 @@
1 +== Why does the automatic mode install nothing? ==
2 +
3 +Because the default flavor mode has no way to know which flavor you want. Set ##distribution.defaultUI## as well when you disable the interactive mode.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Distribution Wizard Steps>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]].
2 +* [[Sub-Directories in the Permanent Directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.sub-directories.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]

Creation of Distribution Wizard Does Not Appear at Startup

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Distribution Wizard Does Not Appear at Startup
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,11 @@
1 +The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] does not open when XWiki is started, although the instance has just been installed or upgraded.
2 +
3 +=== Cause ===
4 +
5 +The wizard records what it has already done in the ##jobs/status/3/distribution## [[sub-directory of the permanent directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.sub-directories.WebHome]]. An instance whose permanent directory was copied from another install therefore starts with the record of a run that is already finished, and the wizard has no reason to open.
6 +
7 +After an upgrade of the XWiki WAR, the wizard also stays closed until a user who has administration rights logs in.
8 +
9 +=== Solution ===
10 +
11 +Delete the ##status.xml.zip## file from that sub-directory, restart XWiki, and log in with a user who has administration rights.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Does the wizard need Internet access to open? ==
2 +
3 +No. It opens whether or not the instance can reach the Internet, and needs the connection only to download the extensions it installs.
4 +
5 +== How is the wizard opened again on a wiki that is already set up? ==
6 +
7 +By emptying the instance, as described in [[Rerun the Distribution Wizard on an Empty Instance>>doc:documentation.xs.admin.distribution-wizard.rerun-empty-instance.WebHome]].
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Sub-Directories in the Permanent Directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.sub-directories.WebHome]].
2 +* [[Rerun the Distribution Wizard on an Empty Instance>>doc:documentation.xs.admin.distribution-wizard.rerun-empty-instance.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +explanation
DocApp.Code.DocumentationExtensionClass[0]

Creation of Rerun the Distribution Wizard on an Empty Instance

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Rerun the Distribution Wizard on an Empty Instance
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,19 @@
1 +Emptying an instance makes the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] run from the start again on a wiki that has already been set up, which is how a test instance is brought back to the state of a fresh install.
2 +
3 +1. Stop the Servlet Container.
4 +1. Drop and recreate the main database, and drop the databases of the subwikis if the farm has any. With MySQL:(((
5 +{{code language="sql"}}
6 +DROP DATABASE xwiki;
7 +CREATE DATABASE xwiki CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
8 +GRANT ALL PRIVILEGES ON xwiki.* TO 'xwiki'@'localhost';
9 +{{/code}}
10 +)))
11 +1. Empty the [[permanent directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.WebHome]], which is the ##environment.permanentDirectory## property of ##xwiki.properties##. On an installation from the Debian packages:(((
12 +{{code language="bash"}}
13 +sudo rm -rf /var/lib/xwiki/data
14 +{{/code}}
15 +)))
16 +1. Start the Servlet Container and open the wiki in a browser.
17 +1. The Distribution Wizard greets you as on a new install, as follows:(((
18 +{{image reference="wizard-welcome-empty-instance.png" size="extra" alt="The Welcome step of the Distribution Wizard on an instance whose database and permanent directory have been emptied"/}}
19 +)))
wizard-welcome-empty-instance.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +80.4 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Is the wiki content recoverable afterwards? ==
2 +
3 +No. The database and the permanent directory are the whole of the wiki, so export what matters beforehand.
4 +
5 +== Why is emptying the database not enough? ==
6 +
7 +Because the permanent directory keeps the record of the runs the wizard has already made, which stops it from [[opening again>>doc:documentation.xs.admin.distribution-wizard.not-appearing-startup.WebHome]].
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Install the Flavor Using the Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.install-flavor.WebHome]].
2 +* [[Sub-Directories in the Permanent Directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.sub-directories.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Content
... ... @@ -1,15 +1,20 @@
1 -To upgrade the pre-installed standard flavor of the wiki with the [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]], once the [[distribution has been upgraded>>documentation.xs.admin.upgrade.distribution.WebHome]]:
1 +To upgrade the pre-installed standard flavor of the wiki with the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]], once the [[distribution has been upgraded>>doc:documentation.xs.admin.upgrade.distribution.WebHome]]:
2 2  
3 3  1. Start the XWiki instance.
4 -1. Log in with a user that has [[programming rights>>Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRights"]].
5 -1. Choose how to proceed in the Welcome step of the Distribution Wizard:(((
6 -{{image reference="distribution-wizard-steps.png" size="large" alt="The Distribution Wizard Welcome step, presenting the steps and the Continue, Later and Never options"/}}
7 -
8 -* "Continue" moves to the next step.
9 -* "Later" prompts you again after XWiki is restarted. Its "Replay recorded actions" sub-option instead sends you to the [[Extension History>>extensions:Extension.Extension Manager Application||anchor="HExtensionHistory"]], where a history file exported from another wiki can be replayed.
10 -* "Never" discards the Distribution Wizard, leaving you to [[import the XAR>>documentation.xs.admin.imports.import-xwiki-pages.WebHome]] yourself.
4 +1. Log in with a user that has [[programming rights>>doc:Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRights"]].
5 +1. Click "Continue" in the [[Welcome step>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]] of the Distribution Wizard:(((
6 +{{image reference="distribution-wizard-steps.png" size="extra" alt="The Distribution Wizard Welcome step, presenting the steps and the Continue, Later and Never options"/}}
11 11  )))
12 -1. Upgrade the extensions installed on the wiki. On a subwiki you can only check the extensions installed on that subwiki; on the main wiki, "Check for updates" computes the plan for the main wiki and the global namespace, and "Check for updates on farm" for every wiki of the farm:(((
8 +1. Click "Upgrade" in the "Flavor" step to upgrade the flavor to the version that matches the distribution:(((
9 +{{image reference="flavor-step-upgrade.png" size="extra" alt="The Flavor step of the Distribution Wizard, offering to upgrade the installed flavor"/}}
10 +)))
11 +1. Click "Continue" to run the upgrade plan the wizard computed:(((
12 +{{image reference="flavor-upgrade-plan.png" size="extra" alt="The plan computed by the Distribution Wizard for upgrading the flavor"/}}
13 +)))
14 +1. Click "Continue" once the flavor is installed:(((
15 +{{image reference="flavor-step-installed.png" size="extra" alt="The Distribution Wizard reporting that the upgraded flavor has been installed"/}}
16 +)))
17 +1. Upgrade the [[extensions installed on the wiki>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]]:(((
13 13  {{gallery}}
14 14  [[image:check-extension-updates.png||alt="The Distribution Wizard step for checking extension upgrades"]]
15 15  [[image:check-updates-farm.png||alt="The Distribution Wizard checking extension upgrades on the whole farm"]]
... ... @@ -17,5 +17,5 @@
17 17  {{/gallery}}
18 18  )))
19 19  1. Click "Continue" to leave the report the Distribution Wizard produced. It lists the Pages that were updated, as follows:(((
20 -{{image reference="pages-distribution-wizard.png" size="large" alt="The Distribution Wizard report listing the Pages updated by the flavor upgrade"/}}
25 +{{image reference="pages-distribution-wizard.png" size="extra" alt="The Distribution Wizard report listing the Pages updated by the flavor upgrade"/}}
21 21  )))
check-extension-updates.png
Size
... ... @@ -1,1 +1,1 @@
1 -42.8 KB
1 +43.3 KB
Content
check-updates-farm.png
Size
... ... @@ -1,1 +1,1 @@
1 -46.1 KB
1 +46.5 KB
Content
check-updates-finish.png
Size
... ... @@ -1,1 +1,1 @@
1 -48.3 KB
1 +67.2 KB
Content
distribution-wizard-steps.png
Size
... ... @@ -1,1 +1,1 @@
1 -83.2 KB
1 +82.2 KB
Content
pages-distribution-wizard.png
Size
... ... @@ -1,1 +1,1 @@
1 -44.4 KB
1 +93.1 KB
Content
flavor-step-installed.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +47.5 KB
Content
flavor-step-upgrade.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +75.9 KB
Content
flavor-upgrade-plan.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +89.2 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,7 +1,3 @@
1 1  == Why do I need programming rights to run the Distribution Wizard when upgrading? ==
2 2  
3 -[[Extension Pages may need to be modified during the upgrade process>>documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.programming-rights-impact-distribution-wizard.WebHome]]. If the upgrade is performed with a user that does not have Programming Rights, these pages might not be updated correctly.
4 -
5 -== Are all the wikis upgraded automatically? ==
6 -
7 -No. On a farm you have to run the Distribution Wizard on every wiki, reaching each of them from the [[wiki index>>extensions:Extension.Wiki Application||anchor="HMenusandWikiIndex"]].
3 +[[Extension Pages may need to be modified during the upgrade process>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.programming-rights-impact-distribution-wizard.WebHome]]. If the upgrade is performed with a user that does not have Programming Rights, these Pages might not be updated correctly.
Related
... ... @@ -1,1 +1,2 @@
1 -* [[Install a Standalone (Demo) Distribution>>documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]].
1 +* [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]].
2 +* [[Install a Standalone (Demo) Distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]].

Edition of Distribution Wizard

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.elenicojocariu
Content
... ... @@ -1,268 +90,16 @@
1 -{{box cssClass="floatinginfobox" title="**Contents**"}}
2 -{{toc/}}
3 -{{/box}}
4 -
5 -The Distribution Wizard (also known as DW) is a feature which has several purposes:
6 -
7 -* It allows provisioning an empty wiki by allowing the administrator to select a [[Flavor>>Applications||anchor="#HFlavors"]] on the first run of XWiki
8 -* It allows to create an administration user account in the wiki.
9 -* It also allows upgrading an existing XWiki instance to a new version by upgrading all required Extensions
10 -
11 -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.
12 -
13 -= Clean Install =
14 -
15 -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>>||anchor="troubleshooting"]].
16 -
17 -== Welcome Step ==
18 -
19 -Upon first access, you will be greeted by the Distribution Wizard, offering you the 3 possible options:
20 -
21 -* **Continue**: when choosing this option, you will move to the next step of the Distribution Wizard
22 -* **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.
23 -* **Never**: Discards the DW and you will have to manually import the XAR
24 -
25 -{{image reference="dw-welcomeStep.png"/}}
26 -
27 -== Admin user ==
28 -
29 -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.
30 -
31 -{{image reference="dw-firstadminuserStep.png"/}}
32 -
33 -== User Interface ==
34 -
35 -Since 7.1 there is two modes for the Distribution Wizard: **Flavor** and **Default User Interface**.
36 -
37 -Since 9.5 the default mode is **Flavor**.
38 -
39 -To switch to **Default User Interface** mode you can do one of the following:
40 -
41 -* [since 10.2] have the following properties set properly in the file ##WEB-INF/xwiki.properties## of the web app:
42 -** ##distribution.defaultUI##: the extension ID[/version] of the application to use on the main wiki
43 -** ##distribution.defaultWikiUI##: the extension ID[/version] of the application to use on other wikis
44 -* [since 8.4] have the following properties set properly in the file ##META-INF/extension.xed## of the web app:
45 -** ##xwiki.extension.distribution.ui##: the extension ID of the application to use on the main wiki
46 -** ##xwiki.extension.distribution.ui.version##: the version of the application to use on the main wiki
47 -** ##xwiki.extension.distribution.wikiui##: the extension ID of the application to use on other wikis
48 -** ##xwiki.extension.distribution.wikiui.version##: the version of the application to use on other wikis
49 -* [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:
50 -** ##xwiki.extension.distribution.ui##: the extension ID of the application to use on the main wiki
51 -** ##xwiki.extension.distribution.ui.version##: the version of the application to use on the main wiki
52 -** ##xwiki.extension.distribution.wikiui##: the extension ID of the application to use on other wikis
53 -** ##xwiki.extension.distribution.wikiui.version##: the version of the application to use on other wikis
54 -
55 -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.
56 -
57 -=== Flavor step ===
58 -
59 -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.
60 -
61 -{{image reference="dw-flavor-step1.png"/}}
62 -
63 -* Select a flavor in the list of flavors.
64 -* Click on "install flavor".(((
65 -{{image reference="dw-flavor-step2.png"/}}
66 -)))
67 -* You can also select to let the wiki be empty.(((
68 -{{image reference="dw-noflavor.png"/}}
69 -)))
70 -* In the case you have selected a flavor, the following steps are similar to those described in the previous section (User Interface).
71 -
72 -=== Default User Interface ===
73 -
74 -The first step will check your XWiki version and will propose a version of the UI which is suited for your version.
75 -
76 -* Click on **Install** to install the proposed UI. This will resolve the extensions that are going to be installed.(((
77 -{{image reference="dw-uiStep.png"/}}
78 -)))
79 -* Click on the **Continue** button. This will start the actual installation of the previously resolved extensions.(((
80 -{{image reference="dw-uiStep-installPlan.png"/}}
81 -)))
82 -* You will be prompted to insert credentials for the Administrator, which are **Admin/admin**.(((
83 -{{image reference="dw-uiStep-login.png"/}}
84 -)))
85 -* After the instalation is complete, you can click on the Continue button to proceed to the next step.
86 -* Since this is a clean install, steps 2 and 3 are skipped.
87 -
88 -== Report step ==
89 -
90 90  {{info}}
91 -Since 5.4
2 +This documentation has moved to [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]].
92 92  {{/info}}
93 93  
94 -The last step display all changes brought to the wiki.
5 +{{id name="HCleanInstall"/}}{{id name="HUserInterface"/}}{{id name="HUpgrade"/}}{{id name="HUpgradewithRepair"/}}{{id name="troubleshooting"/}}
95 95  
96 -{{image reference="dw-report.png"/}}
7 +See [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]], which covers each part of this page:
97 97  
98 -= Upgrade =
99 -
100 -Distribution Wizard also allows you to perform an upgrade without having to manually import the XAR file.
101 -
102 -{{include reference="" section="HUserInterface"/}}
103 -
104 -== Orphaned dependencies step ==
105 -
106 -{{info}}
107 -Since 11.10
108 -{{/info}}
109 -
110 -{{image reference="orphaned.png"/}}
111 -
112 -This step is executed right after the Flavor step.
113 -
114 -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).
115 -
116 -== Wikis ==
117 -
118 -{{info}}
119 -Since 5.3 and only if there is a default UI configured.
120 -{{/info}}
121 -
122 -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.
123 -
124 -{{image reference="dw-wikisStep.png"/}}
125 -
126 -== Extensions ==
127 -
128 -{{image reference="dw-extensionsStep-checkForUpdates.png"/}}
129 -
130 -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:
131 -
132 -* computing the upgrade plan only for the main wiki + global namespace
133 -* computing the upgrade plan for the entire farm (all wikis + global namespace)
134 -
135 -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.
136 -
137 -{{image reference="dw-extensionsStep-computingUpgradePlan.png"/}}
138 -
139 -After the upgrade plan is computed there are two categories of extensions listed, as you can see in the image below:
140 -
141 -* invalid: they don't work with the current XWiki version so they must be upgraded
142 -* 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
143 -
144 -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.
145 -
146 -{{image reference="dw-extensionsStep.png"/}}
147 -
148 -= Upgrade with Repair =
149 -
150 -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.
151 -
152 -{{image reference="dw-uiStep-repair-upgradeQuestion.png"/}}
153 -
154 -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.
155 -
156 -{{image reference="dw-uiStep-repair-selectPreviousVersion.png"/}}
157 -
158 -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.
159 -
160 -{{image reference="dw-uiStep-repair-suggestPreviousId.png"/}}
161 -
162 -If it's not the right extension id then you should click on the pencil icon to change it.
163 -
164 -{{image reference="dw-uiStep-repair-editPreviousId.png"/}}
165 -
166 -Next you need to repair the previous UI extension. Just click on the Repair button.
167 -
168 -{{image reference="dw-uiStep-repair.png"/}}
169 -
170 -Finally you should be able to upgrade the default set of wiki pages like in a normal upgrade.
171 -
172 -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.
173 -
174 -{{image reference="dw-wikisStep-repairPreviousUI.png"/}}
175 -
176 -{{id name="troubleshooting"/}}
177 -
178 -= Replay Install or Upgrade =
179 -
180 -Starting with version 7.1 you can record an install or upgrade and replay it on a different wiki:
181 -
182 -* You start by following the steps described in the [[Clean Install>>||anchor="HCleanInstall"]], [[Upgrade>>||anchor="HUpgrade"]] or [[Upgrade with Repair>>||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+).
183 -* After you finished with the install/upgrade of the default/recommended UI (XAR), you can install/upgrade additional extensions.
184 -* 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
185 -* 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.(((
186 -{{image reference="dw-welcomeStep-replayRecordedActions.png"/}}
187 -)))
188 -* 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)(((
189 -{{image reference="extensionHistory.png"/}}
190 -)))
191 -* 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.
192 -* The Distribution Wizard should not appear next time you restart XWiki, but if it does, just click continue.
193 -
194 -= Automatic mode =
195 -
196 -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.
197 -
198 -The is several ways to do it:
199 -
200 -* since 10.2RC1 it's possible to disable interactive more in ##xwiki.properties## using the ##distribution.job.interactive## and ##distribution.job.interactive.wiki## properties
201 -* since 9.1RC1 it's possible start the ##distribution## job trough [[the Job REST API>>Documentation.UserGuide.Features.XWikiRESTfulAPI||anchor="HJobresources"]]
202 -
203 -{{info}}
204 -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>>||anchor="HUserInterface"]] for more details.
205 -{{/info}}
206 -
207 -= Troubleshooting =
208 -
209 -== The wizard fails to appear at startup ==
210 -
211 -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##).
212 -
213 -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>>Documentation.AdminGuide.InstallationViaAPT]] or ##/var/lib/tomcatX/webapps/...## for [[WAR installation>>Documentation.AdminGuide.InstallationWAR]]).
214 -
215 -{{version before="13.7RC1"}}
216 -The status file was not zipped and named: ##.../jobs/status/distribution/status.xml##.
217 -{{/version}}
218 -
219 -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.
220 -
221 -{{warning}}
222 -In order for the Distribution Wizard to be triggered, you have to log in as administrator (or superadmin if database is empty).
223 -{{/warning}}
224 -
225 -== Setting up new XWiki instance without reinstalling ==
226 -
227 -To set up empty/new XWiki instance you need to clear its database and local file storage.
228 -
229 -1. (((
230 -Empty the main database.
231 -For example with MySQL server, you can execute the command:
232 -
233 -{{code language="none"}}
234 -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';"
235 -{{/code}}
236 -
237 -where ##'password'## is password for xwiki user in MySQL database.
238 -
239 -You should also delete the subwikis databases if any.
240 -)))
241 -1. (((
242 -To clear local data in filesystem empty or remove the permanent directory (see environment.permanentDirectory property in xwiki.properties file).
243 -
244 -For example if you have installed XWiki using [[APT>>Documentation.AdminGuide.InstallationViaAPT]], execute command:
245 -
246 -{{code language="none"}}
247 -sudo rm -fr /var/lib/xwiki/data /var/cache/tomcat7/Catalina/localhost/xwiki/
248 -{{/code}}
249 -)))
250 -1. Restart the application server, open e.g. [[http://localhost:8080/xwiki]] and rerun distribution wizard again.
251 -
252 -== Disable the automatic start of Distribution Wizard {{info}}(Since 7.1RC1){{/info}} ==
253 -
254 -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##:
255 -
256 -{{code language="cfg"}}
257 -#-------------------------------------------------------------------------------------
258 -# Distribution Wizard
259 -#-------------------------------------------------------------------------------------
260 -
261 -#-# [Since 7.1RC1] Enable or disable the automatic start of Distribution Wizard on empty/outdated wiki.
262 -#-#
263 -#-# The default is:
264 -# distribution.automaticStartOnMainWiki=true
265 -# distribution.automaticStartOnWiki=true
266 -{{/code}}
267 -
268 -You just need to uncomment the above two lines and to set the options to ##false##.
9 +* [[Distribution Wizard Steps>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]].
10 +* [[Install the Flavor Using the Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.install-flavor.WebHome]].
11 +* [[Upgrade the Standard Flavor of the Wiki Using the Distribution Wizard>>doc:documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
12 +* [[Repair the Previously Installed Flavor>>doc:documentation.xs.admin.distribution-wizard.repair-previous-flavor.WebHome]].
13 +* [[Replay a Recorded Install or Upgrade>>doc:documentation.xs.admin.distribution-wizard.replay-recorded-actions.WebHome]].
14 +* [[Distribution Wizard Configuration>>doc:documentation.xs.admin.distribution-wizard.configuration.WebHome]].
15 +* [[Distribution Wizard Does Not Appear at Startup>>doc:documentation.xs.admin.distribution-wizard.not-appearing-startup.WebHome]].
16 +* [[Rerun the Distribution Wizard on an Empty Instance>>doc:documentation.xs.admin.distribution-wizard.rerun-empty-instance.WebHome]].

Edition of Install a Standalone (Demo) Distribution

Summary

Details

Page properties
Content
... ... @@ -8,8 +8,8 @@
8 8  1. Select one of the ZIP packages, according to your needs:(((
9 9  {{image reference="standalone-installation.png" size="medium" alt="The Demo Installation box displayed the two options of ZIP packages to download"/}}
10 10  
11 -* Standard Flavor Pre-installed: Includes the [[Standard Flavor>>extensions:Extension.XWiki Standard Flavor.WebHome]] and skips the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]]. Ideal for quick testing.
12 -* ZIP Package: Includes the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to choose your preferred Flavor during installation.
11 +* Standard Flavor Pre-installed: Includes the [[Standard Flavor>>extensions:Extension.XWiki Standard Flavor.WebHome]] and skips the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]]. Ideal for quick testing.
12 +* ZIP Package: Includes the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to choose your preferred Flavor during installation.
13 13  )))
14 14  1. Click "Download" to get the package.
15 15  ))){{id name="HInstallStandalone"/}}

Edition of Install XWiki without Internet Connection (XIP Package)

Summary

Details

Page properties
Content
... ... @@ -13,4 +13,4 @@
13 13  1. Ensure that the user running XWiki has write permissions on the extracted files.
14 14  1. Restart XWiki if it is currently running.
15 15  1. Access your XWiki by pointing your web browser to {{code language="none"}}http://localhost:8080/xwiki{{/code}}.
16 -1. Resume the standard XWiki installation process. The [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]] will use the locally available extensions instead of downloading them from the Internet.
16 +1. Resume the standard XWiki installation process. The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] will use the locally available extensions instead of downloading them from the Internet.

Edition of XIP Package Installation

Summary

Details

Page properties
Content
... ... @@ -1,5 +1,5 @@
1 1  The XIP package contains the Wiki UI and can be used in case you want to continue the [[installation of XWiki offline.>>doc:documentation.xs.admin.installation.install-offline.WebHome]]
2 2  
3 -After installing XWiki using one of the available [[installation methods>>doc:documentation.xs.admin.installation.methods.WebHome]], your wiki is initially empty, meaning it does not contain any wiki Pages. Since applications in XWiki are implemented as wiki Pages, no applications are available at this stage. As a result, the [[Extension Manager>>extensions:Extension.Extension Manager Application]] (which is itself an application used to install extensions) is also not yet available. The ##XIP## package allows the [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]] to find the necessary extensions locally instead of downloading them from the internet, making it suitable for offline installations of XWiki.
3 +After installing XWiki using one of the available [[installation methods>>doc:documentation.xs.admin.installation.methods.WebHome]], your wiki is initially empty, meaning it does not contain any wiki Pages. Since applications in XWiki are implemented as wiki Pages, no applications are available at this stage. As a result, the [[Extension Manager>>extensions:Extension.Extension Manager Application]] (which is itself an application used to install extensions) is also not yet available. The ##XIP## package allows the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to find the necessary extensions locally instead of downloading them from the internet, making it suitable for offline installations of XWiki.
4 4  
5 5  If, after installing XWiki, you want to continue the setup offline, you can install the XIP package. This package provides an offline extension repository that includes the [[Standard Flavor>>extensions:Extension.XWiki Standard Flavor.WebHome]] and all of its required extensions.

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.elenicojocariu
Content
... ... @@ -44,6 +44,6 @@
44 44  {{/code}}
45 45  )))
46 46  1. Open XWiki in your browser at {{code language="none"}}http://localhost:8080{{/code}}.
47 -1. Follow the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to finish the installation.
47 +1. Follow the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to finish the installation.
48 48  
49 49  {{display reference="documentation.xs.admin.installation.methods.install-xwiki-docker.docker-run.run-xwiki-mysql-tomcat.note-replace-placeholders.WebHome"/}}

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.elenicojocariu
Content
... ... @@ -44,6 +44,6 @@
44 44  {{/code}}
45 45  )))
46 46  1. Open XWiki in your browser at {{code language="none"}}http://localhost:8080{{/code}}.
47 -1. Follow the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to finish the installation.
47 +1. Follow the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to finish the installation.
48 48  
49 49  {{display reference="documentation.xs.admin.installation.methods.install-xwiki-docker.docker-run.run-xwiki-mysql-tomcat.note-replace-placeholders.WebHome"/}}

Edition of Run XWiki (PostgreSQL on Tomcat) Using Docker Run

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.elenicojocariu
Content
... ... @@ -34,6 +34,6 @@
34 34  {{/code}}
35 35  )))
36 36  1. Open XWiki in your browser at {{code language="none"}}http://localhost:8080{{/code}}.
37 -1. Follow the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to finish the installation.
37 +1. Follow the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to finish the installation.
38 38  
39 39  {{display reference="documentation.xs.admin.installation.methods.install-xwiki-docker.docker-run.run-xwiki-mysql-tomcat.note-replace-placeholders.WebHome"/}}

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -40,7 +40,7 @@
40 40  {{/code}}
41 41  )))
42 42  1. Open XWiki in your browser at {{code language="none"}}http://localhost:8080{{/code}}.
43 -1. Follow the [[Distribution Wizard>>doc:Documentation.UserGuide.Features.DistributionWizard]] to finish the installation.
43 +1. Follow the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] to finish the installation.
44 44  
45 45  Don't forget to replace ##xwiki-nw## with the name of your Docker network, the ##/my/path/...## directories and the values of the [[environment variables>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.environment-variables.WebHome]] with your own, and ##18.5.0## with the XWiki version behind the ##xwiki:stable-mysql-tomcat## tag you use.
46 46  

Edition of Sub-Directories in the Permanent Directory

Summary

Details

Page properties
Content
... ... @@ -23,7 +23,7 @@
23 23  * Starting with {{version since="17.2.0RC1,16.10.6"}} the path is prefixed with a store version (currently ##3##) to account for differences in how job IDs are mapped to file names across versions. {{/version}}
24 24  * Most entries are used only to track job execution and are generally safe to remove. However, some jobs may rely on their stored status.
25 25  * Examples of standard job directories (extensions may add more):
26 -** ##jobs/status/3/distribution##: Stores decisions made in the [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]] (typically during [[installation>>documentation.xs.admin.installation.WebHome]] or [[upgrade>>documentation.xs.admin.upgrade.WebHome]]). It is recommended to keep this data. If removed, the worst case is that the Distribution Wizard may appear again on the next startup (e.g., if a [[DW step>>Documentation.UserGuide.Features.DistributionWizard]] is triggered), and some steps may need to be canceled again.
26 +** ##jobs/status/3/distribution##: Stores decisions made in the [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] (typically during [[installation>>documentation.xs.admin.installation.WebHome]] or [[upgrade>>documentation.xs.admin.upgrade.WebHome]]). It is recommended to keep this data. If removed, the worst case is that the Distribution Wizard may appear again on the next startup (e.g., if a [[Distribution Wizard step>>doc:documentation.xs.admin.distribution-wizard.steps.WebHome]] is triggered), and some steps may need to be canceled again.
27 27  ** ##jobs/status/3/extension##: Stores logs of [[extension install>>extensions:Extension.Extension Manager Application]] and uninstall operations. Safe to remove; only the operation history is lost.
28 28  ** ##jobs/status/3/refactoring##: Stores logs of [[refactoring operations>>doc:documentation.xs.user.base.page.page-refactoring-operations.WebHome]]. Safe to remove; only the operation history is lost.
29 29  ** ##jobs/status/3/solr/indexer##: Stores logs of [[Solr indexing operations>>extensions:Extension.Solr Search API]]. Safe to remove; only the operation history is lost.

Edition of Programming Rights Impact on Distribution Wizard

Summary

Details

Page properties
Content
... ... @@ -1,4 +1,4 @@
1 -The [[Distribution Wizard>>Documentation.UserGuide.Features.DistributionWizard]] must be executed using a user with [[Programming Rights>>Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRight"]] when performing an [[upgrade of the flavor>>documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
1 +The [[Distribution Wizard>>doc:documentation.xs.admin.distribution-wizard.WebHome]] must be executed using a user with [[Programming Rights>>Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRight"]] when performing an [[upgrade of the flavor>>documentation.xs.admin.upgrade.flavor.upgrade-distribution-wizard.WebHome]].
2 2  
3 3  [[Extension Pages>>documentation.xs.user.base.page.edit-page.extension-page-protection.WebHome]] may need to be modified during the upgrade process. If the upgrade is performed with a user that does not have Programming Rights, these Pages might not be updated correctly. The following Pages may need to be modified by the Distribution Wizard and therefore require Programming Rights:
4 4  

Edition of Why does the Distribution Wizard fail to appear after an install?

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.elenicojocariu
FAQCode.FAQClass[0]
answer
... ... @@ -1,1 +1,1 @@
1 -See the [[Distribution Wizard's troubleshooting section>>Documentation.UserGuide.Features.DistributionWizard#troubleshooting]].
1 +See [[Distribution Wizard Does Not Appear at Startup>>doc:documentation.xs.admin.distribution-wizard.not-appearing-startup.WebHome]].

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.
This Change Request is ready for review.
No conflicts to show.
The change request cannot be published without valid approval or if at least one review request for changes.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected