Upgrading Zikula

NOTE: THIS DOCUMENT CONTAINS IMPORTANT INFORMATION ABOUT ZIKULA. PLEASE READ ALL OF IT BEFORE CONTINUING.

If you do have not and installation of Zikula already on this server, you need to follow the regular installation instructions.

Zikula Upgrade Instructions

More detailed documentation is available in the Documentation Wiki at the Central Community. Support and help with upgrading to Zikula can be obtained from the Community Forums.

Contents

• 1. Warning
• 2. Server Considerations
• 3. Migrating From PostNuke 0.764
• 4. Upgrading From Zikula 1.0.x
• 5. Patching From Zikula 1.1.x
• 6. Caution
• 7. Upgrading Themes
• 8. Final Note

1. Warning

Your PostNuke installation must already be upgraded to PostNuke 0.764 or greater before attempting to upgrade to Zikula. Upgrades from earlier releases are not supported. Please also be aware that the 0.7x PostNuke series is no longer supported.

2. Server Consideration

Before you begin your upgrade, there are some requirements and guidelines you should consider to make upgrading, installing, running, and securing Zikula easier. Please read the Zikula software condsiderations document.

3. Migrating From PostNuke 0.764

PostNuke is no longer supported. Please see the migrate from 764 instructions for more information.

4. Upgrading From Zikula 1.0.x

Please follow the steps below in order, and read each in detail before proceeding. Providing the instructions are followed exactly, the upgrade should proceed with no problems.

• 4.1 Backup your database and files
• 4.2 Prepare your 1.0.x installation
• 4.3 Run the upgrade
• 4.4 Clean up and additional configuration

4.1 Backup your database and files

It is vital to backup your 1.0.x database and file system before proceeding with the upgrade. Upgrades cannot be rolled back, therefore the only solution is to restore from backup if problems occur. To backup your database, try using a tool such as mysqldumper, phpMyAdmin or alternately use SSH or your hosting control panel. Full instructions and tutorials on database backups can be found by searching the web and the documentation of your tool set.

4.2 Prepare your 1.0.x installation

Login to your Zikula site with an administrator account. If you want, you can disable your site during the upgrade by changing the configuration in index.php?module=Settings&type=admin. After that go to your modules administration to disable and remove the Members_List module.

Remove all your Zikula 1.0.x files, and again make sure you have a backup of the files, especially the config/ directory. The file system in Zikula v1.1 has changed from Zikula v1.0.x, and this step is necessary to avoid conflicts during the upgrade process. It is suggested you move all your files to a backup directory and then copy restore the files (such as third party modules, themes and downloads, images, and so on) you need once the upgrade is completed. Once your 1.0.x files have been removed, upload the latest Zikula files to your web space in their place. As you have uploaded a fresh pnTemp directory, ensure it, and all its subdirectories are writable (chmod -R 777).

Upload all files from the package you downloaded. Afterwards, you can replace the config-directory from the new package with the config directory of your previous installation. This way, your configuration is automatically included, and your installation is ready for upgrading.

4.3 Run the upgrade

Run the upgrade script `upgrade10xto11x.php` (e.g. http://www.mywebsite.org/upgrade10xto11x.php) and follow the steps as described. There is no real interaction needed other than clicking on 'next'. All database changes that are necessary will be done automatically. At the end you will be redirected to your admin panel.

4.4 Clean up and additional configuration

After a successful upgrade you have to remove

1. the install folder and the files install.php, upgrade.php and upgrade10xto11x.php from the root folder of your site.

If you have a menublock pointing to the old Members_List module you have to change the link to point to index.php?module=Profile&func=viewmembers. The permissions may have to be changed to the component 'Profile:Members:'.

Zikula 1.1 allows you to configure your favorite profile and messaging module so you should visit the systems settings and check if the upgrade script selected the correct module. We don't know your personal taste, so its better to have a look at this now.

as the time of writing this document the following modules support this technique:

1. profile: the known Profile module
2. profile: myProfile
3. messaging: InterCom 2.1

If you disabled your site before starting the upgrade (see 4.2) you should re-enable it now.

5. Upgrade From Zikula 1.1.x using a patch

Bug-fix upgrades of this type do not require running an upgrade script. Typically, a patch distribution is released exactly for this purpose. Please follow the steps below in order, and read each in detail before proceeding. Providing the instructions are followed exactly, the upgrade should proceed with no problems.

• 5.1 Backup your database and files
• 5.2 Copy the patch files
• 5.3 Additional configuration

5.1 Backup your database and files

For security reasons, you should always backup your files and database. If an upgrade fails, the only way to quickly get your site up and running again is by restoring your backup. To backup your database, try using a tool such as mysqldumper, phpMyAdmin or alternately use SSH or your hosting control panel. Full instructions and tutorials on database backups can be found by searching the web and the documentation of your tool set.

5.2 Copy the patch files

Upload all files from the patch-file you downloaded. Make sure that you do not overwrite your config/config.php file.

5.3 Additional configuration

Check your Administration panel to confirm that the latest Zikula version is active. Afterwards, open your Modules Administration and regenerate the modules list. Some modules might need an upgrade, so you can finish your upgrade by executing these steps.

6. Caution

Before the PostNuke series API was stabilized, it was common for the core database tables to be modified by third party extensions through adding fields, changing names, etc. It should be noted that Zikula does not support any modification of the core code or data structure. Zikula v1 has been designed to be flexible enough to avoid any need to modify the core, but if you find something missing that you believe could be of widespread use, please submit a feature request to the feature request tracker at code.zikula.org/core.

7. Upgrading Themes

Zikula v1 has reconfigured the theme structure for the new theme module, now simply called Themes (Xanthia version 3). If you are using a Xanthia 2 theme, Zikula v1 comes with an upgrade option. To use this tool make your themes directory writeable (chmod -R 777). Go to your Themes Module Administration and click the 'upgrade' option. Please note this is a tool, not the definitive upgrade script. For most Xanthia themes it should work fine, however for more complex themes, it may not completely upgrade your theme. You may have to edit parts of your theme manually. For non-Xanthia (e.g. AutoTheme) themes please consult your theme engine provider. Once you have finished upgrading your themes, ensure you make your theme directory read only again!

8. Final Note

Congratulations! Your upgrade is complete. We hope you enjoy using this new Zikula version. If you have any comments, please use the feedback forum on community.zikula.org.

Regards,
The Zikula Team