Skip to Content

Wiki source code of why-upgrade-xwiki

Version 1.4 by Alex Cotiuga on 2026/05/12 14:47
Hide last authors
Alex Cotiuga 1.4 1 {{velocity}}
2 #set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 {{html clean="false"}}
Alex Cotiuga 1.1 4
Alex Cotiuga 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>
Alex Cotiuga 1.1 12
Alex Cotiuga 1.4 13 <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
Alex Cotiuga 1.1 14
Alex Cotiuga 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>
Alex Cotiuga 1.1 19
Alex Cotiuga 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>
Alex Cotiuga 1.1 24
Alex Cotiuga 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>
Alex Cotiuga 1.1 31
Alex Cotiuga 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>
Alex Cotiuga 1.1 36
Alex Cotiuga 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>
Alex Cotiuga 1.1 42
Alex Cotiuga 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>
Alex Cotiuga 1.1 58
Alex Cotiuga 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>
Alex Cotiuga 1.1 73
Alex Cotiuga 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>
Alex Cotiuga 1.1 91
Alex Cotiuga 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>
Alex Cotiuga 1.1 96
Alex Cotiuga 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>
Alex Cotiuga 1.1 101
Alex Cotiuga 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>
Alex Cotiuga 1.1 114
Alex Cotiuga 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>
Alex Cotiuga 1.1 126
Alex Cotiuga 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>
Alex Cotiuga 1.1 138
Alex Cotiuga 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>
Alex Cotiuga 1.1 150
Alex Cotiuga 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>
Alex Cotiuga 1.1 162
Alex Cotiuga 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>
Alex Cotiuga 1.1 177
Alex Cotiuga 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>
Alex Cotiuga 1.1 184
Alex Cotiuga 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>
Alex Cotiuga 1.1 189
Alex Cotiuga 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>
Alex Cotiuga 1.1 195
Alex Cotiuga 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>
Alex Cotiuga 1.1 221
Alex Cotiuga 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>
Alex Cotiuga 1.1 226
Alex Cotiuga 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>
Alex Cotiuga 1.1 231
Alex Cotiuga 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>
Alex Cotiuga 1.1 242
Alex Cotiuga 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>
Alex Cotiuga 1.1 252
Alex Cotiuga 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>
Alex Cotiuga 1.1 262
Alex Cotiuga 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>
Alex Cotiuga 1.1 275
Alex Cotiuga 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>
Alex Cotiuga 1.1 281
Alex Cotiuga 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>
Alex Cotiuga 1.1 286
Alex Cotiuga 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>
Alex Cotiuga 1.1 291
292 {{/html}}
Alex Cotiuga 1.4 293 {{/velocity}}