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

Zikula Upgrade Instructions

More detailed documentation is available in the Documentation Wiki at http://community.zikula.org. Support and help with upgrading to Zikula v1.1.1 can be obtained from the forums.

Contents

1 Warning

Your PostNuke installation must already be upgraded to PostNuke 0.764 or greater before attempting to upgrade to Zikula v1.1. Upgrades from earlier releases are not supported. Please also be aware that the 0.7x PostNuke series will cease to be supported by the Zikula team on 1st July 2009.

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 Upgrading From PostNuke v0.764

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.

3.1 Backup your database and files

It is vital to backup your v0.7x 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.

3.2 Prepare your 0.7x installation

Login to your PostNuke site with an administrator account and ensure each of the modules listed below are installed and activated. All are included in 0.764 - remember only upgrades to Zikula v1.1 from this release or later are supported.

  1. Admin
  2. Admin_Messages
  3. Blocks
  4. Groups
  5. Header_Footer
  6. legal
  7. Mailer
  8. Permissions
  9. pnRender
  10. Search
  11. Settings
  12. User
  13. Xanthia

Other modules are optional as the core of Zikula v1 is slimmed down to remove non compulsory modules. You can upgrade these separately by downloading the ValueAddons pack distributed at the NOC, or by using the special upgrade distribution which is available at the core downloads section. Once this step is complete your database is ready to be upgraded.

Finally, remove all your PostNuke v0.7x files. The file system in Zikula v1 has changed dramatically from earlier releases and this step is necessary to avoid conflicts during the upgrade process. It is suggested you remove all your files to a backup directory and then copy back the files (such as third party modules, themes and downloads, images, and so on) you need once the upgrade is completed. Once your .7x files have been removed, upload the v1.1.1 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).

3.3 Update config.php

The location of config.php has moved to the /config directory. Open up the config.php included with Zikula v1.1 and add in your database information to the following lines:

$PNConfig['System']['prefix']
$PNConfig['DBInfo']['default']['dbuname']
$PNConfig['DBInfo']['default']['dbpass']
$PNConfig['DBInfo']['default']['dbname']

If you copy the encoded values from your 0.764 config.php be sure to set
$PNConfig['DBInfo']['default']['encoded'] = 1;

Additionally edit the following line:
$PNConfig['System']['installed'] = 1;

In some cases it may also be necessary to edit your database type, table, and host if you are not using the default types.

3.4 Run the upgrade

To upgrade your database, visit the file upgrade.php in your browser. You will need to know your administration username and password to proceed. Follow the onscreen instructions to complete the upgrade process.

Note: Zikula v1.1 removes the footer message from the admin interface, so your footer message will disappear after the upgrade. We recommend hard coding your footer in your theme's template files. For reference, the upgrade process stores a copy of your old footer in the pnTemp directory for easy retrieval.

Note: For performance reasons, user permissions no longer exist in Zikula 1.1 and later. It is recommended you move any user permissions you are using to group based permissions before the upgrade.

3.5 Clean Up

Lastly, remove upgrade.php, install.php and the install directory from your file system.

4 Upgrade 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

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. Upload all files from the package you downloaded, but not the config folder! Uploading this with overwrite your config.php and trash your configuration! Also make sure that you delete the modules/Members_List/ and the system/Profile folder, both are now integrated in the new Profile module which now resides in modules/.

4.3 Run the upgrade

Run the upgrade script 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 module MailUsers - go to the Modules administraton, deinstall it and remove the files from the filesystem (found in modules/MailUsers),
  2. the module Members_List if you haven't done this before already - go to the Modules administraton, deinstall it and remove the files from the filesystem (found in modules/Members_List),
  3. the folder system/Profile if you haven't done this before already - DO NOT REMOVE THE FOLDER modules/Profile!
  4. the folder includes/pnobjlib - the files contained there have been moved to the includes folder itself,
  5. 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.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 (available from the Extensions database)
  2. messaging: InterCom 2.1

MyProfile will become an alternative in the future.

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

5 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.

6 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!

7 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 http://community.zikula.org.

Regards,
The Zikula Team