Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 1.4
edited by Agnease
on 2026/05/12 14:47
Change comment: There is no comment for this version
To version 1.10
edited by Agnease
on 2026/05/12 14:56
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -2,292 +2,167 @@
2 2  #set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 3  {{html clean="false"}}
4 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
5 + <section class="resource-header" aria-labelledby="hero-title">
6 + <div class="container">
7 + <div class="text-center">
8 + <div class="resource-kicker">
9 + <i class="fa fa-refresh" aria-hidden="true"></i>
10 + XWiki upgrade guidance
11 + </div>
11 11   </div>
12 12  
13 13   <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
14 14  
15 - <p class="lead">
16 + <p class="resource-summary">
16 16   A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
17 17   when upgrades are postponed for too long.
18 18   </p>
19 -
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>
24 -
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 29   </div>
30 30   </section>
31 31  
32 - ## WHY IT MATTERS
33 - <section aria-labelledby="why-title">
23 + <section class="resource-page">
34 34   <div class="container">
35 - <h2 id="why-title">“It still works” is not the same as “it is safe to keep unchanged”</h2>
25 + <div class="resource-layout">
36 36  
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>
27 + <article class="resource-content">
42 42  
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 49   <p>
50 - Older versions may miss security-related fixes and improvements that are already available in newer releases.
30 + Many XWiki instances continue to run for years with only small visible problems. This can create the
31 + impression that upgrades are optional, especially when users can still log in, search, edit pages and
32 + access the content they need.
51 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>
58 58  
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 64   <p>
65 - Extensions, custom applications, authentication integrations and infrastructure components evolve together.
36 + The real risk is that technical debt accumulates quietly. Security fixes, extension compatibility,
37 + authentication behavior, infrastructure requirements and custom code assumptions continue to evolve.
38 + The longer an instance remains behind, the more difficult the next upgrade becomes.
66 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>
73 73  
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>
91 -
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>
96 -
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>
101 -
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>
41 + <div class="resource-note">
109 109   <p>
110 - Identify the current XWiki version, the desired target version and whether intermediate upgrade steps are needed.
43 + <strong>The main point:</strong> regular upgrades are not only about new features. They reduce security
44 + exposure, compatibility risk and long-term maintenance cost.
111 111   </p>
112 112   </div>
113 - </article>
114 114  
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>
48 + <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
126 126  
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>
50 + <h3>1. Security fixes accumulate over time</h3>
51 + <p>
52 + Older versions may miss security-related fixes already available in newer releases. Once security issues
53 + become publicly known, running an old version can become a more predictable risk.
54 + </p>
138 138  
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>
56 + <p>
57 + This does not mean every old instance is immediately exposed in the same way. The real impact depends on
58 + your configuration, installed extensions, access model, authentication setup and whether the instance is
59 + public or private. But staying close to supported versions makes security maintenance more manageable.
60 + </p>
150 150  
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>
62 + <h3>2. Large upgrade gaps are harder to control</h3>
63 + <p>
64 + A small, regular upgrade is usually easier to validate than a large jump after several years. Large gaps
65 + mean more release notes, more compatibility changes, more extension checks and more uncertainty around
66 + custom code.
67 + </p>
162 162  
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>
69 + <h3>3. Extensions and customizations can become fragile</h3>
70 + <p>
71 + XWiki instances often include installed extensions, custom Velocity scripts, macros, templates, sheets,
72 + UI extensions, Java components or business-specific applications. These elements need to be reviewed when
73 + planning an upgrade.
74 + </p>
177 177  
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>
184 -
76 + <h3>4. Infrastructure requirements evolve</h3>
185 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.
78 + XWiki upgrades can involve more than the application itself. Java, Tomcat, the database, Docker images,
79 + reverse proxy configuration, PDF export services and authentication integrations may also need attention.
188 188   </p>
189 189  
82 + <h3>5. Business-critical features need validation</h3>
190 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.
84 + A successful upgrade is not only one where the server starts. Users usually depend on login, permissions,
85 + search, dashboards, PDF exports, workflows, notifications, custom applications and important pages. These
86 + should be part of the validation plan.
193 193   </p>
194 - </div>
195 195  
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>
89 + <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
221 221  
222 - ## COMMON MISTAKES
223 - <section aria-labelledby="mistakes-title">
224 - <div class="container">
225 - <h2 id="mistakes-title">Common mistakes to avoid</h2>
91 + <ul class="resource-checklist">
92 + <li>Identify the current XWiki version and the target version.</li>
93 + <li>Check whether intermediate upgrade steps are needed.</li>
94 + <li>List installed extensions and verify compatibility with the target version.</li>
95 + <li>Identify custom code: Velocity scripts, macros, sheets, templates, UI extensions and Java components.</li>
96 + <li>Review authentication: LDAP, Active Directory, SSO, OIDC, SAML or MFA.</li>
97 + <li>Prepare a staging environment or temporary clone of production.</li>
98 + <li>Validate backups and clarify rollback expectations.</li>
99 + <li>Test important pages, dashboards, permissions, search, jobs, exports and custom workflows.</li>
100 + <li>Document the steps, issues found and follow-up recommendations.</li>
101 + </ul>
226 226  
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>
103 + <h2 id="safe-process">A safer upgrade process</h2>
231 231  
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 238   <p>
239 - Production should not be the first place where compatibility issues are discovered.
106 + Production should not be the first place where the upgrade is tested. The safest approach is to rehearse
107 + the upgrade on staging or a temporary clone, resolve compatibility issues there, then perform the production
108 + upgrade with a clear plan.
240 240   </p>
241 - </article>
242 242  
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>
111 + <ol>
112 + <li><strong>Prepare a clone:</strong> copy the relevant database, filesystem and configuration.</li>
113 + <li><strong>Run the upgrade outside production:</strong> record the steps and issues found.</li>
114 + <li><strong>Validate critical features:</strong> login, rights, search, PDFs, workflows, dashboards and integrations.</li>
115 + <li><strong>Plan the production window:</strong> backups, downtime, rollback and communication.</li>
116 + <li><strong>Document the result:</strong> keep notes for the next upgrade cycle.</li>
117 + </ol>
118 +
119 + <h2 id="common-mistakes">Common mistakes to avoid</h2>
120 +
121 + <ul>
122 + <li><strong>Upgrading directly in production.</strong> Compatibility issues should be discovered before users are affected.</li>
123 + <li><strong>Checking only public pages.</strong> Authentication, restricted spaces and admin features also need validation.</li>
124 + <li><strong>Ignoring custom code.</strong> Custom scripts and extensions often create the real upgrade complexity.</li>
125 + <li><strong>Skipping backup validation.</strong> A backup is useful only if restore expectations are understood.</li>
126 + <li><strong>Keeping no upgrade notes.</strong> Without notes, the next maintenance cycle starts again from uncertainty.</li>
127 + </ul>
128 +
129 + <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
130 +
248 248   <p>
249 - Extensions and custom code often create the real upgrade complexity.
132 + For many organizations, a practical rhythm is to stay aligned with the current Long Term Support version
133 + and plan upgrades regularly rather than waiting for a major problem. Some environments can upgrade more
134 + frequently, while heavily customized instances may require more planning.
250 250   </p>
251 - </article>
252 252  
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 258   <p>
259 - Login, permissions, restricted spaces and admin features should also be validated.
138 + The important part is not only the exact frequency. It is having an upgrade process that is repeatable:
139 + review, staging validation, production rollout, documentation and follow-up.
260 260   </p>
261 - </article>
262 262  
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>
142 + <div class="resource-cta">
143 + <h3>Need help planning an XWiki upgrade?</h3>
144 + <p>
145 + If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
146 + the current version, extensions, infrastructure and validation needs before planning the production upgrade.
147 + </p>
148 + <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
267 267   </div>
268 - <p>
269 - Without notes, every future upgrade starts again from uncertainty.
270 - </p>
150 +
271 271   </article>
272 - </div>
273 - </div>
274 - </section>
275 275  
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>
153 + <aside class="resource-sidebar" aria-label="Page summary">
154 + <h4>In this guide</h4>
155 + <ul>
156 + <li><a href="#why-it-matters">Why upgrades matter</a></li>
157 + <li><a href="#upgrade-checklist">Upgrade checklist</a></li>
158 + <li><a href="#safe-process">Safe process</a></li>
159 + <li><a href="#common-mistakes">Common mistakes</a></li>
160 + <li><a href="#upgrade-rhythm">Upgrade rhythm</a></li>
161 + </ul>
162 + </aside>
281 281  
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>
286 -
287 - <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View XWiki upgrade services</a>
288 288   </div>
289 289   </div>
290 290   </section>
291 -
292 292  {{/html}}
293 293  {{/velocity}}