Instance Cloning
Explanation
Cloning an XWiki instance means making a full, independent copy of it: an instance that serves the same content while keeping its own identity. A common case is copying a live instance into a preproduction environment, to test changes before they go live.
The base procedure is a Backup/Restore of the database and the permanent directory, which together hold everything the instance contains. What that copy cannot do on its own is tell apart what belongs to the wiki from what identifies this instance in this environment. Left as restored, the target instance claims the source's identity, its domain name and its connections to external services. Clone an XWiki Instance covers both halves.
The Instance Id
Every instance has an id of its own, stored as the single row of the xwikiid database table. Restoring that row would hand the source's identity to the target, so the table is left out of the restore.
Licenses for paid extensions are issued against an instance id, which is why the ones restored with the database do not apply to the target: it reloads its own from the store instead.
Environment-Specific Settings
A domain name, a mail server, the address of a third-party service: these describe the environment rather than the wiki, and they live in two places that behave differently when cloning.
xwiki.cfg and xwiki.properties are configuration files, so no database restore touches them. They have to be copied from the source and then reviewed, because any of their uncommented settings may name the source's environment.
Everything else is in the database and comes back holding the source's values: the "Alias" property of the XWiki.XWikiServerXwiki page, which is the domain name the wiki answers on, the mail sending settings, and the settings of every extension that connects to an external service.
User Profiles and External Identities
XWiki stores user profiles as pages. When an external identity provider authenticates a user, the wiki keeps a mirror profile for them — created on their first login, or by a synchronization — and records the identity that profile was matched with. The OpenID Connect authenticator records two values: the issuer, which is the provider's URL and is the same on every profile, and the subject, which identifies that one user at that provider. Later logins find the profile again by looking for that exact pair, never by user name.
Cloning copies those profiles together with the identities recorded on them, which is what you want as long as both instances authenticate against the same provider with the same client configuration. When the target instance uses a different one, the identity a returning user arrives with matches nothing and the wiki creates a second, empty profile for them. Giving the target its own authentication settings is not enough to avoid that, hence Preserve User Profiles When Cloning to a Different Identity Provider.
FAQ
Should hibernate.cfg.xml be copied from the source as well?
No. It holds the database connection of the instance it belongs to, so copying it would point the target instance at the source's database.
What if the target instance's own id is lost during the restore?
XWiki generates a new one on the next start and stores it, so the instance keeps working — but it is no longer the instance its licenses were issued against.
Can a XAR export of every page replace the database dump?
No. Some data is not stored in wiki pages and is therefore absent from an export in XAR format: the instance id, the event stream, the statistics, the deleted documents and attachments, and the mail statuses.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
