Clone an XWiki Instance
Last modified by Eleni Cojocariu on 2026/08/12 16:44
Steps
To copy an XWiki instance (the source) into a separate, independent instance (the target):
- Back up the database and the permanent directory of the source instance.
- Restore them on the target instance, excluding the xwikiid database table so that the target keeps its own instance id.
- Copy the configuration files xwiki.cfg and xwiki.properties from the source instance to the target instance.
- Review every uncommented setting of both files and replace the values that name the source's environment, such as a domain name or the address of a third-party service. Authentication settings are the exception:
- Keep the target instance's own authentication settings in xwiki.properties, instead of copying the source's.
- Re-apply the authentication settings stored on the wiki, through the Administration or on a configuration page as the OpenID Connect authenticator supports: the restore brings back the source's values, and wiki-stored settings win over xwiki.properties when both are set.
- Start the target instance and log in. If the restored authentication settings prevent that, enable the superadmin account and correct them from inside the wiki.
- Edit the XWiki.XWikiServerXwiki page and set its "Alias" property to the domain name of the target instance.
- Check whether you have configuration to review: every extension that connects to an external service, (the mail sending settings, for example, may still hold the source's values and need updating for the target's environment; if you use paid extensions, you may also need to reload their license for the target instance).
- Check the target instance in a browser: it answers on its own domain name, it serves the content of the source instance, and it still reports its own instance id.
FAQ
Can the permanent directory be left out of the copy?
No. Backup/Restore lists it among the parts that have to be backed up, because XWiki saves data there that no database table holds. Only its cache sub-directory is regenerated on its own, at the cost of a full reindex.
Why copy the configuration files at all, instead of keeping the target instance's own?
Because they also hold the settings that describe the wiki rather than the environment, and those are part of what makes the target behave like the source.
What if the target instance uses a different identity provider than the source?
Follow Preserve User Profiles When Cloning to a Different Identity Provider as well: keeping the target's authentication settings, which step 4 covers, is only half of what that case needs.
