From RNWiki
Revision as of 16:26, 11 September 2009 by Fkelly (talk | contribs) (From Prior Versions of RavenNuke™)
Jump to: navigation, search

Home>Upgrades and Migrations

Upgrading...

You can ignore this page if this is a brand new RavenNuke™ installation. If you are upgrading from a previous RavenNuke™ installation to the latest version, review the guidelines under the sub-heading of From Prior Versions of RavenNuke™. If you are migrating from a previous non-RavenNuke™ installation to RavenNuke™, review the guidelines under the sub-heading of From Other Versions of PHP-Nuke.


From Prior Versions of RavenNuke™

These instructions are for upgrading from a version greater than or equal to 2.02.00 of RavenNuke™ to the latest 2.40 version ONLY. If you are on a version earlier than 2.02.00, use the various patch downloads and/or support forum posts to help you get to 2.02.00, or better, FIRST. Once you are on version 2.02.00 (or greater) AND you have validated that everything is working properly (do NOT skip this step), you are ready to upgrade. Read ALL steps first to get the complete "picture" of what needs to be done and when.

  1. Backup Current Installation FIRST! - This step is always the most crucial. You need to have a clean restore point (files and database) in case something goes wrong. We also recommend that you "test drive" this upgrade process on a local PC or server setup so you get a better feel for the process and have time to resolve any specific issues that your installation might throw your way. There are so many different ways in use today for backing up your site files and database, so the "how" will not be discussed in these instructions. Do NOT ignore this ALL important step (or any others for that matter). You have been warned!
  2. Note Impacts to Your Add-Ons / Hacks - You should be doing this anyways as you make changes to your site. Make sure you understand the impacts to your add-ons and any files that you have "hacked" since your original RavenNuke™ installation. Look especially for modified core RavenNuke™ tables or modified core script files. You will have to analyze these yourself and ensure that you do not overwrite your changes or somehow get your database out-of-sync with your script files. This is where a good set of change management notes and a good version comparison tool will save the day. Any table that was added new, or new script file that was added, will NOT be impacted by this upgrade, unless somehow, they use the same name.
  3. Extract, Prepare and Upload Files - Here is where you might want to refresh your memory on the steps you took for the full original installation (review the steps of this manual again) so that you take care not to overwrite critical files such as config.php, .htaccess, .staccess, .ftaccess, etc. which you have already configured. The files config.php and rnconfig.php have been modified heavily, so it is recommended that you save off your current version of these and replace them with the ones from the 2.40 distribution, then make sure config.php has the right database connectivity and rnconfig.php has appropriate other settings for your situation. Much has changed in the area of configurability, so please take some time to review the steps mentioned in this manual related to a complete new installation (especially the section on Prepare/Install the Files). The configuration instructions will NOT be repeated here. NOTE: If you normally experience difficulties FTP'ng large quantities of files to your server, and if you have a means of decompressing files on the server, you might want to consider compressing the distribution (zip or tar.gz) and ftp'ng the compressed distribution as a single file and then decompressing it there.
    With the 2.30.00 release, the FCKeditor 2.6.3 changed significantly to where the old directory structure will no longer work. Ravennuke 2.4 uses FCKeditor 2.6.4. If you are upgrading from a version below 2.30.00 and you customized the FCKeditor settings, including custom tool bars, in fckconfig.js OR uploaded files (e.g. images) using the FCKeditor file manager, BEFORE UPLOADING the RavenNuke™ files from the distribution you need to do the following:

    Remove / delete the includes/FCKeditor/editor directory. WARNING: Do NOT delete the includes/FCKeditor/uploads directory if you have uploaded images or other files via the FCKeditor file manager and / or are referencing files there in your content. To save custom configuration changes, save or rename includes/FCKeditor/fckconfig.js (on some operating systems, e.g. Windows, directory and file names are not case sensitive, so unless the file is renamed, it will be overwritten).
    After uploading, the RavenNuke distribution:
    Compare the original includes/FCKeditor/fckconfig.js to the new includes/fckeditor/fckconfig.js to update the new file with necessary changes.

  4. Upgrade Core RavenNuke™ Tables - From your browser, type http://www.YOURDOMAIN.com/INSTALLATION/rndb_upgrade.php. This will upgrade your core RavenNuke™ tables (we'll get to NukeSentinel™ next) from 2.02.00 and greater to 2.40. It will ONLY touch the core tables and will not affect any tables that you have added as completely new. However, if you have previously made changes to these core tables, there is no guarantee that this upgrade to 2.40 will work properly. When you run this upgrade script, output will be written to your screen. We highly recommend that you copy and paste this output into your favorite text editor and save it with your other conversion notes. Depending on your personal preference, you may also wish to print it and save it in your conversion notebook. Having a record of the changes that were made, as well as any errors or exceptions, can be invaluable if problems occur at a later time or if you need to post something in Forums asking for help.
    NOTE: There was a fix posted in the Post 02.02.02 Fixes support forum regarding two missing user table fields. If you have already applied the fix from that thread, you will receive two legitimate errors that you can just ignore:
    ALTER TABLE nuke_users ADD `user_login_tries` smallint(5) unsigned NOT NULL default '0' AFTER `last_ip`; FAILED. MySQL reported: Duplicate column name 'user_login_tries'
    ALTER TABLE nuke_users ADD `user_last_login_try` int(11) NOT NULL default '0' AFTER `user_login_tries`; FAILED. MySQL reported: Duplicate column name 'user_last_login_try'
    If you receive any other errors, most likely you have made modifications to an existing core RavenNuke™ table and missed it in your analysis in Step 2. You will need to analyze the errors and determine how to correct (might require script changes too). However, it is quite possible that even with errors, RavenNuke™ will still operate just fine.
  5. Upgrade NukeSentinel™ Tables - From your browser, type http://www.YOURDOMAIN.com/INSTALLATION/rndb_upgrade_nukesentinel.php (or click the provided link that the previous upgrade script gives you at the bottom when it is done). This will upgrade your NukeSentinel™ tables to version 2.6.03. If you have already upgraded your NukeSentinel™ to this version or higher, you may skip this step. The same comment from the previous step, with regards to saving the output, applies here as well.
    It is entirely possible with this upgrade to have some index related error messages, or possibly a field that already exists or is not there to drop. You can ignore these. However, if the script stops with a message that your version number for NukeSentinel™ is not recognized (it will display a list of "recognized" versions), you will need to re-do your NukeSentinel™ installation using the latest FULL package from the NukeSentinel™ web site.
    You may want to review your blocker settings and strings list just to make sure they are what you desire.
  6. Upgrade IP2Country Tables - The IP2country tables are now incorporated into Ravennuke and supported by the Ravennuke team. We recommend that you run the IP2country portion of installSQL.php to reload your ip2country table from scratch. Be careful to just run this one portion of installSQL.php since running the core tables part of this program will erase all your old data!
  7. Add-Ons - There are several add-ons included within RavenNuke™ that are considered core to the package (see the Additional Add-Ons page for version numbers supplied with this distribution). Some were added with 2.10.00, 2.20.01 and 2.30.00. The upgrade script will take care of adding most of the tables for you if they do not already exist.
    CHMOD the /cache, /uploads, modules/Forums/files, and modules/Forums/images/avatars directories to 777 or 755 (if using suexec) or 644 or 640 (if using suexec). These directories are used to hold cache files for SimplePie, which is used by nukePIE™ to display feeds from other sites in blocks, and other files such as those uploaded with the nukeWYSIWYG editor and/or the forum attachments mod.
    If you already have a version of any of these add-ons that is greater than what is provided within this distribution, you must take care not to overwrite its files. It might actually be best to wait for new versions to come in new RavenNuke™ release packs.
    If you are on previous versions of the HTML Newsletter (below 1.3.x) and/or GCalendar (below 1.7.0) modules, you will need to run their respective installers found under the AddOnFiles directory. You will need to copy over their install files into your the root of your RavenNuke™ in order to run these.
  8. Remove the INSTALLATION Directory - This directory should NOT be retained on the system. Someone can very easily wipe out your entire database in one shot if you do so. It is best to REMOVE this directory entirely from your system. (You can always get it back later from the distribution.) If you had saved off your rndb_upgrade.* output to this directory, you will want to save that off somewhere as you do not want to lose it.
  9. Additional Add-Ons and Configurations - Again, cannot stress enough about reading through the rest of this manual to make sure you have configured everything. There is also a section on Additional Add-Ons that is a must read in order to get some of the add-ons, such as the HTML Newsletter, to operate properly.
  10. Banner Clients Migration! - The old Banner Clients module was replaced by the higher PHP-Nuke Advertising Client system with version 2.10.00. The upgrade scripts have NOT touched your old data, but you may have to edit some of the Advertising modules data and/or convert over your clients if you were coming from a version before 2.10.00.
  11. Clean-Up Unused Files - It is also suggested that you compare the core RavenNuke™ script files / directories and remove any files that are no longer needed. Using a good version comparison tool that can give you diffs on directories too, compare your final upgraded installation to the RavenNuke™ distribution and analyze any differences (as some may be legitimate - such as add-on modules/blocks). Leaving obsolete script files on the server could present a security hole. There is ONE exception to this. Leave the files in the abuse folder alone. To help you locate redundant files we have included a small script in the UtilityFiles/File_Compare directory.
  12. Test, Test, Test! - Do NOT skip this part! Whether migrations are easy or complex, YOU should always test your final migrated system thoroughly. You never know what might be lurking underneath. You do not want your end-users / customers to find these for you. :wink:
  13. Final NOTE - Just remember: many have come before you and many will come after you on this same "journey". It IS possible to perform this upgrade, and many of already done it, but just make sure you are prepared to see it through to the end. We ALWAYS recommend that you take a copy of your production database over to a local test environment and run through these steps and test thoroughly FIRST! Also, once you are ready to do this on your production web site, take a complete database backup as well as a backup of all your files BEFORE doing anything! If you are using NukeSentinel™ (and why would you not? LOL), you might even want to disable your site for the duration of the migration and final test out.

GOOD LUCK!!

From Other Versions of PHP-Nuke

These instructions are for migrating from a non-RavenNuke™ version of PHP-Nuke to the latest RavenNuke™. Given the shear number of variations in use today, it is impossible to write one set of specific instructions that will cover everyone's needs. Therefore, what follows is a very simple, high-level set of guidelines to help you approach this task. Read ALL steps first to get the complete "picture" of what needs to be done and when. Bear in mind, however, that these are only guidelines and one suggested approach.

  1. Backup Current Installation FIRST! - This step is always the most crucial. You need to have a clean restore point (files and database) in case something goes wrong. We also recommend that you "test drive" this migration process on a local PC or server setup so you get a better feel for the process and have time to resolve any specific issues that your installation might throw your way. There are so many different ways in use today for backing up your site files and database, so the "how" will not be discussed in these instructions.
  2. Determine PHP-Nuke Version - The most important thing to remember is that RavenNuke™ is PHP-Nuke 7.6 at its core. You must therefore find out what version you are running in order to plan out the proper migration.
  3. Determine BBtoNuke (phpBB - Forums) Version - This one is easier to determine. Go to the Administration Control Panel of PHP-Nuke and then "Forums". On this page, find where it says "Version Information". The latest version is 2.0.23 as of this writing, which is what RavenNuke™ is using.
  4. Upgrade or Downgrade Database - If you find in Step 1 that your PHP-Nuke version is less than 7.6, then you need to UPGRADE your database to the core 7.6 version. If you find that your PHP-Nuke version is greater than 7.6, you will need to DOWNGRADE your database to the core 7.6 version.
    • How Do I Determine my PHP-Nuke Version? Try Raven's Nuke Version Number Admin Add-On or using phpMyAdmin, view the field "version" in the nuke_config table. The absolute best way to determine what you have is through keeping good notes on what you installed and when :wink:.
    • How Can I Downgrade my Database? - For versions 7.7 - 7.8, you could use the downgrader tool from NukeScripts. NOTE: this may also work for 7.9 and 8.0, but has not been tested as such as far as we know (at this writing). For 7.9 and above (actually, almost any version of PHP-Nuke to RavenNuke™), see this thread from Gremmie on using mySQLDiff and BigDump to get this done. NOTE: if you use the mySQLDiff approach and have it modify your table structure, you can skip past the "Apply RavenNuke™ Core Database Changes" step.
    • How Can I Upgrade my Database? - For versions less than 7.6, the individual upgrade scripts can be found within the RavenNuke™ distribution here: UtilityFiles/nuke_upgrades.zip . You will have to execute each in succession starting from your current version up to 7.6.
  5. Upgrade BBtoNuke (phpBB - Forums) Version - The individual BBtoNuke upgrade scripts can be found within the RavenNuke™ distribution here: UtilityFiles/bbtonuke_upgrades.zip. You will have to execute each in succession starting from your current version up to 2.0.22.
  6. Apply RavenNuke™ Core Database Changes - As of this version, there are four sets of primary code database changes: 1) Resend Email Hack, 2) NSN Groups, 3) HTML Newsletter, and 4) GCalendar. Each of these has a separate SQL file or installer if you need to upgrade/update. Each of these are discussed in its own topic below:
    • Resend Email Hack - If you already are using this hack, you should not have to do anything here. However, if you do not have it already, you will need to use phpMyAdmin to execute the SQL found in file INSTALLATION/sql/includedInCore/rn_resendemail.sql. This will alter the nuke_users_temp table.
    • NSN Groups - If you already have NSN Groups installed in your original database, you should not have to do anything here as long as the table structure is the same as the 1.7.1 release. However, if you do not have it already, you will need to use phpMyAdmin to execute the SQL found in file INSTALLATION/sql/includedInCore/rn_nsngroups.sql. If your current installation has NSN Groups and it is not compatible table structure-wise with 1.7.1, then you may need to treat this as a fresh install using the file just mentioned, and then manually re-do your groups and assignment of users to groups (so you may wish to note both your groups and user-to-group assignments before executing the SQL in that sql file).
    • HTML Newsletter - If you already are using a version of the HTML Newsletter (from Montego Scripts) that is below 1.3.x, then you will need to use the HTML Newsletter installer. You can find this within the RavenNuke™ distribution here: AddOnFiles/HTML_Newsletter (read the README.txt and following the instructions). If you do NOT already have the HTML Newsletter installed, simply apply ONLY (!!!) respective step of the installSQL.php script. This will add the necessary HTML Newsletter tables.
    • GCalendar - If you already are using a version of GCalendar (from GCalendar Support) that is below 1.7.0, then you will need to use the GCalendar installer. You can find this within the RavenNuke™ distribution here: AddOnFiles/GCalendar/html (simply copy over the gcal_install.php to your root and point your browser to it). If you do not already have GCalendar installed, you can also install the tables from this installer.
    • Forum Attachment Mod - If you already are using a version of this mod, you will have to compare your bb* tables to the file in INSTALLATION/sql/includedInCore/rn_forum_attach_mod.sql. Otherwise, use phpMyAdmin to execute the SQL found in that file to add the needed tables as well as modify your core phpBB tables to support this mod.
    • TegoNuke(tm) Mailer - All you have to do is click on the TegoNuke™ Mailer link within the RavenNuke™ Administration Control Panel and if the tables are missing, they will be added. If you already have a version of any of these add-ons that is greater than what is provided within this distribution, you must take care not to overwrite its files.
  7. What to Do About NukeSentinel™? - There are two schools of thought. It really depends upon whether you want to retain all your current blocked IPs, string and harvester blocker data, etc. If you do not mind starting over fresh, you may simply execute the NukeSentinel™ steps of the installSQL.php script and then re-configure the new version. The other option depends upon whether you decide to upgrade "In-Place" or "Move Data" (see next item); use the latest separate NukeSentinel™ installer found on the NukeScripts web site to bring your current version up to date.
  8. Upgrade Database "In-Place" or Move Data - There are two methods for which to migrate a database to RavenNuke™: 1) migrate "in-place", or 2) migrate a copy of the database and then move the data into an empty RavenNuke™ "shell".
    • Migrate "In-Place" - This method involves taking an existing database, with all its data intact, and performing the above mentioned upgrades. Once the database upgrades are done and the script files are overwritten, everything should work.
    • Migrate Database Structure, then Move Data - This method involves taking an existing database, perform the above mentioned upgrades, create a new RavenNuke™ database (an "empty shell" so to speak) and then move the data over. You could use phpMyAdmin to "Export" the Data ONLY (i.e., NO Structure) and then analyze each failure on the INSERTs and manually determine how to get the data in. For help in creating a new RavenNuke™ database, please see the rest of the steps in this HowToInstall manual under Installation and Configuration. Each of these methods have their pros and cons, and there may even be other alternatives. Since there are so many different possible combinations of PHP-Nuke versions, hacks, add-ons, etc., there may still be a few minor issues / differences that you are going to have to analyze and fix.
  9. Remove the INSTALLATION Directory - This directory should NOT be retained on the system. Someone can very easily wipe out your entire database in one shot if you do so. It is best to REMOVE this directory entirely from your system. (You can always get it back later from the distribution.)
  10. Overwrite Script Files - Once the database has been migrated, then the script files need to be overwritten with the ones from the RavenNuke™ distribution (with some exceptions - read on). For the most part, if you have NOT made any modifications to your existing same files (yeah, right, who doesn't?) AND you do not have higher versions of the provided add-ons and NukeSentinel™ then you can simply overwrite. HOWEVER, for files such as config.php, .htaccess, .staccess, .ftaccess and possibly others (like some blocks and modules) which have embedded configuration options, YOU will need to analyze the differences yourself PRIOR to overwriting. The more hacks you have made, the more complex your job becomes. Using a good file comparison utility such as Beyond Compare 2 or Winmerge (free from SourceForge) will be essential for you. NOTE: If you normally experience difficulties FTP'ng large quantities of files to your server, and if you have a means of decompressing files on the server, you might want to consider compressing the distribution (zip or tar.gz) and ftp'ng the compressed distribution as a single file and then decompressing it there.
  11. What About Existing Add-On Blocks and Modules? - It depends! The new RavenNuke™ installer for version 2.10.00 and up no longer drops ALL tables; it only drops and re-creates the tables that are part of core nuke (with the few exceptions already noted above). Therefore, if your add-on blocks / modules are completely independent of the core PHP-Nuke tables and would normally work on PHP-Nuke 7.6 and the 3.3 patches from Chatserv, then there is a high probability that they will work with RavenNuke™. Sometimes, even older modules / blocks require only a few minor code "tweaks" to make them work. Many of these have already been brought up and discussed in the [support.html support forums]. If any given block / module is highly dependent upon the core PHP-Nuke database structure (one example might be one which inserts or updates the nuke_users_temp table), then you will need to rationalize the differences and analyze what code "tweaks" are needed.
  12. Clean-Up Unused Files - It is also suggested that you compare the core RavenNuke™ script files / directories and remove any files that are no longer needed. Unfortunately, since we do not know which version you are migrating from, it is next to impossible for us to tell you which files to remove. We have included a small script in the UtilityFiles/File_Compare/ directory to help you but we recommend you still compare your final migrated installation to the RavenNuke™ distribution and analyze any differences (as some may be legitimate - such as add-on modules/blocks). Leaving obsolete script files on the server could present a security hole.
  13. Test, Test, Test! - Do NOT skip this part! Whether migrations are easy or complex, YOU should always test your final migrated system thoroughly. You never know what might be lurking underneath. You do not want your end-users / customers to find these for you. :wink:
  14. Reminder on File Permissions - Just a quick reminder that once fully configured, only .htaccess and .ftaccess should have permissions of 666. The .staccess file may be set to 644 as an additional security caution, HOWEVER, if you add a new admin, you must change it back to 666 long enough to re-write the file with the encrypted passwords. (You would only have these files if you are using NukeSentinel™'s Admin Auth.) All other files should be 644 or less and directories 755 or less. The only exceptions to this would be any [addons.html add-ons] that might require additional priviledges.
  15. Final NOTE - Just remember: many have come before you and many will come after you on this same "journey". It IS possible to perform this migration, and many of already done it, but just make sure you are prepared to see it through to the end. We ALWAYS recommend that you take a copy of your production database over to a local test environment and run through these steps and test thoroughly FIRST! Also, once you are ready to do this on your production web site, take a complete database backup as well as a backup of all your files BEFORE doing anything! If you are using NukeSentinel™ (and why would you not? LOL), you might even want to disable your site for the duration of the migration and final test out.

GOOD LUCK!!