Skip to Content

Changes for page xwiki-upgrades

Last modified by Alex Cotiugă on 2026/05/12 12:41
From version 2.4
edited by Alex Cotiugă
on 2026/05/12 12:40
Change comment: There is no comment for this version
To version 1.2
edited by Alex Cotiugă
on 2026/05/01 12:16
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,294 +1,398 @@
1 1  {{velocity}}
2 -#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 -{{html clean="false"}}
2 + #set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 + {{html clean="false"}}
4 4  
5 - ## PAGE HEADER
6 - <section class="hero hero-centered service-hero" aria-labelledby="hero-title">
5 + ## HERO
6 + <section class="hero hero-centered" aria-labelledby="hero-title">
7 7   <div class="container hero-inner">
8 - <div class="hero-kicker">
9 - <i class="fa fa-refresh" aria-hidden="true"></i>
10 - XWiki upgrade services
11 - </div>
8 + <h1 id="hero-title">XWiki Upgrades</h1>
9 + <p class="lead">Safe, planned upgrades for production XWiki platforms.</p>
12 12  
13 - <h1 id="hero-title">Safe XWiki LTS upgrades for production environments</h1>
11 + <ul class="benefits">
12 + <li>Latest LTS versions</li>
13 + <li>Security fixes</li>
14 + <li>Extension checks</li>
15 + <li>Minimal downtime</li>
16 + <li>Rollback planning</li>
17 + </ul>
14 14  
19 + <div class="hero-cta">
20 + <a href="mailto:alex@agnease.com?subject=XWiki%20Upgrade%20Assessment">Request an upgrade assessment</a>
21 + </div>
22 + </div>
23 + </section>
24 +
25 + ## INTRO
26 + <section aria-labelledby="intro-title">
27 + <div class="container">
28 + <h2 id="intro-title">Upgrade XWiki with confidence</h2>
15 15   <p class="lead">
16 - Keep your XWiki instance secure, stable and compatible with a planned upgrade path, clear validation steps
17 - and reduced operational risk.
30 + Agnease helps organizations upgrade XWiki instances with a focus on security, stability,
31 + compatibility, and predictable execution.
18 18   </p>
19 19  
20 - <p class="hero-support">
21 - We help organizations upgrade XWiki instances that include custom extensions, authentication integrations,
22 - business-critical pages, workflows, scripts, rights configurations and production constraints.
34 + <p>
35 + Whether your instance is one version behind or several years outdated, an XWiki upgrade should be treated
36 + as a controlled technical operation, not a simple version change. The upgrade may affect installed
37 + extensions, custom developments, authentication, PDF export, database behavior, scripts, and the
38 + application server environment.
23 23   </p>
24 24  
25 - <div class="hero-actions">
26 - <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
27 - <a class="btn btn-secondary" href="#upgrade-process">See the upgrade approach</a>
28 - </div>
41 + <p>
42 + The goal is to keep your platform secure, stable, maintainable, and ready for future improvements
43 + while reducing the risk of unexpected downtime or failed production upgrades.
44 + </p>
29 29   </div>
30 30   </section>
31 31  
32 - ## WHY UPGRADES MATTER
48 + ## WHY UPGRADE
49 + #set ($whyUpgradeData = [{
50 + 'title': 'Security fixes',
51 + 'icon': 'shield',
52 + 'content': 'Older versions may miss important fixes that were introduced in later XWiki releases.'
53 + },{
54 + 'title': 'Stability improvements',
55 + 'icon': 'check-square-o',
56 + 'content': 'Regular upgrades reduce accumulated bugs and keep the platform easier to maintain.'
57 + },{
58 + 'title': 'Compatibility',
59 + 'icon': 'plug',
60 + 'content': 'Modern integrations, authentication systems, Java versions, databases, and application servers require careful compatibility planning.'
61 + },{
62 + 'title': 'Lower future risk',
63 + 'icon': 'line-chart',
64 + 'content': 'Frequent smaller upgrades are usually safer and more predictable than large delayed migrations.'
65 + }])
66 +
33 33   <section aria-labelledby="why-upgrade-title">
34 34   <div class="container">
35 - <h2 id="why-upgrade-title">Why regular XWiki upgrades matter</h2>
69 + <h2 id="why-upgrade-title">Why XWiki upgrades matter</h2>
70 + <p class="lead">Regular upgrades help keep your XWiki platform secure, reliable, and easier to evolve.</p>
36 36  
37 - <p class="section-intro">
38 - An outdated XWiki instance can become harder to maintain over time. Security fixes, browser compatibility,
39 - extension updates, platform changes and infrastructure requirements continue to evolve, while older versions
40 - become more difficult and risky to upgrade.
41 - </p>
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>Reduce security exposure</h3>
49 - <p>
50 - Staying close to supported XWiki versions helps reduce exposure to known vulnerabilities and missing fixes.
51 - </p>
52 - <ul>
53 - <li>Review current version exposure</li>
54 - <li>Plan upgrade to a supported version</li>
55 - <li>Validate security-sensitive features</li>
56 - </ul>
57 - </article>
58 -
59 - <article class="pathway-card">
60 - <div class="pathway-icon">
61 - <i class="fa fa-cogs" aria-hidden="true"></i>
62 - </div>
63 - <h3>Preserve compatibility</h3>
64 - <p>
65 - Extensions, custom applications, authentication systems and infrastructure components need to remain compatible.
66 - </p>
67 - <ul>
68 - <li>Check installed extensions</li>
69 - <li>Review custom code and scripts</li>
70 - <li>Validate integrations after upgrade</li>
71 - </ul>
72 - </article>
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>Improve maintainability</h3>
79 - <p>
80 - Smaller, regular upgrades are usually easier to control than large jumps after years of accumulated changes.
81 - </p>
82 - <ul>
83 - <li>Avoid long upgrade gaps</li>
84 - <li>Document the current platform state</li>
85 - <li>Prepare future upgrade cycles</li>
86 - </ul>
87 - </article>
72 + <div class="widgets">
73 + #foreach ($entry in $whyUpgradeData)
74 + <article class="widget">
75 + <div class="icon" aria-hidden="true">
76 + <i class="fa fa-$entry.icon"></i>
77 + <h4>$entry.title</h4>
78 + </div>
79 + <p>$entry.content</p>
80 + </article>
81 + #end
88 88   </div>
89 89   </div>
90 90   </section>
91 91  
92 - ## COMMON SITUATIONS
93 - <section class="services" aria-labelledby="situations-title">
94 - <div class="container">
95 - <h2 id="situations-title">Common situations we handle</h2>
86 + ## WHEN TO UPGRADE
87 + #set ($whenToUpgradeData = [{
88 + 'title': 'Your XWiki version is old',
89 + 'icon': 'clock-o',
90 + 'content': 'If your current version is more than one year old, the upgrade gap may already be significant.'
91 + },{
92 + 'title': 'You are not on the latest LTS',
93 + 'icon': 'refresh',
94 + 'content': 'Production instances should normally stay close to the latest suitable Long Term Support version.'
95 + },{
96 + 'title': 'You use custom extensions',
97 + 'icon': 'cogs',
98 + 'content': 'Custom applications, scripts, macros, UI extensions, or Java components should be reviewed before upgrading.'
99 + },{
100 + 'title': 'Authentication is critical',
101 + 'icon': 'key',
102 + 'content': 'LDAP, Active Directory, OpenID Connect, SAML, or MFA integrations need careful validation during upgrades.'
103 + },{
104 + 'title': 'Your wiki supports business processes',
105 + 'icon': 'sitemap',
106 + 'content': 'Instances used for intranets, procedures, documentation, approvals, or workflows deserve controlled upgrade planning.'
107 + },{
108 + 'title': 'You are preparing infrastructure changes',
109 + 'icon': 'server',
110 + 'content': 'Java, Tomcat, Docker, database, or operating system changes can make upgrade planning more important.'
111 + }])
96 96  
97 - <p class="section-intro">
98 - XWiki upgrades are often simple in clean environments, but production instances usually include additional
99 - constraints that need to be understood before touching the live system.
113 + <section class="services" aria-labelledby="when-title">
114 + <div class="container">
115 + <h2 id="when-title">When should you consider an upgrade?</h2>
116 + <p class="lead">
117 + An upgrade is recommended when your XWiki instance is becoming outdated, exposed, or harder to maintain.
100 100   </p>
101 101  
102 102   <div class="services-grid">
103 - <article class="service">
104 - <div class="service-icon" aria-hidden="true">
105 - <i class="fa fa-clock-o"></i>
106 - </div>
107 - <div class="service-body">
108 - <h4>Old XWiki versions</h4>
109 - <p>
110 - Instances that have not been upgraded for several months or years and require a careful upgrade path.
111 - </p>
112 - </div>
113 - </article>
121 + #foreach ($entry in $whenToUpgradeData)
122 + <article class="service">
123 + <div class="service-icon">
124 + <i class="fa fa-$entry.icon" aria-hidden="true"></i>
125 + </div>
126 + <div class="service-body">
127 + <h4>$entry.title</h4>
128 + <p>$entry.content</p>
129 + </div>
130 + </article>
131 + #end
132 + </div>
133 + </div>
134 + </section>
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>Custom extensions and scripts</h4>
121 - <p>
122 - Wikis with custom applications, Velocity scripts, macros, UI extensions, rights logic or business workflows.
123 - </p>
124 - </div>
125 - </article>
136 + ## WHAT AGNEASE HANDLES
137 + #set ($upgradeScopeData = [{
138 + 'title': 'Assessment & planning',
139 + 'icon': 'search',
140 + 'content': 'Review the current version, environment, extensions, customizations, and target upgrade path.',
141 + 'items': [
142 + 'Current version and environment review',
143 + 'Recommended target version',
144 + 'Release notes and compatibility analysis'
145 + ]
146 + },{
147 + 'title': 'Extension & customization review',
148 + 'icon': 'puzzle-piece',
149 + 'content': 'Identify risks related to installed extensions, custom code, scripts, templates, and integrations.',
150 + 'items': [
151 + 'Installed extension review',
152 + 'Custom code impact analysis',
153 + 'Authentication and integration checks'
154 + ]
155 + },{
156 + 'title': 'Staging upgrade',
157 + 'icon': 'flask',
158 + 'content': 'Test the upgrade before production when a staging environment is available.',
159 + 'items': [
160 + 'Backup and restore validation',
161 + 'Upgrade execution in test environment',
162 + 'Troubleshooting and issue fixing'
163 + ]
164 + },{
165 + 'title': 'Production rollout',
166 + 'icon': 'rocket',
167 + 'content': 'Execute or guide the production upgrade with a clear plan and validation steps.',
168 + 'items': [
169 + 'Downtime and rollback planning',
170 + 'Production upgrade execution',
171 + 'Post-upgrade verification'
172 + ]
173 + }])
126 126  
127 - <article class="service">
128 - <div class="service-icon" aria-hidden="true">
129 - <i class="fa fa-lock"></i>
130 - </div>
131 - <div class="service-body">
132 - <h4>Authentication integrations</h4>
133 - <p>
134 - LDAP, Active Directory, SSO, OIDC, SAML, MFA or custom login setups that must keep working after upgrade.
135 - </p>
136 - </div>
137 - </article>
175 + <section class="services" aria-labelledby="scope-title">
176 + <div class="container">
177 + <h2 id="scope-title">What Agnease handles</h2>
178 + <p class="lead">
179 + Upgrade support can cover the full process, from assessment to production rollout.
180 + </p>
138 138  
139 - <article class="service">
140 - <div class="service-icon" aria-hidden="true">
141 - <i class="fa fa-server"></i>
142 - </div>
143 - <div class="service-body">
144 - <h4>Infrastructure changes</h4>
145 - <p>
146 - Java, Tomcat, database, Docker, filesystem, reverse proxy or hosting changes required by newer versions.
147 - </p>
148 - </div>
149 - </article>
150 -
151 - <article class="service">
152 - <div class="service-icon" aria-hidden="true">
153 - <i class="fa fa-file-pdf-o"></i>
154 - </div>
155 - <div class="service-body">
156 - <h4>Business-critical features</h4>
157 - <p>
158 - PDF exports, dashboards, structured data, templates, permissions, notifications and workflows that need validation.
159 - </p>
160 - </div>
161 - </article>
162 -
163 - <article class="service">
164 - <div class="service-icon" aria-hidden="true">
165 - <i class="fa fa-warning"></i>
166 - </div>
167 - <div class="service-body">
168 - <h4>Low-downtime rollout</h4>
169 - <p>
170 - Upgrade planning with backups, testing, rollback options and a controlled production deployment window.
171 - </p>
172 - </div>
173 - </article>
182 + <div class="services-grid">
183 + #foreach ($entry in $upgradeScopeData)
184 + <article class="service">
185 + <div class="service-icon">
186 + <i class="fa fa-$entry.icon" aria-hidden="true"></i>
187 + </div>
188 + <div class="service-body">
189 + <h4>$entry.title</h4>
190 + <p>$entry.content</p>
191 + <ul>
192 + #foreach ($item in $entry.items)
193 + <li>$item</li>
194 + #end
195 + </ul>
196 + </div>
197 + </article>
198 + #end
174 174   </div>
175 175   </div>
176 176   </section>
177 177  
178 178   ## PROCESS
179 - <section id="upgrade-process" class="split-section" aria-labelledby="process-title">
204 + #set ($processData = [{
205 + 'title': '1. Initial review',
206 + 'icon': 'info-circle',
207 + 'content': 'We review your current XWiki version, hosting environment, installed extensions, customizations, authentication setup, and known issues.'
208 + },{
209 + 'title': '2. Upgrade path',
210 + 'icon': 'map-signs',
211 + 'content': 'We identify the recommended target version and whether the upgrade should be direct, staged, or combined with infrastructure changes.'
212 + },{
213 + 'title': '3. Compatibility checks',
214 + 'icon': 'check',
215 + 'content': 'We review release notes, extensions, custom developments, authentication integrations, PDF export, and other sensitive areas.'
216 + },{
217 + 'title': '4. Backup and rollback plan',
218 + 'icon': 'database',
219 + 'content': 'Before production work, the database, permanent directory, application files, and configuration backup strategy should be clear.'
220 + },{
221 + 'title': '5. Staging validation',
222 + 'icon': 'desktop',
223 + 'content': 'Whenever possible, the upgrade is tested in a staging environment to validate key pages, extensions, permissions, and workflows.'
224 + },{
225 + 'title': '6. Production upgrade',
226 + 'icon': 'upload',
227 + 'content': 'The production upgrade is executed according to the agreed plan, with attention to downtime, rollback options, and validation.'
228 + }])
229 +
230 + <section class="services" aria-labelledby="process-title">
180 180   <div class="container">
181 - <div class="split-grid">
182 - <div class="split-copy">
183 - <h2 id="process-title">A practical upgrade approach</h2>
232 + <h2 id="process-title">A structured upgrade process</h2>
233 + <p class="lead">
234 + The process is designed to reduce surprises and keep the platform operational.
235 + </p>
184 184  
185 - <p>
186 - The goal is not only to install a newer version. The goal is to move your XWiki instance forward
187 - while protecting the data, configuration, customizations and business processes that already depend on it.
188 - </p>
237 + <div class="services-grid">
238 + #foreach ($entry in $processData)
239 + <article class="service">
240 + <div class="service-icon">
241 + <i class="fa fa-$entry.icon" aria-hidden="true"></i>
242 + </div>
243 + <div class="service-body">
244 + <h4>$entry.title</h4>
245 + <p>$entry.content</p>
246 + </div>
247 + </article>
248 + #end
249 + </div>
250 + </div>
251 + </section>
189 189  
190 - <p>
191 - The upgrade is always prepared outside production first, using a staging environment or a temporary clone
192 - of the live instance. This allows compatibility issues, extension problems, authentication changes and
193 - custom features to be validated before the controlled production rollout.
194 - </p>
195 - </div>
253 + ## COMMON SCENARIOS
254 + #set ($scenariosData = [{
255 + 'title': 'Regular LTS upgrade',
256 + 'icon': 'calendar-check-o',
257 + 'content': 'For organizations that upgrade regularly and want to stay aligned with the latest stable XWiki release line.'
258 + },{
259 + 'title': 'Delayed upgrade',
260 + 'icon': 'exclamation-triangle',
261 + 'content': 'For instances that have not been upgraded for one or more years and need a more careful compatibility review.'
262 + },{
263 + 'title': 'Major platform transition',
264 + 'icon': 'random',
265 + 'content': 'For upgrades that also involve Java, Tomcat, Docker, database, or operating system changes.'
266 + },{
267 + 'title': 'Custom application upgrade',
268 + 'icon': 'code',
269 + 'content': 'For XWiki instances with custom workflows, scripts, macros, PDF templates, or Java extensions.'
270 + },{
271 + 'title': 'Authentication-sensitive upgrade',
272 + 'icon': 'lock',
273 + 'content': 'For platforms using LDAP, Active Directory, OpenID Connect, SAML, MFA, or other authentication integrations.'
274 + },{
275 + 'title': 'Failed upgrade recovery',
276 + 'icon': 'ambulance',
277 + 'content': 'For organizations that already attempted an upgrade and encountered startup errors, broken extensions, or rendering issues.'
278 + }])
196 196  
197 - <ol class="process-list">
198 - <li>
199 - <strong>Review the current instance</strong>
200 - Version, extensions, database, filesystem, authentication, custom code, logs and infrastructure constraints.
201 - </li>
202 - <li>
203 - <strong>Define the upgrade path</strong>
204 - Target version, intermediate steps if needed, compatibility risks, expected downtime and rollback options.
205 - </li>
206 - <li>
207 - <strong>Prepare and validate</strong>
208 - Backups, test upgrade when needed, extension checks and validation of critical XWiki features.
209 - </li>
210 - <li>
211 - <strong>Upgrade production</strong>
212 - Controlled execution, post-upgrade checks, issue resolution and confirmation that key features still work.
213 - </li>
214 - <li>
215 - <strong>Document next steps</strong>
216 - Upgrade notes, observed risks, remaining recommendations and future maintenance guidance.
217 - </li>
218 - </ol>
280 + <section class="services" aria-labelledby="scenarios-title">
281 + <div class="container">
282 + <h2 id="scenarios-title">Common upgrade scenarios</h2>
283 + <p class="lead">
284 + Agnease can help with both routine upgrades and complex migration situations.
285 + </p>
286 +
287 + <div class="services-grid">
288 + #foreach ($entry in $scenariosData)
289 + <article class="service">
290 + <div class="service-icon">
291 + <i class="fa fa-$entry.icon" aria-hidden="true"></i>
292 + </div>
293 + <div class="service-body">
294 + <h4>$entry.title</h4>
295 + <p>$entry.content</p>
296 + </div>
297 + </article>
298 + #end
219 219   </div>
220 220   </div>
221 221   </section>
222 222  
223 - ## DELIVERABLES
224 - <section aria-labelledby="deliverables-title">
303 + ## PLATFORM NOTE
304 + <section aria-labelledby="platform-title">
225 225   <div class="container">
226 - <h2 id="deliverables-title">What you can expect</h2>
227 -
228 - <p class="section-intro">
229 - The exact scope depends on your XWiki version, hosting setup and customizations, but an upgrade engagement
230 - usually includes a clear technical review, a controlled upgrade plan and post-upgrade validation.
306 + <h2 id="platform-title">Major version upgrades require planning</h2>
307 + <p class="lead">
308 + Some XWiki upgrades also require infrastructure-level preparation.
231 231   </p>
232 232  
233 233   <div class="widgets">
234 234   <article class="widget">
235 235   <div class="icon" aria-hidden="true">
236 - <i class="fa fa-search"></i>
237 - <h4>Upgrade review</h4>
314 + <i class="fa fa-server"></i>
315 + <h4>Application server compatibility</h4>
238 238   </div>
239 239   <p>
240 - Review of the current version, installed extensions, customizations, authentication and hosting constraints.
318 + Major XWiki versions may introduce changes that affect Java, Tomcat, Docker images,
319 + database drivers, or deployment configuration. These changes should be reviewed before production rollout.
241 241   </p>
242 242   </article>
243 243  
244 244   <article class="widget">
245 245   <div class="icon" aria-hidden="true">
246 - <i class="fa fa-map"></i>
247 - <h4>Upgrade plan</h4>
325 + <i class="fa fa-plug"></i>
326 + <h4>Extension compatibility</h4>
248 248   </div>
249 249   <p>
250 - Recommended target version, risk areas, validation checklist, downtime expectations and rollback approach.
329 + Installed extensions and custom applications should be checked against the target version,
330 + especially when the instance contains business-specific workflows or integrations.
251 251   </p>
252 252   </article>
253 253  
254 254   <article class="widget">
255 255   <div class="icon" aria-hidden="true">
256 - <i class="fa fa-check-circle"></i>
257 - <h4>Post-upgrade validation</h4>
336 + <i class="fa fa-shield"></i>
337 + <h4>Security and stability</h4>
258 258   </div>
259 259   <p>
260 - Verification of key pages, rights, authentication, extensions, jobs, PDFs, dashboards and custom applications.
340 + Staying close to the recommended LTS version helps reduce exposure to known issues and keeps
341 + the platform easier to maintain over time.
261 261   </p>
262 262   </article>
344 + </div>
345 + </div>
346 + </section>
263 263  
348 + ## ASSESSMENT CTA
349 + <section class="cta-section" aria-labelledby="assessment-title">
350 + <div class="container">
351 + <h2 id="assessment-title">Request an XWiki upgrade assessment</h2>
352 + <p class="lead">
353 + Not sure how far your instance is from the recommended version?
354 + </p>
355 +
356 + <p class="text-center">
357 + Send your current XWiki version and a short description of your setup.
358 + Agnease will review the situation and provide a practical upgrade recommendation.
359 + </p>
360 +
361 + <div class="widgets">
264 264   <article class="widget">
265 265   <div class="icon" aria-hidden="true">
266 - <i class="fa fa-file-text-o"></i>
267 - <h4>Upgrade notes</h4>
364 + <i class="fa fa-list"></i>
365 + <h4>The assessment can include</h4>
268 268   </div>
269 269   <p>
270 - Practical documentation of the performed work, important decisions and recommended follow-up actions.
368 + Recommended target version, estimated upgrade effort, security and stability reasons to upgrade,
369 + infrastructure considerations, extension risks, customization risks, and suggested next steps.
271 271   </p>
272 272   </article>
273 273   </div>
373 +
374 + <p class="text-center contact-inline">
375 + <a href="mailto:alex@agnease.com?subject=XWiki%20Upgrade%20Assessment">Request an upgrade assessment</a>
376 + </p>
274 274   </div>
275 275   </section>
276 276  
277 - ## CTA
278 - <section class="cta-section" aria-labelledby="cta-title">
380 + ## RELATED SERVICES
381 + <section aria-labelledby="related-title">
279 279   <div class="container">
280 - <div class="cta-panel">
281 - <h2 id="cta-title">Planning an XWiki upgrade?</h2>
383 + <h2 id="related-title">Related Agnease services</h2>
384 + <p class="lead">
385 + XWiki upgrades are often connected to maintenance, security, development, and integration work.
386 + </p>
282 282  
283 - <p>
284 - Send your current XWiki version, target version if known, hosting setup and any custom extensions or integrations
285 - that may affect the upgrade. A short description is enough to start with.
286 - </p>
287 -
288 - <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
289 - </div>
388 + <ul class="benefits">
389 + <li>Maintenance & support</li>
390 + <li>Security review</li>
391 + <li>Custom development</li>
392 + <li>Integrations</li>
393 + <li>Migrations</li>
394 + </ul>
290 290   </div>
291 291   </section>
292 -
293 293  {{/html}}
294 294  {{/velocity}}