Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 1.13
edited by Agnease
on 2026/05/19 03:17
Change comment: There is no comment for this version
To version 1.1
edited by Agnease
on 2026/05/01 11:42
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,167 +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 - <section class="resource-header" aria-labelledby="hero-title">
6 - <div class="container">
7 - <div class="text-center">
8 - <div class="hero-kicker">
9 - <i class="fa fa-refresh" aria-hidden="true"></i>
10 - XWiki upgrade guidance
11 - </div>
12 - </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.
13 13  
14 - <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.
15 15  
16 - <p class="resource-summary">
17 - A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
18 - when upgrades are postponed for too long.
19 - </p>
20 - </div>
21 - </section>
7 +{{toc/}}
22 22  
23 - <section class="resource-page">
24 - <div class="container">
25 - <div class="resource-layout">
9 +== Why regular XWiki upgrades matter ==
26 26  
27 - <aside class="resource-sidebar" aria-label="Page summary">
28 - <h4>In this guide</h4>
29 - <ul>
30 - <li><a href="#why-it-matters">Why upgrades matter</a></li>
31 - <li><a href="#upgrade-checklist">Upgrade checklist</a></li>
32 - <li><a href="#safe-process">Safe process</a></li>
33 - <li><a href="#common-mistakes">Common mistakes</a></li>
34 - <li><a href="#upgrade-rhythm">Upgrade rhythm</a></li>
35 - </ul>
36 - </aside>
11 +XWiki is actively maintained. With each release cycle, the platform receives bug fixes, security fixes, usability improvements, performance enhancements, and compatibility updates.
37 37  
38 - <article class="resource-content">
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.
39 39  
40 - <p>
41 - Many XWiki instances continue to run for years with only small visible problems. This can create the
42 - impression that upgrades are optional, especially when users can still log in, search, edit pages and
43 - access the content they need.
44 - </p>
15 +A regular upgrade strategy helps keep your platform predictable and easier to maintain.
45 45  
46 - <p>
47 - The real risk is that technical debt accumulates quietly. Security fixes, extension compatibility,
48 - authentication behavior, infrastructure requirements and custom code assumptions continue to evolve.
49 - The longer an instance remains behind, the more difficult the next upgrade becomes.
50 - </p>
17 +== Security should be a priority ==
51 51  
52 - <div class="resource-note">
53 - <p>
54 - <strong>The main point:</strong> regular upgrades are not only about new features. They reduce security
55 - exposure, compatibility risk and long-term maintenance cost.
56 - </p>
57 - </div>
19 +Older XWiki versions may be affected by security vulnerabilities that have already been corrected in later releases.
58 58  
59 - <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
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.
60 60  
61 - <h3>1. Security fixes accumulate over time</h3>
62 - <p>
63 - Older versions may miss security-related fixes already available in newer releases. Once security issues
64 - become publicly known, running an old version can become a more predictable risk.
65 - </p>
23 +This means that delaying upgrades can increase the window of exposure.
66 66  
67 - <p>
68 - This does not mean every old instance is immediately exposed in the same way. The real impact depends on
69 - your configuration, installed extensions, access model, authentication setup and whether the instance is
70 - public or private. But staying close to supported versions makes security maintenance more manageable.
71 - </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.
72 72  
73 - <h3>2. Large upgrade gaps are harder to control</h3>
74 - <p>
75 - A small, regular upgrade is usually easier to validate than a large jump after several years. Large gaps
76 - mean more release notes, more compatibility changes, more extension checks and more uncertainty around
77 - custom code.
78 - </p>
27 +== Stability and compatibility improvements ==
79 79  
80 - <h3>3. Extensions and customizations can become fragile</h3>
81 - <p>
82 - XWiki instances often include installed extensions, custom Velocity scripts, macros, templates, sheets,
83 - UI extensions, Java components or business-specific applications. These elements need to be reviewed when
84 - planning an upgrade.
85 - </p>
29 +Security is not the only reason to upgrade.
86 86  
87 - <h3>4. Infrastructure requirements evolve</h3>
88 - <p>
89 - XWiki upgrades can involve more than the application itself. Java, Tomcat, the database, Docker images,
90 - reverse proxy configuration, PDF export services and authentication integrations may also need attention.
91 - </p>
31 +Newer XWiki LTS versions also include important improvements related to:
92 92  
93 - <h3>5. Business-critical features need validation</h3>
94 - <p>
95 - A successful upgrade is not only one where the server starts. Users usually depend on login, permissions,
96 - search, dashboards, PDF exports, workflows, notifications, custom applications and important pages. These
97 - should be part of the validation plan.
98 - </p>
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
99 99  
100 - <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
41 +These improvements are especially important for organizations that rely on XWiki as a central knowledge base, intranet, documentation portal, or business process platform.
101 101  
102 - <ul class="resource-checklist">
103 - <li>Identify the current XWiki version and the target version.</li>
104 - <li>Check whether intermediate upgrade steps are needed.</li>
105 - <li>List installed extensions and verify compatibility with the target version.</li>
106 - <li>Identify custom code: Velocity scripts, macros, sheets, templates, UI extensions and Java components.</li>
107 - <li>Review authentication: LDAP, Active Directory, SSO, OIDC, SAML or MFA.</li>
108 - <li>Prepare a staging environment or temporary clone of production.</li>
109 - <li>Validate backups and clarify rollback expectations.</li>
110 - <li>Test important pages, dashboards, permissions, search, jobs, exports and custom workflows.</li>
111 - <li>Document the steps, issues found and follow-up recommendations.</li>
112 - </ul>
43 +== Major platform transitions require planning ==
113 113  
114 - <h2 id="safe-process">A safer upgrade process</h2>
45 +Some upgrades are more significant than others.
115 115  
116 - <p>
117 - Production should not be the first place where the upgrade is tested. The safest approach is to rehearse
118 - the upgrade on staging or a temporary clone, resolve compatibility issues there, then perform the production
119 - upgrade with a clear plan.
120 - </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.
121 121  
122 - <ol>
123 - <li><strong>Prepare a clone:</strong> copy the relevant database, filesystem and configuration.</li>
124 - <li><strong>Run the upgrade outside production:</strong> record the steps and issues found.</li>
125 - <li><strong>Validate critical features:</strong> login, rights, search, PDFs, workflows, dashboards and integrations.</li>
126 - <li><strong>Plan the production window:</strong> backups, downtime, rollback and communication.</li>
127 - <li><strong>Document the result:</strong> keep notes for the next upgrade cycle.</li>
128 - </ol>
49 +This type of upgrade should not be treated as a simple file replacement. It requires careful planning, compatibility checks, and proper validation.
129 129  
130 - <h2 id="common-mistakes">Common mistakes to avoid</h2>
51 +== A safe upgrade process ==
131 131  
132 - <ul>
133 - <li><strong>Upgrading directly in production.</strong> Compatibility issues should be discovered before users are affected.</li>
134 - <li><strong>Checking only public pages.</strong> Authentication, restricted spaces and admin features also need validation.</li>
135 - <li><strong>Ignoring custom code.</strong> Custom scripts and extensions often create the real upgrade complexity.</li>
136 - <li><strong>Skipping backup validation.</strong> A backup is useful only if restore expectations are understood.</li>
137 - <li><strong>Keeping no upgrade notes.</strong> Without notes, the next maintenance cycle starts again from uncertainty.</li>
138 - </ul>
53 +At Agnease, XWiki upgrades are approached as controlled technical operations.
139 139  
140 - <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
55 +A typical upgrade process may include:
141 141  
142 - <p>
143 - For many organizations, a practical rhythm is to stay aligned with the current Long Term Support version
144 - and plan upgrades regularly rather than waiting for a major problem. Some environments can upgrade more
145 - frequently, while heavily customized instances may require more planning.
146 - </p>
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
147 147  
148 - <p>
149 - The important part is not only the exact frequency. It is having an upgrade process that is repeatable:
150 - review, staging validation, production rollout, documentation and follow-up.
151 - </p>
67 +The goal is to minimize risk while keeping the platform secure, stable, and maintainable.
152 152  
153 - <div class="resource-cta">
154 - <h3>Need help planning an XWiki upgrade?</h3>
155 - <p>
156 - If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
157 - the current version, extensions, infrastructure and validation needs before planning the production upgrade.
158 - </p>
159 - <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
160 - </div>
69 +== What happens if upgrades are postponed? ==
161 161  
162 - </article>
163 - </div>
164 - </div>
165 - </section>
71 +Postponing upgrades for too long can lead to:
72 +
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
80 +
81 +Regular upgrades are usually easier, safer, and more cost-effective than large delayed migrations.
82 +
83 +== Who should consider an upgrade? ==
84 +
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>
166 166  {{/html}}
167 -{{/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.