Export from XWiki 8 : a few tips and tricks

Help / Discuss
#1

I successfully achieved a migration from XWiki 8. I just wanted to share a few tips, in case someone else is looking to do the same thing. There are some infos on the web, but it’s scattered, and there are some pitfalls to avoid.

Some of those tricks may apply to other (rather old I guess) versions of XWiki

Don’t try to use the integrated export feature
It tends to silently fail, and to generate incomplete XAR archived, without error…

Use Large Export by Space extension
It’s very efficient. It looks unpolished, and you have to check individually every page to export (the child pages are not checked automatically), but it does the job. I exported 1500 pages (XAR archive of 4 GiB)

Adapt your Java container’s max URL size
The Large Export extension generates a long GET request. In my case it was about 70.000 chars. Java containers accept usually a limited size of URL (4 kbytes in the case of Tomcat), so you’ll have to increase that. For Tomcat, that’s the maxHttpHeaderSize parameter in server.xml. I set it to 128 kbytes (URL characters are usually among the 128 first of unicode, which are encoded on 1 byte per char).

Increase Java’s max heap space
With my default heap space of 1 GiB, the Large Export extension failed (fortunately with an explicit error, contrary to the integrated export function). Increasing the heap space to 4 GiB did the trick. Don’t forget to set it back to its original value once the export is done, too much heap space is not recommended (the GC could slow things down I believe)

So, that’s about it. Hope it helps

#2

Note that generally for an upgrade you are not really supposed to go through XAR export/import (also you are loosing some information which are not part of the XAR). This need is most of the time the result of a move to a very different database engine.

#3

1°/ What would have been the right way to do it then (not only upgrade, but install in a new host) ?

2°/ The only information that I seem to have lost during export/import is the document history. In my case that’s not an issue, it’s a personal server only used by me and some family members. But I can see how this could be an issue in a professional environment. Is there something else that’s lost in a XAR export ?

#4

See the warning in Upgrading (XWiki.org).

Document history is definitely something you can have in the XAR, maybe you made a mistake with the tool you used to export.

For XWiki 8.x the main things you loose are:

  • events (the activity stream and notifications)
  • extensions (knowing which extensions you installed in the case of XAR extension and the actual extensions in the case of JAR extensions)

In more recent versions of XWiki you would lose more things.

#5

OK thanks, good to know for a future upgrade. For now importing XAR did the trick, I set up the new server with the exact same extensions and config options as the old one.

Yes, in the more recent versions the integrated export functionality has the option to include history. But v8-4 doesn’t have that functionality. Plus the integrated export tool was unreliable (works fine in recent versions though). That’s probably why someone felt the need to write the Large Export extension back then, which I ended up using. Anyway, I wasn’t interested in history, so that’s not an issue for me.

#6

AFAIK, all versions of XWiki have history support in XAR export (and it’s the default when you use the export in admin).

#7

The information is at Backup/Restore (XWiki.org) (see also https://platform.xwiki.org/xwiki/bin/view/AdminGuide/Configuration#HConfiguringDirectories which explains what the permanent directory contains).

Thanks