Wiki source code of Distribution Wizard

Last modified by Eleni Cojocariu on 2026/11/13 12:30

Show last authors
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.xs.user.flavors.WebHome]], 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 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
11 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
12 skinparam activity {
13 BackgroundColor #0568AE
14 BorderColor #034873
15 FontColor #FFFFFF
16 StartColor #04538B
17 EndColor #04538B
18 BarColor #5A5A5A
19 ' Diamonds are blue with white text, not light with dark text: a labelled
20 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
21 ' FontColor above, so a light fill draws that one box white on white, and no
22 ' selector reaches it without reaching the decision diamonds too.
23 DiamondBackgroundColor #0568AE
24 DiamondBorderColor #034873
25 DiamondFontColor #FFFFFF
26 }
27 skinparam state {
28 BackgroundColor #0568AE
29 BorderColor #034873
30 FontColor #FFFFFF
31 AttributeFontColor #FFFFFF
32 StartColor #04538B
33 EndColor #04538B
34 }
35 skinparam class {
36 BackgroundColor #0568AE
37 BorderColor #034873
38 FontColor #FFFFFF
39 HeaderBackgroundColor #0568AE
40 AttributeFontColor #FFFFFF
41 StereotypeFontColor #262626
42 }
43 skinparam object {
44 BackgroundColor #0568AE
45 BorderColor #034873
46 FontColor #FFFFFF
47 AttributeFontColor #FFFFFF
48 StereotypeFontColor #262626
49 }
50 skinparam participant {
51 BackgroundColor #0568AE
52 BorderColor #034873
53 FontColor #FFFFFF
54 }
55 skinparam actor {
56 BackgroundColor #F5F5F5
57 BorderColor #5A5A5A
58 FontColor #262626
59 }
60 skinparam component {
61 BackgroundColor #0568AE
62 BorderColor #034873
63 FontColor #FFFFFF
64 }
65 skinparam collections {
66 BackgroundColor #0568AE
67 BorderColor #034873
68 FontColor #FFFFFF
69 }
70 skinparam queue {
71 BackgroundColor #0568AE
72 BorderColor #034873
73 FontColor #FFFFFF
74 }
75 skinparam stack {
76 BackgroundColor #0568AE
77 BorderColor #034873
78 FontColor #FFFFFF
79 }
80 ' database, control, entity, boundary and interface draw their label beside or
81 ' under the icon, on the page, in some diagram types: their text stays dark.
82 skinparam database {
83 BackgroundColor #F5F5F5
84 BorderColor #5A5A5A
85 FontColor #262626
86 }
87 skinparam control {
88 BackgroundColor #0568AE
89 BorderColor #034873
90 FontColor #262626
91 }
92 skinparam entity {
93 BackgroundColor #0568AE
94 BorderColor #034873
95 FontColor #262626
96 }
97 skinparam boundary {
98 BackgroundColor #0568AE
99 BorderColor #034873
100 FontColor #262626
101 }
102 skinparam usecase {
103 BackgroundColor #0568AE
104 BorderColor #034873
105 FontColor #FFFFFF
106 StereotypeFontColor #FFFFFF
107 }
108 skinparam card {
109 BackgroundColor #04538B
110 BorderColor #034873
111 FontColor #FFFFFF
112 }
113 skinparam note {
114 BackgroundColor #04538B
115 BorderColor #034873
116 FontColor #FFFFFF
117 }
118 skinparam storage {
119 BackgroundColor #8A4A00
120 BorderColor #8A4A00
121 FontColor #FFFFFF
122 }
123 skinparam agent {
124 BackgroundColor #8A4A00
125 BorderColor #8A4A00
126 FontColor #FFFFFF
127 }
128 skinparam interface {
129 BackgroundColor #A62222
130 BorderColor #A62222
131 FontColor #262626
132 }
133 skinparam node {
134 BackgroundColor #F5F5F5
135 BorderColor #5A5A5A
136 FontColor #262626
137 }
138 skinparam cloud {
139 BackgroundColor #F5F5F5
140 BorderColor #5A5A5A
141 FontColor #262626
142 }
143 skinparam artifact {
144 BackgroundColor #F5F5F5
145 BorderColor #5A5A5A
146 FontColor #262626
147 }
148 skinparam file {
149 BackgroundColor #F5F5F5
150 BorderColor #5A5A5A
151 FontColor #262626
152 }
153 skinparam rectangle {
154 BackgroundColor #FFFFFF
155 BorderColor #5A5A5A
156 FontColor #262626
157 StereotypeFontColor #0568AE
158 }
159 skinparam folder {
160 BackgroundColor #F5F5F5
161 BorderColor #8A4A00
162 FontColor #8A4A00
163 }
164 skinparam frame {
165 BackgroundColor #F5F5F5
166 BorderColor #04538B
167 FontColor #04538B
168 }
169 skinparam package {
170 BackgroundColor #FFFFFF
171 BorderColor #0568AE
172 FontColor #262626
173 }
174 skinparam partition {
175 BackgroundColor #FFFFFF
176 BorderColor #0568AE
177 FontColor #0568AE
178 }
179 skinparam swimlane {
180 BorderColor #0568AE
181 TitleBackgroundColor #F5F5F5
182 TitleFontColor #0568AE
183 }
184 skinparam sequence {
185 BoxBackgroundColor #F5F5F5
186 BoxBorderColor #5A5A5A
187 BoxFontColor #262626
188 DelayFontColor #262626
189 GroupBorderColor #5A5A5A
190 GroupFontColor #262626
191 LifeLineBorderColor #5A5A5A
192 LifeLineBackgroundColor #F5F5F5
193 TitleFontColor #0568AE
194 StartColor #0568AE
195 EndColor #0568AE
196 BorderColor #0568AE
197 }
198 skinparam arrow {
199 Color #0568AE
200 FontColor #262626
201 }
202 skinparam legend {
203 BackgroundColor #F5F5F5
204 BorderColor #5A5A5A
205 FontColor #262626
206 }
207 skinparam stereotype {
208 CBackgroundColor #F5F5F5
209 CBorderColor #5A5A5A
210 ABackgroundColor #F5F5F5
211 ABorderColor #5A5A5A
212 IBackgroundColor #F5F5F5
213 IBorderColor #5A5A5A
214 EBackgroundColor #F5F5F5
215 EBorderColor #5A5A5A
216 NBackgroundColor #F5F5F5
217 NBorderColor #5A5A5A
218 }
219 skinparam ArrowColor #0568AE
220 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
221 ' leaks its background onto every element in the diagram.
222 skinparam titleFontColor #0568AE
223 skinparam titleBorderColor #5A5A5A
224 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
225 <style>
226 root {
227 HyperLinkColor #0568AE
228 }
229 element {
230 HyperLinkColor #FFFFFF
231 }
232 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
233 legend, node, package, rectangle {
234 HyperLinkColor #0568AE
235 }
236 </style>
237 ' ---- end XWiki accessible diagram palette ----
238 start
239 :XWiki starts;
240 if (Interactive mode?) then (no)
241 :The distribution job runs at once,\\nfirst on the main wiki then on the other\\nwikis, and takes the decisions on its own;
242 stop
243 endif
244 :A user allowed to run the wizard\\nrequests a page;
245 if (Automatic start enabled\\nfor this wiki?) then (no)
246 :The wizard stays closed;
247 stop
248 endif
249 if (Default user interface\\nconfigured?) then (yes)
250 :Default user interface mode:\\nthe "User Interface" step, and "Wikis"\\nfor the other wikis of the farm;
251 else (no)
252 :Flavor mode:\\nthe "Flavor" step;
253 endif
254 if (Any step with something to do?) then (no)
255 :The wizard stays closed;
256 stop
257 endif
258 :The wizard opens in the browser,\\nfrom "Welcome" to "Report";
259 stop
260 @enduml
261 {{/plantuml}}
262
263 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:
264
265 * [[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.
266 * [[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.
267 * [[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.
268 * [[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.
269 * [[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.
270
271 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]].

Get Connected