Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 8.2
edited by Agnease
on 2026/05/26 09:14
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,176 +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 - </ul>
36 - </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 +}
37 37  
38 - <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 +}
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>
53 +.resource-content {
54 + color: @text;
55 + font-size: 16px;
56 + line-height: 1.68;
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>
58 + h2 {
59 + text-align: left;
60 + margin: 34px 0 12px;
61 + line-height: 1.28;
62 + }
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>
64 + h3 {
65 + margin: 24px 0 8px;
66 + line-height: 1.3;
67 + }
58 58  
59 - <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
69 + p {
70 + margin: 0 0 16px;
71 + }
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>
73 + ul,
74 + ol {
75 + margin: 0 0 18px;
76 + padding-left: 22px;
77 + }
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>
79 + li {
80 + margin: 6px 0;
81 + }
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>
83 + strong {
84 + color: @text;
85 + }
86 +}
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>
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;
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>
95 + p:last-child {
96 + margin-bottom: 0;
97 + }
98 +}
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>
100 +.resource-checklist {
101 + margin: 18px 0 24px;
102 + padding: 0;
103 + list-style: none;
99 99  
100 - <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
105 + li {
106 + position: relative;
107 + padding: 10px 0 10px 34px;
108 + border-bottom: 1px solid @line;
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>
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 - <h2 id="safe-process">A safer upgrade process</h2>
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;
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>
130 + h4 {
131 + margin: 0 0 10px;
132 + }
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>
134 + ul {
135 + margin: 0;
136 + padding-left: 18px;
137 + color: @muted;
138 + }
129 129  
130 - <h2 id="common-mistakes">Common mistakes to avoid</h2>
140 + li {
141 + margin: 8px 0;
142 + }
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>
144 + a {
145 + color: @brand;
146 + font-weight: 600;
147 + }
148 +}
139 139  
140 - <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</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;
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>
157 + h3 {
158 + margin-top: 0;
159 + }
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>
161 + p {
162 + color: @muted;
163 + }
164 +}
152 152  
153 - <div class="resource-note">
154 - <p>
155 - Related resources:
156 - <a href="$xwiki.getURL('resources.xwiki-security-reviewi')">what an XWiki security review should actually include</a>
157 - and
158 - <a href="$xwiki.getURL('resources.xwiki-custom-development')">how to keep XWiki custom development maintainable across upgrades</a>.
159 - </p>
160 - </div>
166 +@media (max-width: 900px) {
167 + .resource-layout {
168 + grid-template-columns: 1fr;
169 + }
161 161  
162 - <div class="resource-cta">
163 - <h3>Need help planning an XWiki upgrade?</h3>
164 - <p>
165 - If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
166 - the current version, extensions, infrastructure and validation needs before planning the production upgrade.
167 - </p>
168 - <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
169 - </div>
170 -
171 - </article>
172 - </div>
173 - </div>
174 - </section>
175 -{{/html}}
176 -{{/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