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.2
edited by Agnease
on 2026/05/01 11:42
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,293 +1,121 @@
1 -{{velocity}}
2 -#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 -{{html clean="false"}}
1 += Why Upgrade Your XWiki Instance to the Latest LTS Version? =
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
11 - </div>
3 +Your XWiki instance may be working well today, but if it is running an older version, it may already be missing important security fixes, stability improvements, compatibility updates, and platform enhancements.
12 12  
13 - <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
5 +Keeping XWiki aligned with the latest Long Term Support (LTS) version is not only a maintenance task. It is a practical way to reduce operational risk and keep your knowledge platform secure, reliable, and ready for future needs.
14 14  
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>
7 +{{toc start=2 /}}
19 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>
9 +== Why regular XWiki upgrades matter ==
24 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 - </div>
30 - </section>
11 +XWiki is actively maintained. With each release cycle, the platform receives bug fixes, security fixes, usability improvements, performance enhancements, and compatibility updates.
31 31  
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>
13 +When an instance remains on an older version for too long, the upgrade gap becomes larger. This can make future upgrades more complex, increase the risk of incompatibilities, and leave the platform exposed to issues that have already been fixed in newer versions.
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>
15 +A regular upgrade strategy helps keep your platform predictable and easier to maintain.
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 - <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>
17 +== Security should be a priority ==
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 - <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>
19 +Older XWiki versions may be affected by security vulnerabilities that have already been corrected in later releases.
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>
21 +Once security advisories and fixes become public, attackers can analyze the disclosed information and use it to target systems that are still running vulnerable versions.
91 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>
23 +This means that delaying upgrades can increase the window of exposure.
96 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>
25 +Upgrading to the latest LTS version helps reduce this risk by applying the latest available fixes in a stable, production-oriented release line.
101 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>
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>
27 +== Stability and compatibility improvements ==
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>
29 +Security is not the only reason to upgrade.
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>
31 +Newer XWiki LTS versions also include important improvements related to:
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>
33 +* platform stability
34 +* extension compatibility
35 +* authentication and integration support
36 +* user interface improvements
37 +* performance and reliability
38 +* bug fixes accumulated across multiple releases
39 +* better support for modern Java and application server environments
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>
41 +These improvements are especially important for organizations that rely on XWiki as a central knowledge base, intranet, documentation portal, or business process platform.
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>
43 +== Major platform transitions require planning ==
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>
45 +Some upgrades are more significant than others.
184 184  
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>
47 +For example, the move from XWiki 16.x to XWiki 17.x introduced an important platform change: the migration to Jakarta EE. This also affects the application server layer, requiring environments such as Tomcat 10+ instead of Tomcat 9.
189 189  
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>
49 +This type of upgrade should not be treated as a simple file replacement. It requires careful planning, compatibility checks, and proper validation.
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>
51 +== A safe upgrade process ==
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>
53 +At Agnease, XWiki upgrades are approached as controlled technical operations.
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>
55 +A typical upgrade process may include:
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 - <p>
239 - Production should not be the first place where compatibility issues are discovered.
240 - </p>
241 - </article>
57 +* reviewing the current XWiki version and infrastructure
58 +* identifying the recommended target LTS version
59 +* checking installed extensions and custom developments
60 +* reviewing authentication and integration dependencies
61 +* preparing a staging environment when needed
62 +* testing the upgrade before production
63 +* planning downtime and rollback options
64 +* executing the production upgrade
65 +* performing post-upgrade checks
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>
248 - <p>
249 - Extensions and custom code often create the real upgrade complexity.
250 - </p>
251 - </article>
67 +The goal is to minimize risk while keeping the platform secure, stable, and maintainable.
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 - <p>
259 - Login, permissions, restricted spaces and admin features should also be validated.
260 - </p>
261 - </article>
69 +== What happens if upgrades are postponed? ==
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>
267 - </div>
268 - <p>
269 - Without notes, every future upgrade starts again from uncertainty.
270 - </p>
271 - </article>
272 - </div>
273 - </div>
274 - </section>
71 +Postponing upgrades for too long can lead to:
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>
73 +* increased exposure to known vulnerabilities
74 +* more difficult future upgrades
75 +* outdated dependencies
76 +* compatibility problems with newer integrations
77 +* unsupported or harder-to-maintain infrastructure
78 +* higher troubleshooting costs
79 +* increased risk during emergency upgrades
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>
81 +Regular upgrades are usually easier, safer, and more cost-effective than large delayed migrations.
286 286  
287 - <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View XWiki upgrade services</a>
288 - </div>
289 - </div>
290 - </section>
83 +== Who should consider an upgrade? ==
291 291  
85 +You should consider planning an upgrade if:
86 +
87 +* your XWiki instance is not running the latest LTS version
88 +* your current version is more than one year old
89 +* your instance contains sensitive or business-critical information
90 +* you use custom extensions or integrations
91 +* authentication is connected to LDAP, Active Directory, SSO, OpenID Connect, or SAML
92 +* your platform is used as an intranet, knowledge base, documentation portal, or workflow system
93 +* you want to reduce long-term maintenance risks
94 +
95 +== Request an XWiki upgrade assessment ==
96 +
97 +If you are unsure where your XWiki instance stands, Agnease can help with a concise upgrade assessment.
98 +
99 +The assessment can include:
100 +
101 +* current version review
102 +* recommended target version
103 +* estimated upgrade effort
104 +* key security and stability reasons to upgrade
105 +* infrastructure considerations
106 +* extension and customization risks
107 +* recommended next steps
108 +
109 +Contact Agnease to review your current XWiki setup and plan a safe upgrade to the latest LTS version.
110 +
111 +{{html}}
112 +<p>
113 + <a class="btn btn-primary" href="/xwiki/bin/view/Contact/">Request an upgrade assessment</a>
114 +</p>
292 292  {{/html}}
293 -{{/velocity}}
116 +
117 +== About Agnease ==
118 +
119 +Agnease provides professional XWiki services for organizations that rely on XWiki as a secure and long-term knowledge management platform.
120 +
121 +Services include XWiki upgrades, maintenance, troubleshooting, custom development, integrations, security-aware consulting, and long-term platform support.