Introduction

This article treats backup, restore and upgrade not as an abstract concept, but as a verifiable runbook for XWiki with database, attachments, extensions and configuration.

Test Environment and Assumptions

The examples use neutral lab names such as wiki.example.test and xwiki01.example.test. They show real work steps but contain no production hostnames, credentials or internal paths.

  • XWiki runs behind a reverse proxy with HTTPS.
  • PostgreSQL is used as the database.
  • Attachments and XWiki state live in a persistent directory.
  • Administration is done through the XWiki UI and supplemented on the shell.

Runbook

  1. Inventory: database, permanent storage, extensions, configuration.
  2. Create a consistent backup.
  3. Restore into an isolated test instance.
  4. Validate search, attachments, permissions, mail and extensions.
  5. Upgrade only after the restore test has passed.

What Matters Most in This Part

For backup, restore and upgrade, technical state and UI behavior must match. A command can be green while users still cannot find a page, lack permissions or have unusable search.

Before the Change: Establish a Baseline

bash
curl -fsS -o /dev/null -w '%{http_code}\n' https://wiki.example.test/bin/view/Main/
systemctl is-active tomcat postgresql nginx
df -h /srv/xwiki/permanent
  1. Log in and open the menu in the upper right.
  2. Choose Administration.
  3. First review Users & Rights, Extensions, Search and Mail on the left.
  4. Then switch to the affected space and validate space permissions, pages and attachments.
  5. Finally test with a normal user, not only with the administrator.

Implementation

Run backup and restore

bash
install -d -m 0700 /backup/xwiki/$(date +%F)
systemctl stop tomcat
pg_dump -Fc -f /backup/xwiki/$(date +%F)/xwiki.dump xwiki
rsync -aHAX --numeric-ids /srv/xwiki/permanent/ /backup/xwiki/$(date +%F)/permanent/
rsync -aHAX --numeric-ids /etc/xwiki/ /backup/xwiki/$(date +%F)/etc-xwiki/
systemctl start tomcat
bash
createdb -O xwiki xwiki_restore
pg_restore -d xwiki_restore /backup/xwiki/2026-10-10/xwiki.dump
rsync -aHAX /backup/xwiki/2026-10-10/permanent/ /srv/xwiki/permanent/
systemctl restart tomcat

How Completely Did We Test?

  • Browser UI: home page, administration, space view and login.
  • Technical services: Tomcat, PostgreSQL, reverse proxy and storage.
  • Functional tests: search, attachments, permissions, mail and extensions.
  • Rollback or restore path is documented and tested once in practice.

Technical Acceptance

PASS  home page returns HTTP 200
PASS  administrator can open global administration
PASS  normal user sees only intended spaces
PASS  attachment upload and download work
PASS  search finds known page title and attachment
PASS  backup or rollback path is available

Mandatory Tests

  • Login as admin and as normal user.
  • Navigate to Administration -> Users & Rights.
  • Navigate to Administration -> Extensions.
  • Navigate to Administration -> Search.
  • Create or edit a test page with attachment.
  • Validate logout and login again.

What Does PASS Mean in This Test?

PASS does not only mean that a service is running. PASS means that the browser user path works, the technical state is plausible and a second test with restricted permissions produces the expected result.

Pitfalls

  • Admin rights are assigned globally although space permissions would be enough.
  • Attachments are not stored in the persistent directory.
  • Backups include the database but not extensions, configuration and attachments.
  • Search is not validated after restore or upgrade.
  • Screenshots or documentation contain real internal hostnames.

Final Health Check

bash
curl -fsS -o /dev/null -w '%{http_code}\n' https://wiki.example.test/bin/view/Main/
systemctl is-active tomcat postgresql nginx
journalctl -u tomcat --since -1h --no-pager | tail -n 80

Checklist

  • Public URL and admin access validated.
  • User and group model documented.
  • Database, attachments and configuration included in backup.
  • Restore or rollback test performed.
  • Search index and mail function validated.
  • No real hostnames or secrets in the public article.

Partner Runbook: Order for Your Own Environments

  1. Build lab or staging system first.
  2. Then test the XWiki UI with admin and normal user.
  3. Only then move SSO, permissions, backup and monitoring into production.
  4. Accept every change with both browser path and shell check.

FAQ

Is it enough if XWiki opens in the browser?

No. Login, permissions, search, attachments, mail and backup must also be validated.

Does every installation need SSO?

Not necessarily. In production it must be clear whether users are managed locally, through LDAP, OIDC or SAML.

Why focus so much on restore?

Because a wiki without attachments, permissions and extensions may start after an incident but is often no longer fully usable for users.

Conclusion

XWiki becomes production-ready when technical installation, UI operation, permissions, backup and operations are tested together. That combination makes the series reproducible.

Commands are only half of the work. The decisive part is documented acceptance with real user paths in XWiki. The related XWiki series is shown directly below the article.