Back Up an XWiki Instance
Last modified by Eleni Cojocariu on 2026/08/20 10:08
Steps
To copy everything an XWiki instance holds into a backup you can restore later, part by part as Backup and Restore lists them:
- Stop the servlet container, so that the files are copied in a consistent state.
- Dump the database with the command of your database, and compress the dump.
- Copy the permanent directory, whose location you can read from the instance:
tar -C /var/lib/xwiki -czf permanent-directory.tar.gz --exclude=cache dataLeaving out the cache sub-directory keeps the archive small, at the price of a slower first start after the restore.
- Copy the configuration files of the web application, the part of it that XWiki does not reinstall as it was shipped:
tar -C /usr/lib/xwiki -czf configuration.tar.gz \ WEB-INF/hibernate.cfg.xml \ WEB-INF/xwiki.cfg \ WEB-INF/xwiki.properties \ WEB-INF/classes/logback.xml \ WEB-INF/observation - Copy whatever else you added around the wiki: the JDBC driver and any other jar in WEB-INF/lib, any skin under skins, and the servlet container's own configuration and TLS keystore if you changed them. Archiving the whole web application directory is the way not to forget one of them.
- Copy the log files, if you want to be able to read afterwards what the instance was doing. They go wherever the logging configuration sends them, by default the console output of the servlet container.
- Start the servlet container again.
- Check that the backup holds one file per part:
$ ls -1 /srv/backup/xwiki/2026-08-19/ configuration.tar.gz database.sql.gz permanent-directory.tar.gz webapp.tar.gz
FAQ
Can I back up a running instance?
The database dump can be taken while it runs, and on HSQLDB not even that, since its files are only complete once the instance has shut down. A permanent directory copied while XWiki writes to it can miss an attachment, so take a filesystem snapshot instead when the downtime is not acceptable.
Do I have to back up the whole web application?
No. Only the files above are not reinstalled by the distribution, so those are the ones that matter. Archiving the whole directory is simply the safest way to catch the jars and skins you added yourself.
