What XWiki upgrade and support work involves
Upgrade and support work for XWiki covers four things: choosing the release line you will stay on, planning and rehearsing each upgrade on a copy of production, testing extensions and customizations against the new core, and running the wiki after go-live. Most of the effort sits in the second and third items, not in the file replacement itself. Start by deciding which line fits your organization: the stable line, the long term support (LTS) line or the intermediate LTS line. At the time of research the official Docker image tags were 18.8.0 for stable, 17.10.14 for LTS and 18.4.7 for the intermediate LTS. Confirm current tags with the XWiki project before you pin a version.
Four kinds of trigger usually start this work. The first is a release line that is approaching the end of its useful life for your organization, which you should judge against your own change windows and approval cycles. The second is a security release, which needs a fast, tested path. The third is an extension that requires a newer core version. The fourth is a team with no one who has run an XWiki upgrade before. Ask any partner for a written plan covering the upgrade rehearsal, the extension compatibility list, the rollback procedure and who signs off on the cutover.
For routine minor upgrades, a team with an operator who understands Java, Tomcat and the chosen database, and a patient test process, can often manage alone. A partner is most useful for the first major move, for wikis with many third-party or custom extensions, and for recurring support coverage that matches your service hours. The usual deployment base is the official XWiki Docker images in MySQL, PostgreSQL and MariaDB variants, each running on Tomcat. These images are maintained by the XWiki Core Dev Team, so confirm which tag and database variant your environment pins and how you will track its updates. Support terms, response times and any retainer should be written into the scope before work starts.
What the service includes
The engagement splits into one-time upgrade work that ends at cutover and recurring support that runs after go-live. The exact response times and coverage come from the written scope and from the XWiki support plan you hold, so ask for both in writing.
Release line decision record
A short written record of which XWiki line you will run (stable, LTS or intermediate LTS), why, and when you will next review that choice. It names the current official Docker image tags, the database and servlet variant, and who approved the decision. Ask for it before any upgrade work starts so the target version is agreed, not assumed.
Upgrade runbook
A step-by-step procedure covering backups, database and configuration changes, extension updates, the order of operations and the checks at each step. It records who performs each action and what to do if a step fails. Review it with your operations team so the person on call can follow it without the author present.
Staging environment rehearsal
A full dry run of the upgrade on a copy of production data and configuration, built to match production's servlet container, database and extensions. The rehearsal measures how long each step takes and surfaces failures before users are affected. Confirm that staging holds representative content and real permission structures.
Extension compatibility report
A list of every installed extension, application and skin, with its current version, the version needed for the target release, and the action required: upgrade, replace, remove or keep with a documented risk. Custom code and third-party extensions usually need the closest review, so ask which ones have no vendor support path.
Regression test scripts
Scripted checks for the key spaces, pages, macros and scripts your users depend on, including search results, permission outcomes and rendering of custom macros. Each script states the expected result so a tester can pass or fail it without judgment calls. Agree the list of critical spaces with the business owners before testing begins.
Cutover and rollback plan
The window, freeze rules, go or no-go criteria, communication steps and the rollback path with its own tested backup restore. It names who can call a rollback and the point after which rollback is no longer practical. Ask how user edits made during the window are handled before you approve the plan.
Post-upgrade verification
Checks run on production after cutover, covering the regression scripts, search index health, scheduled jobs, authentication flows and error logs. The results are written up and signed off by your owner, with any open defects tracked to closure. Verification ends the one-time work and hands over to the support schedule.
Support schedule
The recurring service after go-live: monitoring of the platform, review of XWiki security and patch releases, scheduled backup restore tests, and a named contact for incidents. Response times and coverage hours are set by the written scope and your XWiki support plan, so confirm both in writing before you rely on them.
What drives upgrade cost and duration
This table lists the factors that change how much work an XWiki upgrade takes, why each one matters and what you can do to keep it contained.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Installed extensions | Each extension must work on the target release, and most upgrade effort comes from checking and replacing extensions rather than from the core package itself. | Inventory every extension with its version, remove unused ones, and confirm target-version compatibility with the extension maintainer before scheduling. |
| Custom Groovy and Velocity scripts | Scripts that call internal APIs can break when those APIs change between releases, and each break needs diagnosis and a fix. | Keep scripts small, document the APIs they call, and move reusable logic into a tested extension with its own test cases. |
| Macros and page content | Macros that depend on older syntax or deprecated behavior may render differently or fail after the upgrade, and affected pages must be found and checked. | Run a scan of macro usage across spaces, prioritize heavily used pages, and fix or retire macros that no longer serve a purpose. |
| Gap between current and target version | A larger jump means more release notes to review, more migrations to run and more extensions that may lack a matching release. | Plan intermediate steps where the vendor documentation calls for them, and keep the target on a supported line such as LTS. |
| Number of spaces and attachments | Migration and reindexing time grow with content volume, and large attachment stores lengthen backup and restore windows. | Archive inactive spaces, clean up unused attachments before the upgrade, and measure content volume in a staging copy. |
| Database engine and size | Schema migrations run against the database, and engine choice (MySQL, PostgreSQL or MariaDB) and data size affect how long they take and how a rollback is handled. | Take a verified database backup, confirm the engine and version are supported for the target release, and test the migration timing on a copy. |
| Number of environments and staging copy | Without a staging copy, issues surface in production, and each additional environment adds a test cycle. | Maintain a staging environment built from a recent production backup, and keep environment configuration in version control. |
| Integrations such as SSO and Confluence exports | Identity connectors, reverse proxy rules and any data exchanges with Confluence must be retested after the upgrade. | List every integration with its owner, add a test for each login path and data flow, and retest these before cutover. |
| Skin customization | Custom skins and template overrides depend on page structure and CSS classes that can change between releases. | Keep skin changes minimal, use supported extension points where available, and review them in staging before each upgrade. |
| Edition in use | XWiki Standard relies on community extensions, while XWiki Pro includes Pro apps and support plans that may need their own version checks and renewals. | Confirm which Pro apps are installed and their target-version support, and ask the vendor for a compatibility statement before the upgrade window. |
Project phases and outputs
The sequence moves from an inventory of what is installed to a rehearsed, signed-off upgrade and a support schedule that keeps the wiki on a supported line afterward.
Inventory the installation and choose the target line
The team lists the running XWiki version, database and servlet container, installed extensions, scripts and customizations, then compares the current line with the stable, LTS and intermediate LTS options. The output is an installed extension and script inventory and a documented target line decision, which the client approves before any build work starts.
Build a staging copy and rehearse the upgrade
The team restores a recent copy of production data into a staging environment in the client's infrastructure and runs the planned upgrade path against it. The rehearsal is complete when the upgrade finishes on the copy and every failure is logged with its cause and fix, producing a rehearsed upgrade on a production copy.
Fix or replace extensions and customizations
Each extension and custom script is checked against the target release. Incompatible items receive a compatibility fix, or a replacement plan where the extension is no longer suitable. The output is a compatibility fix or replacement plan for every extension in the inventory, reviewed by the client's wiki owner.
Run regression tests on key spaces
Testers, usually the client's content owners with DeployOpen support, run scripted checks on the spaces that carry the most business use: page rendering, macros, search, permissions, attachments and any applications used in those spaces. The output is signed-off test results for each key space, with open defects tracked to closure or accepted by the client in writing.
Rehearse cutover and rollback
The team writes a runbook with each cutover step timed on the staging environment, including database backup, maintenance mode, upgrade, post-upgrade checks and the rollback path. The rehearsal is complete when the runbook names a rollback point and the team has actually executed the rollback once. The output is that runbook.
Go live and run hypercare
The upgrade runs in the production window set out in the runbook, followed by post-upgrade checks on rendering, search, authentication and key spaces. A hypercare period follows in which incidents are logged with their status and resolution. The output is the post-upgrade check record and an incident log that the client signs off.
Hand over to the support schedule
The team transfers the documentation, inventory, runbook and open items to the client's operators and agrees the ongoing support arrangement, including who applies patch releases and how extension updates are tested. The handover is complete when the client confirms receipt and the support schedule is in place.
What teams keep in-house and what they outsource
This table shows which XWiki upgrade and support work most teams keep internally, which they often hand to a partner, and the skills each area needs, so you can judge where your own gaps are.
| Work area | Usually kept in-house | Usually outsourced | Skills needed |
|---|---|---|---|
| Page correctness sign-off | Business owners confirm that key pages, processes and reference content are still right after each upgrade | Test scripts or checklists written with the partner from owner input | Domain knowledge of the content and its consumers |
| Space content review | Space owners review their spaces after the upgrade and report macro, layout or rendering problems | Triage of technical defects found during review | Knowledge of how each space is used day to day |
| Tomcat and database operations | Internal operators run the servlet container, database and reverse proxy on a routine basis | Initial setup, runbook writing and knowledge transfer for the first upgrade cycle | Linux administration, Tomcat, MySQL, PostgreSQL or MariaDB administration |
| Backup and restore | Your team owns backup schedules, retention and proven restore tests | Restore rehearsal design and a first end-to-end test in a staging copy | Database backup tooling, file-level backup of XWiki data, restore procedures |
| Extension selection and testing | Your team decides which extensions the wiki needs and signs off their use | Compatibility testing of extensions against the target XWiki version before the upgrade | Extension manager knowledge, XWiki release notes review, test environments |
| Custom code changes | Owners of custom applications or scripts approve changes and keep them documented | Porting custom code and macros to the target version and fixing breakage | XWiki scripting, Velocity and Groovy, Java where extensions are involved |
| Release planning | Your team chooses the target line (stable, LTS or intermediate LTS) and sets the upgrade calendar | Upgrade plan drafting, effort estimate and staged rollout proposal | Understanding of XWiki release lines and your change control process |
| On-call and incident response | Internal staff receive alerts and decide on rollback during business hours and after hours | Optional retainer covering out-of-hours escalation, if contracted | Monitoring, log analysis and the XWiki admin console |
What goes wrong and how to prevent it
Most failed XWiki upgrades trace back to a few preventable gaps. Each card names the risk and the check that closes it.
Staying on an unsupported line
Running an older XWiki line past its support window means security fixes arrive late or not at all. Confirm the support dates for your current line in XWiki's release information, and plan the move to an LTS or intermediate LTS line before support ends. Security releases also need a fast path that skips the normal change cycle. Hardening detail is in the security hardening topic.
Upgrading core without extension checks
Extensions are versioned separately from the core, so an upgrade can break an extension that worked before. Before the upgrade, list every installed extension with its version, check each one against the target release, and test them on a staging copy of production data. Remove unused extensions so the test list stays short.
Custom scripts that break silently
Scripts in pages, macros and application code often fail without an error on screen, so users discover the breakage days later. Inventory every script that calls an API or renders dynamic content, define the expected output for each, and compare results on staging after the upgrade. Keep scripts in version control with a named owner.
Skipped migration steps and runtime drift
An upgrade may require database migration and a rebuilt search index, and skipping either leaves pages missing from results or the wiki misbehaving. Write both as ordered runbook steps with a check after each. The search topic covers index repair in detail. Also confirm the Java and Tomcat versions the target release requires, and match them on staging before cutover.
Backups and rollback never tested
A backup that has never been restored is an assumption, not a recovery plan. Restore a recent backup of the database and the XWiki data directory to a separate host, then start the target version against it. Rehearse the rollback on the same copy and time each step, so the team knows before the window opens whether reverting is practical.
Changes made directly in production
Fixes applied live during an upgrade window bypass staging and often never reach the next environment. Freeze production configuration, extensions and scripts for the window, route every change through the runbook, and record any emergency edit so it is replayed on staging. Name who approves changes during the window before it starts.
How the work changes by starting point
An instance on an older line may need to cross more than one release before it reaches a newer LTS, so the plan starts with the upgrade path.
- Plan: Confirm the supported upgrade path from your current line to the target in the XWiki release notes, and decide whether an intermediate step is needed. Check which LTS and intermediate LTS tags are current, since the tags listed at research time were 17.10.14 for LTS and 18.4.7 for the intermediate LTS.
- Verify: Run the upgrade on a copy of production data, then check every extension, custom script and macro for behavior changes.
- Provide: A current inventory of installed extensions, the database and servlet container versions, a recent verified backup and a test environment that resembles production.
- Confirm: The database and Java servlet container requirements of the target line with the release documentation before any hosts are changed.
Moving from XWiki Standard to a Pro subscription during an upgrade adds licensing and application decisions to the technical work.
- Plan: List the Pro applications and connectors you need, such as directory SSO, file management or Office365 connectors, and confirm which needs the free Standard edition already covers.
- Verify: Confirm with XWiki SAS that each Pro application supports the target line, then install and test them on staging before cutover.
- Provide: Your user count, so the subscription tier can be matched to it, a named owner for the support contract and a list of required applications.
- Confirm: The support scope and tier limits in writing, and whether consulting depends on a Business or Enterprise support plan.
With the official Docker images, the upgrade is mainly an image tag change, but persistent storage, database configuration and orchestration settings carry most of the risk.
- Plan: Choose the image variant that matches your database (MySQL, PostgreSQL or MariaDB), and confirm it matches the existing data store before changing tags.
- Verify: Check that volumes holding attachments and configuration survive the new container, that environment variables still apply, and that the target architecture (amd64 or arm64v8) matches your nodes.
- Kubernetes: Confirm that database schema migration runs once rather than on every replica, and review health probes and rolling update settings.
- Provide: Your current Compose files or Helm values, the storage class, the backup method and the registry your images are pulled from.
In a restricted network, every image, extension and dependency must be fetched, reviewed and mirrored before the upgrade can start, so the schedule depends on the transfer process.
- Plan: Mirror the exact image tags for the target line and the matching database image into your internal registry, and record their digests.
- Verify: Confirm that extensions and their dependencies are downloaded and approved offline, including any that try to fetch resources from external repositories at startup.
- Provide: An internal registry, an approved transfer process for one-way imports, and a sign-off path for new software.
- Confirm: With XWiki SAS and your security team how security releases and Pro application updates will reach a network with no direct internet access.
Custom extensions and paid apps often set the upgrade schedule, because each one needs a version that supports the target line.
- Plan: Build an extension register listing each extension's source, version, owner and type (custom, paid or community), then remove unused extensions before testing.
- Verify: Test each extension on the target line, check for deprecated APIs and scripting patterns, and confirm that every paid app has a release for that line.
- Provide: Source code and build access for custom work, licenses for paid apps and an owner who signs off on behavior changes.
- Confirm: With the extension authors or vendors which versions they support, and how long a fix takes if one breaks during testing.
What the client needs to provide
The upgrade cannot start until the client supplies access to the current XWiki servers or containers and to the database, along with a current backup and a restore test completed against that backup. A backup that has never been restored is not evidence of recoverability, so ask your team to restore it into a separate environment and confirm that pages, attachments and users come back. Also supply an inventory of installed extensions, or read-only access to the extension list in the administration area, so the provider can check each one against the target release before any change is made.
Name business owners for the key spaces who will test after the upgrade. Each owner should be able to log in with a test account, open the pages they depend on, run the macros and applications their teams use, and sign off in writing. Agree a maintenance window with the people who own the wiki's users, because the upgrade will take the site offline or make it read-only for a period. Provide a staging environment that matches production as closely as possible in servlet container version, database engine, extensions, operating system and reverse proxy configuration. Differences between staging and production are the most common reason a tested upgrade fails at cutover.
The client must decide the target release line before scoping starts. The options are the stable line, the long term support line and the intermediate LTS line, and that choice determines how often the wiki must be moved again. Also confirm which XWiki support plan the organization holds, because that determines what vendor support from XWiki SAS is available during and after the upgrade. Ask the vendor directly to confirm the plan, its user tier and its coverage terms, rather than relying on an internal record that may be out of date.
Decide before go-live who approves the cutover. In most organizations this is the wiki owner together with the business owners who signed testing, and the approval should be recorded in writing with the rollback conditions. Agree after handover who owns incidents: the internal platform team for the servlet container, database and network, the wiki administrators for spaces and rights, and the support provider for defects in XWiki itself or in extensions. Write these ownership boundaries into the handover document so that an outage on the first Monday after go-live does not stall while teams argue about responsibility.
Frequently asked questions
Should we run the stable line or an LTS line of XWiki?
For a wiki that several teams depend on, an LTS line is often the better starting point, while the stable line suits teams that want the newest features and can upgrade more often. At the time of research, the official Docker tags were 18.8.0 for stable and 17.10.14 for LTS, so the choice shows up in the image version you pin. Consider how quickly your team can complete a release cycle, whether your extensions track the same line, and how long you need each version to receive fixes. Confirm the support window for each line with XWiki SAS before you commit.
Is the intermediate LTS line a good fit for a new XWiki deployment?
It can be, when you want newer functionality than the full LTS line provides without moving to the stable line every few months. At the time of research, the official intermediate LTS Docker tag was 18.4.7, alongside the stable tag 18.8.0 and the LTS tag 17.10.14. Check which extensions and Pro applications you need, because a feature you depend on may be available in only one line. Ask XWiki SAS for the support length and upgrade path of the intermediate line, since those terms determine how long you can stay on it.
How much does an XWiki upgrade cost and what drives it?
Cost depends mainly on scope: the number of extensions, the amount of custom code, the size of the wiki and the number of environments that need testing. One-time work includes the impact assessment, test plan, upgrade rehearsal, fixes to custom code or extensions, and cutover. Recurring costs include support subscriptions and any retainer you choose for later upgrades. If you buy consulting from XWiki SAS, its listed rate is 1200 EUR per day, and that rate requires a Business or Enterprise support plan. Ask any provider for a quote built on a written scope that lists each environment and extension separately.
Can our own team upgrade XWiki without an outside partner?
Yes, a team can handle a minor upgrade in-house if it has a staging copy, a tested backup and someone who understands the Tomcat and database layers. The harder cases involve custom extensions, customized templates, scripts that depend on internal APIs, or a jump across several major versions. Your team must own the rollback plan, the post-upgrade checks and the extension compatibility review. Decide based on who would fix a broken macro late on a Friday. Bring in an outside partner when skills, capacity or the deadline are missing, and ask for the work to be written as a fixed scope.
How do we test extensions before upgrading XWiki?
Build a staging environment from a recent backup, then upgrade it to the target version before touching production. Start with an inventory of every installed extension, application and skin, including the version each one is pinned to and whether it comes from XWiki Pro. Next, test the functions people actually use: page creation and editing, search, permissions, scripted macros, SSO login and any connector to other systems. Record which extensions have a compatible release for the target line, and treat any without one as a blocker. Rehearse the rollback path too, including restoring the database and files.
What does support after go-live include, and do we need a plan?
Support after go-live typically covers incident response, security releases, upgrades within your chosen line and questions about configuration, depending on the plan you buy. XWiki SAS sells support in four tiers: Starter for up to 25 users on XWiki Cloud only, Basic for up to 1,000 users, Business for up to 10,000 users and Enterprise for unlimited users. XWiki SAS states that cloud and on-premises pricing is the same. Confirm with XWiki SAS how long support lasts for each release line and what response times apply. DeployOpen can also provide ongoing support, upgrades and testing under a retainer.
How DeployOpen delivers XWiki upgrades and support
DeployOpen plans and carries out XWiki upgrades in infrastructure you control, starting with a written scope that names the release line, extensions and environments involved. Support after go-live is available as a retainer, so the people who upgraded your wiki can keep it on a supported line.
How we scope
- Confirm the current XWiki version, database variant and servlet container before agreeing which release line you move to.
- Inventory installed extensions, custom applications and skins, and record which ones must be retested before any upgrade.
- Agree in writing which environments, data volumes and user groups the upgrade covers, and what is excluded.
How we build
- Rehearse the upgrade on a copy of production data in a staging environment that mirrors your database and Tomcat setup.
- Test extensions, search, permissions and key knowledge base spaces against the target release before cutover is scheduled.
- Document each step, rollback point and backup check so the upgrade can be repeated or reversed by your team.
How we hand over
- Deliver a runbook covering the upgrade sequence, configuration changes, extension versions and verification checks performed.
- Walk your administrators through the post-upgrade checklist, including reindexing, log review and user acceptance testing.
- Record the agreed retainer or support scope, contacts and escalation steps so ownership after handover is clear.
How we support
- Ongoing support is available as a retainer, covering planned upgrades to a supported XWiki line and review of security releases.
- Retainer work is scoped in writing, so you can see which upgrades, testing cycles and incident responses are included.
- Ask any partner, including DeployOpen, to confirm response expectations, release tracking and what happens when an extension lags behind the core.
