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

PostNuke .764 -> Zikula 1.1.2 Migration Instructions

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

ADVISORY

Additions / modifications to these instructions are available online at the wiki page for PostNuke .764 -> Zikula 1.1.2 Migration Instructions.
Allthough we tried to put as much information as possible in this document, it is advised that you follow the online instructions instead, to be certain of the most accurate and up-to-date instructions for a successfull migration to Zikula.

IMPORTANT

These directions are only for migrating from PostNuke .76x to Zikula 1.1.2. Utilizing a special Migration Distribution created expressly for that purpose. If you are running a version PostNuke previous to .76x, you must upgrade to .76x first, then you can follow these instructions. You can upgrade to PostNuke .764 by downloading and installing it from The PostNuke Legacy Site.

If you are already running any version of Zikula, you need to follow the standard upgrade instructions.

Zikula continues to be developed and there might be a newer version available. If so, you should download the necessary files to upgrade to the most current version of Zikula, after installing this migration. These files can be obtained at code.zikula.org.

DOWNLOAD the Migration Distribution

Create A Test Environment

This is not an entirely painless process. This will take some time. It is best to test the process out (if possible) before doing it "for real".

Ideally you will want to leave your current site running while you test your migration. So create a test environment. You can set up a local webserver to test. Some people may choose to create a test directory right at their server. This has the advantage of working directly with the same setup as you will be using live.

When working with your on actual server, you can use the same database, if you just use a different prefix. Doing so will allow you to use the same exact configuration save the prefix. Note that copying your tables is a manual process, which you should take care of yourself.

1 Migrating From PostNuke v0.76x

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

1.1 Backup your database and files

It is vital to backup your v0.76x database and file system before proceeding with the migration. Migrations 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.

1.2 Prepare your 0.76x 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.76x

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

Note 1: For performance reasons, user permissions no longer exist in Zikula 1.0 and later. It is recommended you move any user permissions you are using to group based permissions before the migration.
Note 2: In your Settings module, verify that the start-module of your website is set to a module that also existed in the original PostNuke package (for example News, Polls or Search). After the migration process, the current start-module might not be available yet, resulting in an error. You can always set ik back after the migration process.

Once this step is complete your database is ready to be Migrated.

Finally, remove all your PostNuke v0.76x files. The file system in Zikula v1.1.2 has changed dramatically from earlier releases and this step is necessary to avoid conflicts during the migration 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 migration is completed. Once your .7x files have been removed, upload the Migration Distribution 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).

NOTE: Some hosting providers do not allow certain commands in .htaccess files on their servers. If yours does not (mostly indicated by a 500 Internal Server Error), you can safely delete the .htaccess file from your newly-uploaded directory. You should, however, replace it with an appropriate php.ini file. Contact your hosting provider for information on using php.ini to disable register_globals and magic_quotes_gpc.

1.3 Update config.php

The location of config.php has moved to the /config directory. Open up the config.php included with Zikula 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.76x 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.

1.4 Run the script

To migrate your database, open the file 'upgrade.php' in your browser (e.g. http://www.mywebsite.org/upgrade.php). (if you receive an "Internal Server Error" at this point, please see the note above about .htaccess files). You will need to know your administration username and password to proceed. Follow the onscreen instructions to complete the migration process.

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

1.5 Clean Up

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

Themes: Please note that your theme from PostNuke may not be compatible with Zikula. If you were using a Xanthia 2.0 theme with PostNuke .764, then you may be able to upgrade your theme and utilize it with Zikula. Please see the note in the standard upgrade docs about doing so. If not, you should take a look at the dozens (hundreds?) of themes available in the Themes Area of the Extensions Database.

1.6 Final Notes

Additional information about Modules that have changed, been replaced or removed is available in this wiki document.

Regards,
The Zikula Team