Steps

The permanent directory is set either as a Java system property of the servlet container or as a property of xwiki.properties; the system property wins when both are set.

1. Stop the XWiki instance.
2. Set the directory in one of the two places:
   • As a startup parameter of the JVM of your servlet container:

     -Dxwiki.data.dir=/var/lib/xwiki/data

   • Or in xwiki/WEB-INF/xwiki.properties:

     environment.permanentDirectory=/var/lib/xwiki/data

3. Give the account that runs XWiki write access to that directory.
4. Move the content of the previous permanent directory into the new one, if the instance already had data.
5. Start the XWiki instance.
6. Read the startup log: the directory XWiki reports is the one you set.

   INFO  o.x.e.i.ServletEnvironment     - Using permanent directory [/var/lib/xwiki/data]

FAQ

What happens if I do not set it at all?

XWiki falls back to the temporary directory and logs a warning. That directory is emptied at every startup, so extensions, search indexes and filesystem attachments would be lost on each restart.

Why not keep it inside the installation directory?

Because an upgrade replaces the installation directory. A separate location keeps the data out of the way of upgrades and maintenance, which is why the Debian packages use /var/lib/xwiki/data.

Related

• Find the Current Permanent Directory
• Sub-Directories in the Permanent Directory
• Temporary Directory