Tutorial

To upgrade your XWiki instance to a newer version using the ZIP package:

1. Backup the configuration files, the permananet data (i.e. the /data directory), the HSQLDB database is already included in the /data directory, the log files (optional).
2. Check the Release Notes.
   • Review the release notes for the versions between your current version and the target version. 
   • Pay special attention to sections titled "Issues specific to XWiki <version>" and to any changes in hardware of software requirements (prerequisites).
3. Download the new version just as you had installed the standalone (demo) distribution.
4. Stop the XWiki instance to prevent file corruption and database inconsistencies.
5. Install the new version in a different directory than the old one. Keep both the old and the new installations.
6. Merge the Configuration files:
   • If you have never modified the configuration files, you don’t need to copy the old configuration files to the new installation. Just keep the new configuration files and proceed with the other steps.
   • If you have customized the old configuration files:
     • Do NOT copy the old configuration files directly to the new installation. The new XWiki version may have introduced new configuration options, and overwriting the files completely could cause you to lose those options.
     • Ideally, manually merge the old configuration files with the new ones: Compare the old and new configuration files, keep your custom settings, and add any new settings or changes from the new files.
7. Copy the Permanent data directory (the data directory) from the old XWiki to the new XWiki instance.

8. Ensure the xwiki.cfg file is configured correctly to allow the system to automatically upgrade the database schema. More specifically, find the section # Data migrations and schema updates, and verify the following migration setting is enabled (uncommented):

   xwiki.store.migration=1

9. Start the new instance to test and verify that the upgrade was successful and the new version is running correctly. 

After upgrading the Distribution, the next step is to upgarde the flavor.

FAQ

How to do the merge of the files on Unix operating systems ?

If you're on a Unix system check some commands that may help you doing the merge instead of doing it fully manually.

What if the migration of the database fails?

If the migration process fails, drop the tables: DATABASECHANGELOG and  DATABASECHANGELOGLOCK from your database and then restart the migration. This should allow the migration to proceed without further issues.

More

To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.