Upgrading an XWiki v0.9 Installation

Upgrading an XWiki v0.9 Installation

The idea behind this is to install the new version in a clean environment, copy the database to the new environment, copy your skin and make some minor adjustments. Let's rock and roll !!

Base components install

• Download the latest XWiki WAR version (the enterprise one)
• Follow the instructions in installing the XWiki WAR manually

At this point you have a clean install with an empty database, so the next steps will be to fill it with you old data and settings. It's a good idea to test your fresh and clean environment by pointing your browser to it (e.g. http://server:8080/xwiki)

Filling it with data

Now you need to make your first big choice on XWiki migration path: copy your database to the new environment, or migrate the desired pages using the Import/Export mechanism. Just to give you a clue on which one to use, the characteristics of each one are:

Regarding the Database copy:

• All pages are copied, resulting in XWiki 0.9 code inside your XWiki 1.1 installation,
• XWiki will automatically make most required adjustments to the database schema
• You will need to make some remaining adjustments to the database

Commonly, this method is used if you have a lot of custom code inside your pages, and don't want/need/like to adapt it to the new APIs. Be careful, because is strongly recommended that you adapt this code. Certainly don't delay this until long after your initial deployment in your production environment .

Regarding the Import/Export method:

• You have to add some XWiki documents (scripts) and some Java code to your v0.9 installation to support export capabilities
• You have to select, manually, which pages are migrated.
• The process is carried out at the application level

Is common practice to use this process for a cleaner migration, and when you don't have ad hoc code inside your pages. WARNING: as the time of this writing (October 22nd, 2007) there's a problem with v1.1 import feature

Database copy

• Copy the data in your old database using the proper procedures (see the Backup Guide), but take care that in each database and version could exist issues about encoding, schema incompatibilities, etc.
• Execute the next statement in your database engine : alter table xwikidoc modify column XWD_ARCHIVE mediumtext null (take a look at this bug report)
• If you are using XWiki authentication, up to XWiki 1.0 RC the passwords were stored in clear in the database. Passwords are now hashed, so, we are providing a tool to automatically hash all passwords from an existing database. WARNING: Start by backing up your wiki by doing an export or backuping your database. Then import that XAR into your wiki (be sure to be logged as an Admin) and then go to the Admin.CryptPasswords and follow the instructions there.

Export/import

BEWARE: all the steps below will be performed in your 0.9 XWiki

• Add the Export/Import utility to your v0.9 wiki (see also xwiki.js and prototype.js attachments to this page). To perform this action log-in to this site, choose to edit the page and copy/paste the code to a new page in your v0.9 XWiki
• Make a new folder inside your skins folder called expimp and copy inside it the two javascripts files attached to this page
• Add the Package capabilities to your v0.9 wiki
  • Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using jar xvf xwiki-1.1-enterprise.war
  • Look for the xwiki-core-your_version_here.jar, copy it to new folder (outside the path were our extracted the WAR file) and extract it into a new folder using the jar command as shown in the previous step
  • Change your current folder to the one were you extracted the xwki-core file and perform the command jar cvf xwiki-packaging-plugin.jar com/xpn/xwiki/plugin/packaging/Package*
  • copy the file xwiki-packaging-plugin.jar to the webapps/xwiki/WEB-INF/lib inside your 0.9 XWiki install (the one already running in your servlet container)
  • add the class com.xpn.xwiki.plugin.packaging.PackagePlugin to the entry xwiki.plugins inside webapps/xwiki/WEB-INF/xwiki.cfg config file
• Restart your 0.9 XWiki
• Export the desired pages
• Import them into your v1.1 wiki

Now you have the new XWiki core and your old data we can make a new test: you must see the old data and a new interface : perhaps not the best, perhaps it looks bad, but at this point we must assure that all data is correctly migrated to the new environment.

<textarea></textarea>