Instance Cloning
Explanation
Cloning means making a full, independent copy of an XWiki instance. A common case is copying a live instance to a separate environment to test changes safely before they go live, but the same steps apply any time you need an independent copy, whatever you call the two instances.
The base procedure is the same as a Back Up and Restore (copy the database and the permanent directory from the source instance to the target instance). However, cloning also requires updating a few instance- and environment-specific settings. Simply copying everything as-is would cause the cloned instance to behave like the original rather than as an independent instance.
The instance id
Each XWiki instance has its own id, stored as the only row in the xwikiid database table. There are multiple methods of getting the instance Id if needed. The target instance must keep its own id, not inherit the source's, so exclude the xwikiid table when restoring the database. XWiki instances using non-bundled paid extensions licenses are tied to the instance id. Since the id isn't copied, the target instance needs to reload its licenses after the restore, see Clone an XWiki Instance.
Configuration and settings
Settings in xwiki.cfg, xwiki.properties, and the XWiki Administration (e.g., mail sending, and any extension that connects to an external service) often contain values specific to one environment, a domain name, or a third-party service address. A backup/restore doesn't adjust these automatically, so review and update them on the target instance. The XWiki server's domain name is stored on the wiki itself, in the Alias property of the XWiki.XWikiServerXwiki page. It's restored unchanged with the rest of the database, so set it to the target instance's own domain afterwards.
Authentication
Authentication needs extra care in one case: when the target instance must use a different identity provider (or a different client configuration of the same provider) than the source. In that case, existing user profiles no longer match after cloning, because the login system can't recognize them. This has its own procedure: Preserve User Profiles When Cloning to a Different Identity Provider. If authentication settings block login right after cloning, use the superadmin account as a fallback to fix the configuration from inside the wiki.
FAQ
Why exclude xwikiid instead of just copying everything?
Because it identifies one specific instance. Copying it would make the clone share an identity with the source instead of being independent.
Do I need the identity-provider procedure if both instances use the same provider?
No. Preserve User Profiles When Cloning to a Different Identity Provider only applies when the target instance's identity provider or client configuration is different from the source's.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
