It's crucial that you define a backup strategy for your wiki so that you don't lose any data in case of a problem with your wiki installation or in case you have issues upgrading your XWiki instance to a newer version.

There are several parts that need to be backed up:

• The database
• The XWiki WAR file
• The Permanent data (located in the XWiki permanent directory)
• Log files (optional)

Backup your database

If you've installed XWiki using your own database then you'll need a backup tool for that database to back it up and to restore it. Moreover, if you're backing up a huge amount of data, we advise that you compress the dump files to save disk space (for example with 7-zip).

• MySQL:

  Backup: mysqldump --add-drop-database --databases xwiki > xwiki.sql
  backs up the xwiki schema (use the option --all-databases instead of --databases xwiki if you want to backup the whole XWiki istance with all its subwikis).

  Warning

  It's important that the backup is done with --add-drop-database since when you restore it it's important that tables that might have been created are removed. For example database migrations can create extra tables. If you want to cancel the migration and go back to your clean dump you'll need to have those tables removed as otherwise when you run the migration again later on you might have errors.

• PostgreSQL: You can use pg_dump xwiki > xwiki.sql to backup the PostgreSQL database. In case of backing up the whole instance, use the binary pg_dumpall instead.
• Oracle: Use exp to export data.
• HSQLDB: Simply backup the HSQLDB directory. For the XWiki standalone packaging it's the data/ directory.

Backup the XWiki WAR

To be on the safe side you can and should backup the whole XWiki WAR file (that's the file that was expanded and deployed in your Servlet Container when XWiki was installed).

More specifically the WAR contains mostly static files that are not changed. However it also contains some configuration files for XWiki and you really want to backup those, as explained below.

Configuration files

There are several configuration files you'll need to backup:

• WEB-INF/hibernate.cfg.xml (Hibernate configuration)
• WEB-INF/xwiki.cfg (old XWiki configuration file but still used)
• WEB-INF/xwiki.properties (new XWiki Configuration file)
• WEB-INF/classes/logback.xml (Logging configuration)
• WEB-INF/observation/* (Cluster configuration)

To restore them simply copy them at the same location where you backed them up from.

In addition you may want to also backup any extra files you'll have installed in your XWiki installation such as JDBC drivers, extra plugins, etc.

Custom filesystem Skins

If you have a custom skin that is stored on the filesystem, make sure you backup the corresponding folder located in the webapps/xwiki/skins/ directory.

Backup Permanent Data

XWiki generates the following data:

• Wiki pages (but they're saved in the database)
• Attachments (when they're saved on the filesystem, otherwise they're saved in the database)
• Installed extensions
• Logs
• Mails that failed to be sent
• Cache files (Search index foles from Solr, Extension Cache, FOP Font Cache, etc)

It's important that you back them up.

All generated data is located in the permanent directory of XWiki. If you've installed the default standalone version of XWiki then the Permanent Directory is located in the data/ directory inside the directory where you've installed XWiki. If you have installed the XWiki WAR, you'll find this directly in the location pointed by the environment.permanentDirectory configuration property in your WEB-INF/xwiki.properties configuration file.

Backing up this Permanent Directory will backup all files generated by XWiki. Read on below for details.

Attachments

Since XWiki 3.x you can choose to store attachments on the filesystem instead of in the database. If you've configured it this way then you need to backup the Permanent Directory which is where attachments saved on the filesystem are located.

Extensions

Extensions are also saved on the filesystem in the Permanent Data Directory in an extension subdirectory.

In addition, the Extension Manager also maintains a cache/extension directory that currently only contains descriptors of core extensions. If you delete it XWiki will simply try to resolve those extensions again at startup but it won't need to resolve much since the WAR embeds complete descriptors for all the JARs (since XWiki 8.4.4). Removing this directory allows cleaning descriptors that were downloaded in previous versions of XWiki.

Solr Index Files

If you are using Solr as the default search engine you will also have to backup the Solr index which is stored by default in the Permanent Data Directory. However XWiki will regenerate this directory automatically if it's not found at startup. The Solr index files are  stored in cache/solr/search (since XWiki 12.5, they used to be in solr/ from XWiki 4.3 to 12.4).

Mails

The Mail Sender API (used by several features of XWiki that require sending mails) will serialize email messages in a mails subdirectpry inside the permanent directory before they are sent, so that if XWiki crashes or is stopped, those mails are not lost and can be resent. Once a mail is successfully sent, its associated file is removed from the mails directory.

Backup Log files

XWiki generates logs in the console by default and these will go where your Servlet container has been defined to save them. For Tomcat for example this usually goes in the TOMCAT_HOME/logs/catalina.out file.

However this is fully configurable and you may have configured XWiki to output log files elsewhere. If you want to keep those logs, don't forget to save them. Those logs are not needed by XWiki but you may want to save them to review them later on to diagnose issues that happened for example.

Using the XWiki Export feature

Since most XWiki data is saved in wiki pages one solution to backup a XWiki instance is to export all its pages using XWiki's Import/Export feature. However note that this is quite a resource hungry operation and depending on the size of your wiki you may need a lot of memory. As a consequence the recommended backup strategy is to backup the databases. It's much better to use a specialized backup tool that'll backup the database, perform incremental backups, verify backup integrity, etc.

In addition you should know that currently the following information is not located in wiki pages and is thus not saved in a wiki export:

• Activity stream data
• Statistics data
• Feed plugin data (if you use it)
• Deleted documents/attachments data
• XWiki Instance Id
• Mail Statuses

Moreover this won't save configuration data or other Permanent Data mentioned above such as installed Extensions, Lucene/SOLR index files and Logs.

In practice the Import/Export feature should be reserved for the following use cases:

• move data across XWiki instances, including sharing of applications between separate instances
• move data to another wiki
• convert from one database to another

Restore your data

• MySQL: Assuming you have your xwiki.sql file handy (obtained running mysqldump as explained above), run the following from the command line (or a script). Examples below are for the Linux shell.
  • Disable constraints check first: mysql -e "SET FOREIGN_KEY_CHECKS=0;" (restoring may fail with some cryptic error code, leaving the database in an inconsistent state, if you omit this step)
  • Delete the existing xwiki database if any: mysql -e "DROP DATABASE xwiki;" (better to start fresh)
  • Recreate the xwiki database: mysql -e "CREATE DATABASE IF NOT EXISTS xwiki DEFAULT CHARACTER SET utf8;".
  • Restore data from the dump file: mysql xwiki --user=root -p < xwiki.sql
    . Alternatively, you can omit the -p by adding a section [mysqldump] in your .my.cnf file (with a user and password line, same as for [mysql]).
  • Re-enable constraints checks: mysql -e "SET FOREIGN_KEY_CHECKS=1;"

  That is not all, now you need to restore the xwiki user rights (assuming the xwiki user exists in MySQL).

  • Update the xwiki user password from the (previously restored) hibernate configuration file
    pass=$(cat /etc/xwiki/hibernate.cfg.xml | grep passw| head -1 | sed -e 's/^.*<prop.*password">//' | sed -e 's|</property>.*||')
    mysql -e "SET PASSWORD FOR 'xwiki'@'localhost' = PASSWORD('$pass');"

  Finally, restart you container, for example in Linux: service tomcat7 restart

• PostgreSQL: psql -d xwiki -f xwiki.sql to restore your previously saved data. In full instance backup mode, use psql -d postgres -f xwiki.sql instead.
• Oracle: Use imp.

Tips in case you are using nginx

Assuming you have a nginx configuration with a server_name entry that needs updating, the following script might be useful.

Sample Backup Script