Wiki source code of why-upgrade-xwiki

Version 6.1 by Alex Cotiuga on 2026/05/22 06:11

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Siblings
- Content
- Comments
- Attachments
- History
- Information
- Likes

version	line-number	content
1.6	1	{{velocity}}
	2	#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
	3	{{html clean="false"}}
1.1	4
1.6	5	<section class="resource-header" aria-labelledby="hero-title">
	6	<div class="container">
	7	<div class="text-center">
1.11	8	<div class="hero-kicker">
1.6	9	<i class="fa fa-refresh" aria-hidden="true"></i>
	10	XWiki upgrade guidance
	11	</div>
	12	</div>
1.1	13
1.6	14	<h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
1.1	15
1.6	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>
1.1	22
1.6	23	<section class="resource-page">
	24	<div class="container">
	25	<div class="resource-layout">
1.1	26
1.12	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>
	37
1.6	38	<article class="resource-content">
1.1	39
1.6	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>
1.1	45
1.6	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>
1.1	51
1.6	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>
1.1	58
1.6	59	<h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
1.1	60
1.6	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>
1.1	66
1.6	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>
1.1	72
1.6	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>
1.1	79
1.6	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>
1.1	86
1.6	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>
1.1	92
1.6	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>
1.1	99
1.6	100	<h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
1.1	101
1.6	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>
1.1	113
1.6	114	<h2 id="safe-process">A safer upgrade process</h2>
1.1	115
1.6	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>
1.1	121
1.6	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>
1.1	129
1.6	130	<h2 id="common-mistakes">Common mistakes to avoid</h2>
1.1	131
1.6	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>
1.1	139
1.6	140	<h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
1.1	141
1.6	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>
1.1	147
1.6	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>
1.1	152
1.6	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>
1.10	159	<a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
1.6	160	</div>
1.1	161
1.6	162	</article>
	163	</div>
	164	</div>
	165	</section>
	166	{{/html}}
	167	{{/velocity}}