Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 9.1
edited by Agnease
on 2026/05/26 10:39
Change comment: There is no comment for this version
To version 1.5
edited by Agnease
on 2026/05/12 14:48
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,0 @@
1 -Why You Should Upgrade XWiki Regularly for Security and Stability
Content
... ... @@ -1,294 +1,174 @@
1 -{{velocity}}
2 -#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 -{{html clean="false"}}
1 +/* ========== Resource / Article Pages ========== */
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 +.resource-page {
4 + padding-top: 34px;
5 +}
13 13  
14 - <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
7 +.resource-header {
8 + padding: 40px 0 30px;
9 + border-top: none;
10 + background:
11 + radial-gradient(42rem 14rem at 50% 0%, @brand-bg 0%, transparent 70%);
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>
13 + .resource-kicker {
14 + display: inline-flex;
15 + align-items: center;
16 + gap: 8px;
17 + color: @brand;
18 + background: fade(@brand, 8%);
19 + border: 1px solid fade(@brand, 18%);
20 + border-radius: 999px;
21 + padding: 6px 12px;
22 + margin-bottom: 14px;
23 + font-size: 13px;
24 + font-weight: 700;
25 + }
22 22  
23 - <section class="resource-page">
24 - <div class="container">
25 - <div class="resource-layout">
27 + h1 {
28 + max-width: 820px;
29 + margin: 0 auto 14px;
30 + text-align: center;
31 + line-height: 1.18;
32 + }
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 - <li><a href="#upgrade-faq">FAQ</a></li>
36 - </ul>
37 - </aside>
34 + .resource-summary {
35 + max-width: 780px;
36 + margin: 0 auto;
37 + color: @muted;
38 + text-align: center;
39 + font-size: 18px;
40 + line-height: 1.55;
41 + }
42 +}
38 38  
39 - <article class="resource-content">
44 +.resource-layout {
45 + display: grid;
46 + grid-template-columns: minmax(0, 760px) 280px;
47 + gap: 42px;
48 + max-width: 1080px;
49 + margin: 0 auto;
50 + align-items: start;
51 +}
40 40  
41 - <p>
42 - Many XWiki instances continue to run for years with only small visible problems. This can create the
43 - impression that upgrades are optional, especially when users can still log in, search, edit pages and
44 - access the content they need.
45 - </p>
53 +.resource-content {
54 + color: @text;
55 + font-size: 16px;
56 + line-height: 1.68;
46 46  
47 - <p>
48 - The real risk is that technical debt accumulates quietly. Security fixes, extension compatibility,
49 - authentication behavior, infrastructure requirements and custom code assumptions continue to evolve.
50 - The longer an instance remains behind, the more difficult the next upgrade becomes.
51 - </p>
58 + h2 {
59 + text-align: left;
60 + margin: 34px 0 12px;
61 + line-height: 1.28;
62 + }
52 52  
53 - <div class="resource-note">
54 - <p>
55 - <strong>In practice:</strong> an XWiki upgrade should review the current version, target version,
56 - required intermediate steps, installed extensions, custom code, authentication setup, infrastructure,
57 - backups, rollback expectations and the business-critical features that must be validated before
58 - production is touched.
59 - </p>
60 - </div>
64 + h3 {
65 + margin: 24px 0 8px;
66 + line-height: 1.3;
67 + }
61 61  
62 - <p>
63 - An XWiki upgrade is the process of moving an existing instance to a newer XWiki version while preserving
64 - content, configuration, extensions, customizations, access rights and business-critical behavior. A safe
65 - upgrade is not only a software installation task. It is a controlled maintenance process with preparation,
66 - staging validation, production rollout and follow-up notes.
67 - </p>
69 + p {
70 + margin: 0 0 16px;
71 + }
68 68  
69 - <div class="resource-note">
70 - <p>
71 - <strong>The main point:</strong> regular upgrades are not only about new features. They reduce security
72 - exposure, compatibility risk and long-term maintenance cost.
73 - </p>
74 - </div>
73 + ul,
74 + ol {
75 + margin: 0 0 18px;
76 + padding-left: 22px;
77 + }
75 75  
76 - <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
79 + li {
80 + margin: 6px 0;
81 + }
77 77  
78 - <h3>1. Security fixes accumulate over time</h3>
79 - <p>
80 - Older versions may miss security-related fixes already available in newer releases. Once security issues
81 - become publicly known, running an old version can become a more predictable risk.
82 - </p>
83 + strong {
84 + color: @text;
85 + }
86 +}
83 83  
84 - <p>
85 - This does not mean every old instance is immediately exposed in the same way. The real impact depends on
86 - your configuration, installed extensions, access model, authentication setup and whether the instance is
87 - public or private. But staying close to supported versions makes security maintenance more manageable.
88 - </p>
88 +.resource-note {
89 + border-left: 4px solid @brand;
90 + background: @brand-bg;
91 + padding: 16px 18px;
92 + margin: 22px 0;
93 + border-radius: 0 @radius @radius 0;
89 89  
90 - <p>
91 - For a broader view of security-related checks, see
92 - <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>.
93 - </p>
95 + p:last-child {
96 + margin-bottom: 0;
97 + }
98 +}
94 94  
95 - <h3>2. Large upgrade gaps are harder to control</h3>
96 - <p>
97 - A small, regular upgrade is usually easier to validate than a large jump after several years. Large gaps
98 - mean more release notes, more compatibility changes, more extension checks and more uncertainty around
99 - custom code.
100 - </p>
100 +.resource-checklist {
101 + margin: 18px 0 24px;
102 + padding: 0;
103 + list-style: none;
101 101  
102 - <h3>3. Extensions and customizations can become fragile</h3>
103 - <p>
104 - XWiki instances often include installed extensions, custom Velocity scripts, macros, templates, sheets,
105 - UI extensions, Java components or business-specific applications. These elements need to be reviewed when
106 - planning an upgrade.
107 - </p>
105 + li {
106 + position: relative;
107 + padding: 10px 0 10px 34px;
108 + border-bottom: 1px solid @line;
108 108  
109 - <p>
110 - For more details on organizing custom work, see
111 - <a href="$xwiki.getURL('resources.xwiki-custom-development')">how to keep XWiki custom development maintainable across upgrades</a>.
112 - </p>
110 + &:before {
111 + content: "\f00c";
112 + font-family: FontAwesome;
113 + position: absolute;
114 + left: 0;
115 + top: 11px;
116 + color: @brand;
117 + }
118 + }
119 +}
113 113  
114 - <h3>4. Infrastructure requirements evolve</h3>
115 - <p>
116 - XWiki upgrades can involve more than the application itself. Java, Tomcat, the database, Docker images,
117 - reverse proxy configuration, PDF export services and authentication integrations may also need attention.
118 - </p>
121 +.resource-sidebar {
122 + position: sticky;
123 + top: 96px;
124 + border: 1px solid @line;
125 + border-radius: @radius;
126 + padding: 18px;
127 + background: #fff;
128 + box-shadow: @shadow-sm;
119 119  
120 - <h3>5. Business-critical features need validation</h3>
121 - <p>
122 - A successful upgrade is not only one where the server starts. Users usually depend on login, permissions,
123 - search, dashboards, PDF exports, workflows, notifications, custom applications and important pages. These
124 - should be part of the validation plan.
125 - </p>
130 + h4 {
131 + margin: 0 0 10px;
132 + }
126 126  
127 - <h2 id="upgrade-checklist">XWiki upgrade planning checklist</h2>
134 + ul {
135 + margin: 0;
136 + padding-left: 18px;
137 + color: @muted;
138 + }
128 128  
129 - <p>
130 - A practical XWiki upgrade plan should cover both the application and the environment around it.
131 - The following checklist can be used as a starting point before upgrading a production instance.
132 - </p>
140 + li {
141 + margin: 8px 0;
142 + }
133 133  
134 - <ul class="resource-checklist">
135 - <li>Identify the current XWiki version and the target version.</li>
136 - <li>Check whether intermediate upgrade steps are needed.</li>
137 - <li>List installed extensions and verify compatibility with the target version.</li>
138 - <li>Identify custom code: Velocity scripts, macros, sheets, templates, UI extensions and Java components.</li>
139 - <li>Review authentication: LDAP, Active Directory, SSO, OIDC, SAML or MFA.</li>
140 - <li>Prepare a staging environment or temporary clone of production.</li>
141 - <li>Validate backups and clarify rollback expectations.</li>
142 - <li>Test important pages, dashboards, permissions, search, jobs, exports and custom workflows.</li>
143 - <li>Document the steps, issues found and follow-up recommendations.</li>
144 - </ul>
144 + a {
145 + color: @brand;
146 + font-weight: 600;
147 + }
148 +}
145 145  
146 - <h2 id="safe-process">A safer upgrade process</h2>
150 +.resource-cta {
151 + margin-top: 36px;
152 + padding: 22px;
153 + border: 1px solid fade(@brand, 20%);
154 + border-radius: @radius;
155 + background: @brand-bg;
147 147  
148 - <p>
149 - Production should not be the first place where the upgrade is tested. The safest approach is to rehearse
150 - the upgrade on staging or a temporary clone, resolve compatibility issues there, then perform the production
151 - upgrade with a clear plan.
152 - </p>
157 + h3 {
158 + margin-top: 0;
159 + }
153 153  
154 - <ol>
155 - <li><strong>Prepare a clone:</strong> copy the relevant database, filesystem and configuration.</li>
156 - <li><strong>Run the upgrade outside production:</strong> record the steps and issues found.</li>
157 - <li><strong>Validate critical features:</strong> login, rights, search, PDFs, workflows, dashboards and integrations.</li>
158 - <li><strong>Plan the production window:</strong> backups, downtime, rollback and communication.</li>
159 - <li><strong>Document the result:</strong> keep notes for the next upgrade cycle.</li>
160 - </ol>
161 + p {
162 + color: @muted;
163 + }
164 +}
161 161  
162 - <h2 id="common-mistakes">Common mistakes to avoid</h2>
163 -
164 - <ul>
165 - <li><strong>Upgrading directly in production.</strong> Compatibility issues should be discovered before users are affected.</li>
166 - <li><strong>Checking only public pages.</strong> Authentication, restricted spaces and admin features also need validation.</li>
167 - <li><strong>Ignoring custom code.</strong> Custom scripts and extensions often create the real upgrade complexity.</li>
168 - <li><strong>Skipping backup validation.</strong> A backup is useful only if restore expectations are understood.</li>
169 - <li><strong>Keeping no upgrade notes.</strong> Without notes, the next maintenance cycle starts again from uncertainty.</li>
170 - </ul>
171 -
172 - <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
173 -
174 - <p>
175 - For many organizations, a practical rhythm is to stay aligned with the current Long Term Support version
176 - and plan upgrades regularly rather than waiting for a major problem. Some environments can upgrade more
177 - frequently, while heavily customized instances may require more planning.
178 - </p>
179 -
180 - <p>
181 - The important part is not only the exact frequency. It is having an upgrade process that is repeatable:
182 - review, staging validation, production rollout, documentation and follow-up.
183 - </p>
184 -
185 - <h2 id="upgrade-faq">XWiki upgrade FAQ</h2>
186 -
187 - <h3>Why should XWiki be upgraded regularly?</h3>
188 - <p>
189 - XWiki should be upgraded regularly to reduce security exposure, keep extensions compatible, avoid large
190 - upgrade gaps and make long-term maintenance easier. Regular upgrades are easier to plan and validate than
191 - major jumps after several years.
192 - </p>
193 -
194 - <h3>Is a working XWiki instance safe to leave unchanged?</h3>
195 - <p>
196 - Not necessarily. An XWiki instance can continue to work from a user perspective while becoming outdated,
197 - harder to upgrade and exposed to avoidable risks. Visible functionality is not the same as long-term
198 - maintainability.
199 - </p>
200 -
201 - <h3>What should be checked before upgrading XWiki?</h3>
202 - <p>
203 - Before upgrading XWiki, review the current version, target version, intermediate upgrade steps, installed
204 - extensions, custom code, authentication setup, infrastructure, backups, rollback expectations and
205 - business-critical features.
206 - </p>
207 -
208 - <h3>Should an XWiki upgrade be tested outside production?</h3>
209 - <p>
210 - Yes. The safest approach is to rehearse the upgrade on a staging environment or temporary clone, fix
211 - compatibility issues there, then perform the production upgrade with a clear plan and rollback expectations.
212 - </p>
213 -
214 - <h3>What makes an XWiki upgrade difficult?</h3>
215 - <p>
216 - XWiki upgrades become more difficult when the version gap is large, extensions are outdated, custom code is
217 - undocumented, authentication is complex, infrastructure dependencies changed or critical workflows were not
218 - included in the validation plan.
219 - </p>
220 -
221 - <div class="resource-note">
222 - <p>
223 - Related resources:
224 - <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
225 - and
226 - <a href="$xwiki.getURL('resources.xwiki-custom-development')">how to keep XWiki custom development maintainable across upgrades</a>.
227 - </p>
228 - </div>
229 -
230 - <div class="resource-cta">
231 - <h3>Need help planning an XWiki upgrade?</h3>
232 - <p>
233 - If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
234 - the current version, extensions, infrastructure and validation needs before planning the production upgrade.
235 - </p>
236 - <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
237 - </div>
238 -
239 - </article>
240 - </div>
241 - </div>
242 - </section>
243 -
244 - <script type="application/ld+json">
245 - {
246 - "@context": "https://schema.org",
247 - "@type": "FAQPage",
248 - "mainEntity": [
249 - {
250 - "@type": "Question",
251 - "name": "Why should XWiki be upgraded regularly?",
252 - "acceptedAnswer": {
253 - "@type": "Answer",
254 - "text": "XWiki should be upgraded regularly to reduce security exposure, keep extensions compatible, avoid large upgrade gaps and make long-term maintenance easier. Regular upgrades are easier to plan and validate than major jumps after several years."
255 - }
256 - },
257 - {
258 - "@type": "Question",
259 - "name": "Is a working XWiki instance safe to leave unchanged?",
260 - "acceptedAnswer": {
261 - "@type": "Answer",
262 - "text": "Not necessarily. An XWiki instance can continue to work from a user perspective while becoming outdated, harder to upgrade and exposed to avoidable risks. Visible functionality is not the same as long-term maintainability."
263 - }
264 - },
265 - {
266 - "@type": "Question",
267 - "name": "What should be checked before upgrading XWiki?",
268 - "acceptedAnswer": {
269 - "@type": "Answer",
270 - "text": "Before upgrading XWiki, review the current version, target version, intermediate upgrade steps, installed extensions, custom code, authentication setup, infrastructure, backups, rollback expectations and business-critical features."
271 - }
272 - },
273 - {
274 - "@type": "Question",
275 - "name": "Should an XWiki upgrade be tested outside production?",
276 - "acceptedAnswer": {
277 - "@type": "Answer",
278 - "text": "Yes. The safest approach is to rehearse the upgrade on a staging environment or temporary clone, fix compatibility issues there, then perform the production upgrade with a clear plan and rollback expectations."
279 - }
280 - },
281 - {
282 - "@type": "Question",
283 - "name": "What makes an XWiki upgrade difficult?",
284 - "acceptedAnswer": {
285 - "@type": "Answer",
286 - "text": "XWiki upgrades become more difficult when the version gap is large, extensions are outdated, custom code is undocumented, authentication is complex, infrastructure dependencies changed or critical workflows were not included in the validation plan."
287 - }
288 - }
289 - ]
166 +@media (max-width: 900px) {
167 + .resource-layout {
168 + grid-template-columns: 1fr;
290 290   }
291 - </script>
292 292  
293 -{{/html}}
294 -{{/velocity}}
171 + .resource-sidebar {
172 + position: static;
173 + }
174 +}
Agnease.Code.SEODetailsClass[0]
metaDescription
... ... @@ -1,1 +1,0 @@
1 -Learn why regular XWiki upgrades matter for security, stability, extension compatibility and long-term maintenance, especially for production XWiki instances.
metaTitle
... ... @@ -1,1 +1,0 @@
1 -Why You Should Upgrade XWiki Regularly for Security and Stability | Agnease