Skip to Content

Wiki source code of why-upgrade-xwiki

Version 1.4 by Agnease on 2026/05/12 14:47
Hide last authors
Agnease 1.4 1 {{velocity}}
2 #set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 {{html clean="false"}}
Agnease 1.1 4
Agnease 1.4 5 ## PAGE HEADER
6 <section class="hero hero-centered service-hero" aria-labelledby="hero-title">
7 <div class="container hero-inner">
8 <div class="hero-kicker">
9 <i class="fa fa-refresh" aria-hidden="true"></i>
10 XWiki upgrade guidance
11 </div>
Agnease 1.1 12
Agnease 1.4 13 <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
Agnease 1.1 14
Agnease 1.4 15 <p class="lead">
16 A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
17 when upgrades are postponed for too long.
18 </p>
Agnease 1.1 19
Agnease 1.4 20 <p class="hero-support">
21 Regular upgrades help keep XWiki secure, stable, compatible and easier to evolve, especially when the platform
22 is used for internal knowledge, documentation, procedures, workflows or business-critical collaboration.
23 </p>
Agnease 1.1 24
Agnease 1.4 25 <div class="hero-actions">
26 <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View upgrade services</a>
27 <a class="btn btn-secondary" href="#upgrade-tips">Read upgrade tips</a>
28 </div>
29 </div>
30 </section>
Agnease 1.1 31
Agnease 1.4 32 ## WHY IT MATTERS
33 <section aria-labelledby="why-title">
34 <div class="container">
35 <h2 id="why-title">“It still works” is not the same as “it is safe to keep unchanged”</h2>
Agnease 1.1 36
Agnease 1.4 37 <p class="section-intro">
38 Many XWiki instances continue to run for years with only small visible problems. That can create the impression
39 that upgrades are optional. In practice, the longer an instance stays behind, the more risk accumulates around
40 security fixes, extension compatibility, infrastructure changes, custom code and future upgrade effort.
41 </p>
Agnease 1.1 42
Agnease 1.4 43 <div class="pathways">
44 <article class="pathway-card">
45 <div class="pathway-icon">
46 <i class="fa fa-shield" aria-hidden="true"></i>
47 </div>
48 <h3>Security fixes accumulate</h3>
49 <p>
50 Older versions may miss security-related fixes and improvements that are already available in newer releases.
51 </p>
52 <ul>
53 <li>Known issues may already be fixed upstream</li>
54 <li>Public information about vulnerabilities increases risk over time</li>
55 <li>Security updates are easier to handle when upgrades are regular</li>
56 </ul>
57 </article>
Agnease 1.1 58
Agnease 1.4 59 <article class="pathway-card">
60 <div class="pathway-icon">
61 <i class="fa fa-puzzle-piece" aria-hidden="true"></i>
62 </div>
63 <h3>Compatibility becomes harder</h3>
64 <p>
65 Extensions, custom applications, authentication integrations and infrastructure components evolve together.
66 </p>
67 <ul>
68 <li>Extensions may require newer XWiki versions</li>
69 <li>Java, Tomcat and database requirements can change</li>
70 <li>Large version jumps are harder to validate</li>
71 </ul>
72 </article>
Agnease 1.1 73
Agnease 1.4 74 <article class="pathway-card">
75 <div class="pathway-icon">
76 <i class="fa fa-line-chart" aria-hidden="true"></i>
77 </div>
78 <h3>Maintenance cost increases</h3>
79 <p>
80 The longer upgrades are postponed, the more difficult it becomes to understand what changed and what may break.
81 </p>
82 <ul>
83 <li>More release notes to review</li>
84 <li>More compatibility checks to perform</li>
85 <li>More risk around custom code and old assumptions</li>
86 </ul>
87 </article>
88 </div>
89 </div>
90 </section>
Agnease 1.1 91
Agnease 1.4 92 ## WHAT TO REVIEW
93 <section id="upgrade-tips" class="services" aria-labelledby="tips-title">
94 <div class="container">
95 <h2 id="tips-title">Practical tips before planning an XWiki upgrade</h2>
Agnease 1.1 96
Agnease 1.4 97 <p class="section-intro">
98 A good upgrade starts before the installation step. The most useful preparation is to understand the current
99 platform, identify what is business-critical and validate the upgrade outside production.
100 </p>
Agnease 1.1 101
Agnease 1.4 102 <div class="services-grid">
103 <article class="service">
104 <div class="service-icon" aria-hidden="true">
105 <i class="fa fa-code-fork"></i>
106 </div>
107 <div class="service-body">
108 <h4>Check your current version and target version</h4>
109 <p>
110 Identify the current XWiki version, the desired target version and whether intermediate upgrade steps are needed.
111 </p>
112 </div>
113 </article>
Agnease 1.1 114
Agnease 1.4 115 <article class="service">
116 <div class="service-icon" aria-hidden="true">
117 <i class="fa fa-puzzle-piece"></i>
118 </div>
119 <div class="service-body">
120 <h4>Review installed extensions</h4>
121 <p>
122 List installed extensions and check whether they are compatible with the target XWiki version.
123 </p>
124 </div>
125 </article>
Agnease 1.1 126
Agnease 1.4 127 <article class="service">
128 <div class="service-icon" aria-hidden="true">
129 <i class="fa fa-code"></i>
130 </div>
131 <div class="service-body">
132 <h4>Identify custom code</h4>
133 <p>
134 Review custom macros, Velocity scripts, Java components, UI extensions, sheets, templates and local changes.
135 </p>
136 </div>
137 </article>
Agnease 1.1 138
Agnease 1.4 139 <article class="service">
140 <div class="service-icon" aria-hidden="true">
141 <i class="fa fa-lock"></i>
142 </div>
143 <div class="service-body">
144 <h4>Validate authentication</h4>
145 <p>
146 LDAP, Active Directory, SSO, OIDC, SAML and MFA configurations should be tested carefully after the upgrade.
147 </p>
148 </div>
149 </article>
Agnease 1.1 150
Agnease 1.4 151 <article class="service">
152 <div class="service-icon" aria-hidden="true">
153 <i class="fa fa-database"></i>
154 </div>
155 <div class="service-body">
156 <h4>Prepare backups and a staging clone</h4>
157 <p>
158 Never treat production as the first test. Validate the upgrade on staging or a temporary clone first.
159 </p>
160 </div>
161 </article>
Agnease 1.1 162
Agnease 1.4 163 <article class="service">
164 <div class="service-icon" aria-hidden="true">
165 <i class="fa fa-check-square-o"></i>
166 </div>
167 <div class="service-body">
168 <h4>Create a validation checklist</h4>
169 <p>
170 Test login, permissions, search, dashboards, PDFs, custom applications, jobs, important pages and integrations.
171 </p>
172 </div>
173 </article>
174 </div>
175 </div>
176 </section>
Agnease 1.1 177
Agnease 1.4 178 ## SAFE PROCESS
179 <section class="split-section" aria-labelledby="process-title">
180 <div class="container">
181 <div class="split-grid">
182 <div class="split-copy">
183 <h2 id="process-title">The safest upgrade is the one rehearsed before production</h2>
Agnease 1.1 184
Agnease 1.4 185 <p>
186 A production upgrade should not be the first time the process is tested. A staging environment or temporary
187 clone allows problems to be discovered before they affect users.
188 </p>
Agnease 1.1 189
Agnease 1.4 190 <p>
191 This is especially important when the instance includes custom applications, authentication integrations,
192 PDF exports, workflows, advanced permissions or business-critical documentation.
193 </p>
194 </div>
Agnease 1.1 195
Agnease 1.4 196 <ol class="process-list">
197 <li>
198 <strong>Prepare a staging clone</strong>
199 Copy the relevant database, filesystem and configuration into a controlled non-production environment.
200 </li>
201 <li>
202 <strong>Run the upgrade there first</strong>
203 Apply the upgrade, resolve compatibility issues and record the steps required.
204 </li>
205 <li>
206 <strong>Validate business-critical features</strong>
207 Confirm that authentication, rights, search, exports, custom apps and important workflows still work.
208 </li>
209 <li>
210 <strong>Plan the production window</strong>
211 Define backup, downtime, rollback and communication expectations before touching production.
212 </li>
213 <li>
214 <strong>Document the result</strong>
215 Keep upgrade notes, observed issues and follow-up recommendations for the next maintenance cycle.
216 </li>
217 </ol>
218 </div>
219 </div>
220 </section>
Agnease 1.1 221
Agnease 1.4 222 ## COMMON MISTAKES
223 <section aria-labelledby="mistakes-title">
224 <div class="container">
225 <h2 id="mistakes-title">Common mistakes to avoid</h2>
Agnease 1.1 226
Agnease 1.4 227 <p class="section-intro">
228 Most difficult upgrades are not difficult because XWiki cannot be upgraded. They become difficult because
229 the environment, customizations or validation steps were not understood early enough.
230 </p>
Agnease 1.1 231
Agnease 1.4 232 <div class="widgets">
233 <article class="widget">
234 <div class="icon" aria-hidden="true">
235 <i class="fa fa-warning"></i>
236 <h4>Upgrading<br />directly in production</h4>
237 </div>
238 <p>
239 Production should not be the first place where compatibility issues are discovered.
240 </p>
241 </article>
Agnease 1.1 242
Agnease 1.4 243 <article class="widget">
244 <div class="icon" aria-hidden="true">
245 <i class="fa fa-puzzle-piece"></i>
246 <h4>Ignoring<br />extensions</h4>
247 </div>
248 <p>
249 Extensions and custom code often create the real upgrade complexity.
250 </p>
251 </article>
Agnease 1.1 252
Agnease 1.4 253 <article class="widget">
254 <div class="icon" aria-hidden="true">
255 <i class="fa fa-lock"></i>
256 <h4>Testing only<br />public pages</h4>
257 </div>
258 <p>
259 Login, permissions, restricted spaces and admin features should also be validated.
260 </p>
261 </article>
Agnease 1.1 262
Agnease 1.4 263 <article class="widget">
264 <div class="icon" aria-hidden="true">
265 <i class="fa fa-file-text-o"></i>
266 <h4>No upgrade<br />notes</h4>
267 </div>
268 <p>
269 Without notes, every future upgrade starts again from uncertainty.
270 </p>
271 </article>
272 </div>
273 </div>
274 </section>
Agnease 1.1 275
Agnease 1.4 276 ## CTA
277 <section class="cta-section" aria-labelledby="cta-title">
278 <div class="container">
279 <div class="cta-panel">
280 <h2 id="cta-title">Need help planning an XWiki upgrade?</h2>
Agnease 1.1 281
Agnease 1.4 282 <p>
283 If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
284 the current version, extensions, infrastructure and validation needs before planning the production upgrade.
285 </p>
Agnease 1.1 286
Agnease 1.4 287 <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View XWiki upgrade services</a>
288 </div>
289 </div>
290 </section>
Agnease 1.1 291
292 {{/html}}
Agnease 1.4 293 {{/velocity}}