Changes for page Why You Should Upgrade XWiki Regularly for Security and Stability

Last modified by Agnease on 2026/05/26 10:58

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

From 1.4 to 1.3 From 1.12 to 1.11

From version 1.11

edited by Agnease
on 2026/05/18 19:01

Change comment: There is no comment for this version

To version 1.4

edited by Agnease
on 2026/05/12 14:47

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -2,167 +2,292 @@
  #set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
  {{html clean="false"}}
--  <section class="resource-header" aria-labelledby="hero-title">
--    <div class="container">
--      <div class="text-center">
--        <div class="hero-kicker">
--          <i class="fa fa-refresh" aria-hidden="true"></i>
--          XWiki upgrade guidance
--        </div>
++  ## PAGE HEADER
++  <section class="hero hero-centered service-hero" aria-labelledby="hero-title">
++    <div class="container hero-inner">
++      <div class="hero-kicker">
++        <i class="fa fa-refresh" aria-hidden="true"></i>
++        XWiki upgrade guidance
        </div>
        <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
--      <p class="resource-summary">
++      <p class="lead">
          A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
          when upgrades are postponed for too long.
        </p>
++
++      <p class="hero-support">
++        Regular upgrades help keep XWiki secure, stable, compatible and easier to evolve, especially when the platform
++        is used for internal knowledge, documentation, procedures, workflows or business-critical collaboration.
++      </p>
++
++      <div class="hero-actions">
++        <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View upgrade services</a>
++        <a class="btn btn-secondary" href="#upgrade-tips">Read upgrade tips</a>
++      </div>
      </div>
    </section>
--  <section class="resource-page">
++  ## WHY IT MATTERS
++  <section aria-labelledby="why-title">
      <div class="container">
--      <div class="resource-layout">
++      <h2 id="why-title">“It still works” is not the same as “it is safe to keep unchanged”</h2>
--        <article class="resource-content">
++      <p class="section-intro">
++        Many XWiki instances continue to run for years with only small visible problems. That can create the impression
++        that upgrades are optional. In practice, the longer an instance stays behind, the more risk accumulates around
++        security fixes, extension compatibility, infrastructure changes, custom code and future upgrade effort.
++      </p>
++      <div class="pathways">
++        <article class="pathway-card">
++          <div class="pathway-icon">
++            <i class="fa fa-shield" aria-hidden="true"></i>
++          </div>
++          <h3>Security fixes accumulate</h3>
            <p>
--            Many XWiki instances continue to run for years with only small visible problems. This can create the
--            impression that upgrades are optional, especially when users can still log in, search, edit pages and
--            access the content they need.
++            Older versions may miss security-related fixes and improvements that are already available in newer releases.
            </p>
++          <ul>
++            <li>Known issues may already be fixed upstream</li>
++            <li>Public information about vulnerabilities increases risk over time</li>
++            <li>Security updates are easier to handle when upgrades are regular</li>
++          </ul>
++        </article>
++        <article class="pathway-card">
++          <div class="pathway-icon">
++            <i class="fa fa-puzzle-piece" aria-hidden="true"></i>
++          </div>
++          <h3>Compatibility becomes harder</h3>
            <p>
--            The real risk is that technical debt accumulates quietly. Security fixes, extension compatibility,
--            authentication behavior, infrastructure requirements and custom code assumptions continue to evolve.
--            The longer an instance remains behind, the more difficult the next upgrade becomes.
++            Extensions, custom applications, authentication integrations and infrastructure components evolve together.
            </p>
++          <ul>
++            <li>Extensions may require newer XWiki versions</li>
++            <li>Java, Tomcat and database requirements can change</li>
++            <li>Large version jumps are harder to validate</li>
++          </ul>
++        </article>
--          <div class="resource-note">
++        <article class="pathway-card">
++          <div class="pathway-icon">
++            <i class="fa fa-line-chart" aria-hidden="true"></i>
++          </div>
++          <h3>Maintenance cost increases</h3>
++          <p>
++            The longer upgrades are postponed, the more difficult it becomes to understand what changed and what may break.
++          </p>
++          <ul>
++            <li>More release notes to review</li>
++            <li>More compatibility checks to perform</li>
++            <li>More risk around custom code and old assumptions</li>
++          </ul>
++        </article>
++      </div>
++    </div>
++  </section>
++
++  ## WHAT TO REVIEW
++  <section id="upgrade-tips" class="services" aria-labelledby="tips-title">
++    <div class="container">
++      <h2 id="tips-title">Practical tips before planning an XWiki upgrade</h2>
++
++      <p class="section-intro">
++        A good upgrade starts before the installation step. The most useful preparation is to understand the current
++        platform, identify what is business-critical and validate the upgrade outside production.
++      </p>
++
++      <div class="services-grid">
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-code-fork"></i>
++          </div>
++          <div class="service-body">
++            <h4>Check your current version and target version</h4>
              <p>
--              <strong>The main point:</strong> regular upgrades are not only about new features. They reduce security
--              exposure, compatibility risk and long-term maintenance cost.
++              Identify the current XWiki version, the desired target version and whether intermediate upgrade steps are needed.
              </p>
            </div>
++        </article>
--          <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-puzzle-piece"></i>
++          </div>
++          <div class="service-body">
++            <h4>Review installed extensions</h4>
++            <p>
++              List installed extensions and check whether they are compatible with the target XWiki version.
++            </p>
++          </div>
++        </article>
--          <h3>1. Security fixes accumulate over time</h3>
--          <p>
--            Older versions may miss security-related fixes already available in newer releases. Once security issues
--            become publicly known, running an old version can become a more predictable risk.
--          </p>
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-code"></i>
++          </div>
++          <div class="service-body">
++            <h4>Identify custom code</h4>
++            <p>
++              Review custom macros, Velocity scripts, Java components, UI extensions, sheets, templates and local changes.
++            </p>
++          </div>
++        </article>
--          <p>
--            This does not mean every old instance is immediately exposed in the same way. The real impact depends on
--            your configuration, installed extensions, access model, authentication setup and whether the instance is
--            public or private. But staying close to supported versions makes security maintenance more manageable.
--          </p>
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-lock"></i>
++          </div>
++          <div class="service-body">
++            <h4>Validate authentication</h4>
++            <p>
++              LDAP, Active Directory, SSO, OIDC, SAML and MFA configurations should be tested carefully after the upgrade.
++            </p>
++          </div>
++        </article>
--          <h3>2. Large upgrade gaps are harder to control</h3>
--          <p>
--            A small, regular upgrade is usually easier to validate than a large jump after several years. Large gaps
--            mean more release notes, more compatibility changes, more extension checks and more uncertainty around
--            custom code.
--          </p>
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-database"></i>
++          </div>
++          <div class="service-body">
++            <h4>Prepare backups and a staging clone</h4>
++            <p>
++              Never treat production as the first test. Validate the upgrade on staging or a temporary clone first.
++            </p>
++          </div>
++        </article>
--          <h3>3. Extensions and customizations can become fragile</h3>
--          <p>
--            XWiki instances often include installed extensions, custom Velocity scripts, macros, templates, sheets,
--            UI extensions, Java components or business-specific applications. These elements need to be reviewed when
--            planning an upgrade.
--          </p>
++        <article class="service">
++          <div class="service-icon" aria-hidden="true">
++            <i class="fa fa-check-square-o"></i>
++          </div>
++          <div class="service-body">
++            <h4>Create a validation checklist</h4>
++            <p>
++              Test login, permissions, search, dashboards, PDFs, custom applications, jobs, important pages and integrations.
++            </p>
++          </div>
++        </article>
++      </div>
++    </div>
++  </section>
--          <h3>4. Infrastructure requirements evolve</h3>
++  ## SAFE PROCESS
++  <section class="split-section" aria-labelledby="process-title">
++    <div class="container">
++      <div class="split-grid">
++        <div class="split-copy">
++          <h2 id="process-title">The safest upgrade is the one rehearsed before production</h2>
++
            <p>
--            XWiki upgrades can involve more than the application itself. Java, Tomcat, the database, Docker images,
--            reverse proxy configuration, PDF export services and authentication integrations may also need attention.
++            A production upgrade should not be the first time the process is tested. A staging environment or temporary
++            clone allows problems to be discovered before they affect users.
            </p>
--          <h3>5. Business-critical features need validation</h3>
            <p>
--            A successful upgrade is not only one where the server starts. Users usually depend on login, permissions,
--            search, dashboards, PDF exports, workflows, notifications, custom applications and important pages. These
--            should be part of the validation plan.
++            This is especially important when the instance includes custom applications, authentication integrations,
++            PDF exports, workflows, advanced permissions or business-critical documentation.
            </p>
++        </div>
--          <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
++        <ol class="process-list">
++          <li>
++            <strong>Prepare a staging clone</strong>
++            Copy the relevant database, filesystem and configuration into a controlled non-production environment.
++          </li>
++          <li>
++            <strong>Run the upgrade there first</strong>
++            Apply the upgrade, resolve compatibility issues and record the steps required.
++          </li>
++          <li>
++            <strong>Validate business-critical features</strong>
++            Confirm that authentication, rights, search, exports, custom apps and important workflows still work.
++          </li>
++          <li>
++            <strong>Plan the production window</strong>
++            Define backup, downtime, rollback and communication expectations before touching production.
++          </li>
++          <li>
++            <strong>Document the result</strong>
++            Keep upgrade notes, observed issues and follow-up recommendations for the next maintenance cycle.
++          </li>
++        </ol>
++      </div>
++    </div>
++  </section>
--          <ul class="resource-checklist">
--            <li>Identify the current XWiki version and the target version.</li>
--            <li>Check whether intermediate upgrade steps are needed.</li>
--            <li>List installed extensions and verify compatibility with the target version.</li>
--            <li>Identify custom code: Velocity scripts, macros, sheets, templates, UI extensions and Java components.</li>
--            <li>Review authentication: LDAP, Active Directory, SSO, OIDC, SAML or MFA.</li>
--            <li>Prepare a staging environment or temporary clone of production.</li>
--            <li>Validate backups and clarify rollback expectations.</li>
--            <li>Test important pages, dashboards, permissions, search, jobs, exports and custom workflows.</li>
--            <li>Document the steps, issues found and follow-up recommendations.</li>
--          </ul>
++  ## COMMON MISTAKES
++  <section aria-labelledby="mistakes-title">
++    <div class="container">
++      <h2 id="mistakes-title">Common mistakes to avoid</h2>
--          <h2 id="safe-process">A safer upgrade process</h2>
++      <p class="section-intro">
++        Most difficult upgrades are not difficult because XWiki cannot be upgraded. They become difficult because
++        the environment, customizations or validation steps were not understood early enough.
++      </p>
++      <div class="widgets">
++        <article class="widget">
++          <div class="icon" aria-hidden="true">
++            <i class="fa fa-warning"></i>
++            <h4>Upgrading<br />directly in production</h4>
++          </div>
            <p>
--            Production should not be the first place where the upgrade is tested. The safest approach is to rehearse
--            the upgrade on staging or a temporary clone, resolve compatibility issues there, then perform the production
--            upgrade with a clear plan.
++            Production should not be the first place where compatibility issues are discovered.
            </p>
++        </article>
--          <ol>
--            <li><strong>Prepare a clone:</strong> copy the relevant database, filesystem and configuration.</li>
--            <li><strong>Run the upgrade outside production:</strong> record the steps and issues found.</li>
--            <li><strong>Validate critical features:</strong> login, rights, search, PDFs, workflows, dashboards and integrations.</li>
--            <li><strong>Plan the production window:</strong> backups, downtime, rollback and communication.</li>
--            <li><strong>Document the result:</strong> keep notes for the next upgrade cycle.</li>
--          </ol>
--
--          <h2 id="common-mistakes">Common mistakes to avoid</h2>
--
--          <ul>
--            <li><strong>Upgrading directly in production.</strong> Compatibility issues should be discovered before users are affected.</li>
--            <li><strong>Checking only public pages.</strong> Authentication, restricted spaces and admin features also need validation.</li>
--            <li><strong>Ignoring custom code.</strong> Custom scripts and extensions often create the real upgrade complexity.</li>
--            <li><strong>Skipping backup validation.</strong> A backup is useful only if restore expectations are understood.</li>
--            <li><strong>Keeping no upgrade notes.</strong> Without notes, the next maintenance cycle starts again from uncertainty.</li>
--          </ul>
--
--          <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
--
++        <article class="widget">
++          <div class="icon" aria-hidden="true">
++            <i class="fa fa-puzzle-piece"></i>
++            <h4>Ignoring<br />extensions</h4>
++          </div>
            <p>
--            For many organizations, a practical rhythm is to stay aligned with the current Long Term Support version
--            and plan upgrades regularly rather than waiting for a major problem. Some environments can upgrade more
--            frequently, while heavily customized instances may require more planning.
++            Extensions and custom code often create the real upgrade complexity.
            </p>
++        </article>
++        <article class="widget">
++          <div class="icon" aria-hidden="true">
++            <i class="fa fa-lock"></i>
++            <h4>Testing only<br />public pages</h4>
++          </div>
            <p>
--            The important part is not only the exact frequency. It is having an upgrade process that is repeatable:
--            review, staging validation, production rollout, documentation and follow-up.
++            Login, permissions, restricted spaces and admin features should also be validated.
            </p>
++        </article>
--          <div class="resource-cta">
--            <h3>Need help planning an XWiki upgrade?</h3>
--            <p>
--              If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
--              the current version, extensions, infrastructure and validation needs before planning the production upgrade.
--            </p>
--            <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
++        <article class="widget">
++          <div class="icon" aria-hidden="true">
++            <i class="fa fa-file-text-o"></i>
++            <h4>No upgrade<br />notes</h4>
            </div>
--
++          <p>
++            Without notes, every future upgrade starts again from uncertainty.
++          </p>
          </article>
++      </div>
++    </div>
++  </section>
--        <aside class="resource-sidebar" aria-label="Page summary">
--          <h4>In this guide</h4>
--          <ul>
--            <li><a href="#why-it-matters">Why upgrades matter</a></li>
--            <li><a href="#upgrade-checklist">Upgrade checklist</a></li>
--            <li><a href="#safe-process">Safe process</a></li>
--            <li><a href="#common-mistakes">Common mistakes</a></li>
--            <li><a href="#upgrade-rhythm">Upgrade rhythm</a></li>
--          </ul>
--        </aside>
++  ## CTA
++  <section class="cta-section" aria-labelledby="cta-title">
++    <div class="container">
++      <div class="cta-panel">
++        <h2 id="cta-title">Need help planning an XWiki upgrade?</h2>
++        <p>
++          If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
++          the current version, extensions, infrastructure and validation needs before planning the production upgrade.
++        </p>
++
++        <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View XWiki upgrade services</a>
        </div>
      </div>
    </section>
++
  {{/html}}
  {{/velocity}}