From RNWiki
Jump to: navigation, search
(Intro: minor change - added hyperlink to the XAMPP site)
(From Prior Versions of {{RN}}: removed one comment that is not really needed)
 
(One intermediate revision by the same user not shown)
Line 19: Line 19:
 
'''NOTE''': we always encourage folks to have their own local development environment using tools such as [http://www.apachefriends.org XAMPP] to have a fresh copy of their running site to test their changes on!  You may also want to disable your site within {{NS}} using the ''Site Switch'' function right before you begin and then enable it again once you are finished.
 
'''NOTE''': we always encourage folks to have their own local development environment using tools such as [http://www.apachefriends.org XAMPP] to have a fresh copy of their running site to test their changes on!  You may also want to disable your site within {{NS}} using the ''Site Switch'' function right before you begin and then enable it again once you are finished.
  
If you are upgrading from a previous {{RN}} installation, review the guidelines under the sub-heading of '''From Prior Versions of {{RN}}'''. If you are migrating from a previous non-{{RN}} installation to {{RN}}, review the guidelines under the sub-heading of '''From Other Versions of *Nuke'''.  If you are a seasoned {{RN}} veteran, are just upgrading from an existing {{RN}} installation, and don't need all the extra helpful hints and lessons learned, you might just want to review the '''Quick {{RN}} Upgrade''' section.
+
If you are upgrading from a previous {{RN}} installation, review the guidelines under the sub-heading of '''[[RavenNuke2:Upgrades_and_Migrations#From_Prior_Versions_of_RavenNuke.E2.84.A2|From Prior Versions of {{RN}}]]'''. If you are migrating from a previous non-{{RN}} installation to {{RN}}, review the guidelines under the sub-heading of '''[[RavenNuke2:Upgrades_and_Migrations#From_Other_Versions_of_PHP-Nuke|From Other Versions of *Nuke]]'''.  If you are a seasoned {{RN}} veteran, are just upgrading from an existing {{RN}} installation, and don't need all the extra helpful hints and lessons learned, you might just want to review the '''[[RavenNuke2:Upgrades_and_Migrations#Quick_RavenNuke.E2.84.A2_Upgrade|Quick {{RN}} Upgrade]]''' section.
  
 
==From Prior Versions of {{RN}}==
 
==From Prior Versions of {{RN}}==
  
These instructions are for upgrading from a version greater than or equal to 2.02.00 of {{RN}} to the latest {{RNVersion}} version ONLY. Releases prior to 2.02.00 are no longer supported directly from an upgrading perspective. Sorry, but you need to stay more current! Read ALL steps first to get the complete "picture" of what needs to be done and when.  We would also highly recommend reviewing the applicable [[RavenNuke2:Release_Notes|Release Notes]] as they contain valuable information on what has changed as well as key upgrade considerations.  Let us get started...
+
These instructions are for upgrading from a version greater than or equal to 2.02.00 of {{RN}} to the latest {{RNVersion}} version ONLY. Releases prior to 2.02.00 are no longer supported directly from an upgrading perspective.  Read ALL steps first to get the complete "picture" of what needs to be done and when.  We would also highly recommend reviewing the applicable [[RavenNuke2:Release_Notes|Release Notes]] as they contain valuable information on what has changed as well as key upgrade considerations.  Let us get started...
  
 
#'''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. <span style="color:red">Do NOT ignore this ALL important step (or any others for that matter). You have been warned!</span><br /><br />
 
#'''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. <span style="color:red">Do NOT ignore this ALL important step (or any others for that matter). You have been warned!</span><br /><br />

Latest revision as of 13:01, 10 February 2010

Home>Upgrades and Migrations

If you have come here looking for instructions for a brand new RavenNuke™ installation, you have come to the wrong place! For a brand new RavenNuke™ installation you would need to following the instructions for New Installations. If you are upgrading from a previous RavenNuke™ installation to the latest version or attempting to migrate from an existing non-RavenNuke™ installation, read on...

Since it is impossible to account for every possible scenario, what we attempt to do is provide helpful hints, guidelines if you will, on the overall approach we recommend you take with your upgrade or migration. While these guidelines look extensive and "wordy", we believe they encourage good sound site administration principles and should be read in their entirety. However, the bottom line high-level steps are:

  • Take backup of both database and files (so can restore quickly if needed)
  • Extract files from package and configure/update as needed
  • Publish the files
  • Upgrade the database
  • Clean-up obsoleted files as well as installation files (i.e., such as the INSTALLATION directory)
  • Configure any database related settings (as you already did the file-based ones above)
  • Test, test, test...
  • Done

Sound easy? Sometimes it is that easy, just all depends upon how many customizations you have made.

NOTE: we always encourage folks to have their own local development environment using tools such as XAMPP to have a fresh copy of their running site to test their changes on! You may also want to disable your site within NukeSentinel™ using the Site Switch function right before you begin and then enable it again once you are finished.

If you are upgrading from a previous RavenNuke™ installation, 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 *Nuke. If you are a seasoned RavenNuke™ veteran, are just upgrading from an existing RavenNuke™ installation, and don't need all the extra helpful hints and lessons learned, you might just want to review the Quick RavenNuke™ Upgrade section.

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.50.00 version ONLY. Releases prior to 2.02.00 are no longer supported directly from an upgrading perspective. Read ALL steps first to get the complete "picture" of what needs to be done and when. We would also highly recommend reviewing the applicable Release Notes as they contain valuable information on what has changed as well as key upgrade considerations. Let us get started...

  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, especially the section on Prepare/Install the Files) so that you take care not to overwrite critical files such as config.php, .htaccess, .staccess, .ftaccess, etc. which you have already configured. Some further considerations related to this step:
    1. The files config.php and rnconfig.php are constantly being enhanced with new configuration options so be sure to merge your changes carefully in with our new options each time.
    2. 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.
    3. The Advanced Editor (FCKeditor) continues to evolve and thus RavenNuke™ with it. With FCKeditor version 2.6.3, there was a significant name change to the directory that the editor resides in, which will NOT work properly in the latest RavenNuke™. The following steps are critical to getting this right if you are on RavenNuke™ version 2.30.00 or less:
      1. If you had customized any of the editor settings, including custom tool bars, within any of the existing files such as fckconfig.js, save off these files somewhere safe, such as on your local PC.
      2. BEFORE UPLOADING the RavenNuke™ files from the package, you need to remove 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.
      3. AFTER UPLOADING the RavenNuke™ files (or you can do prior to uploading the package locally), compare your customization settings / toolbars with the RavenNuke™ distribution files and make your customizations as needed to the RavenNuke™ files (and upload them if needed).
    4. If you were at 2.30.00 or greater, it is still a good idea to make sure you do not overwrite any editor customizations that you have done as we will be providing regular FCKeditor updates with each release.

  4. Upgrade Core RavenNuke™ Tables - From your browser, type http://www.YOURDOMAIN.com/INSTALLATION/rndb_upgrade.php. This will upgrade your core RavenNuke™ tables to the latest version. It will ONLY touch the core tables and will not affect any tables that you have added as completely new (as long as there are no name collisions). However, if you have previously made changes to these core tables, there is no guarantee that this upgrade 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 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 - After the rndb_upgrade.php script finishes, it will provide a button to click to initiate the NukeSentinel™ upgrade, but if for whatever reason you need to run it directly, from your browser, type http://www.YOURDOMAIN.com/INSTALLATION/rndb_upgrade_nukesentinel.php; 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 upgrade script will recognize that you are on a later version and will stop). The following points may also be considered:
    1. The same comment from the previous step, with regards to saving the output, applies here as well.
    2. 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.
    3. You may want to review your blocker settings and strings list just to make sure they are what you desire.

  6. Add-Ons - With each RavenNuke™ release, we have the option of including new scripts that we feel hold significant promise to become core to RavenNuke™ or that are just viewed as very useful by the community, but may not be as straightforward to integrate into RavenNuke™ (so we provide versions that will integrate without coding). Eventually, many of these become core to RavenNuke™. The upgrade script will take care of adding the tables for you if they do not already exist. Like with anything else, if you installed an add-on and made customizations to it, care will have to be taken to merge or re-customize what is provided in the RavenNuke™ package if the add-on makes it into Core. The Release Notes will document when these shifts from the AddOnsFiles directory to core (i.e., under html) occur.

  7. 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 download package.)

  8. Additional Add-Ons and Configurations - Again, cannot stress enough about reading through the rest of this manual, especially the Configuration section to make sure you have configured everything.

  9. Clean-Up Obsolete Files - It is highly recommended 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 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 or otherwise negatively affect site operations. 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 along with a readme.txt file.

  10. Test, Test, Test! - Do NOT skip this part! Whether migrations are easy or complex, YOU should always test your final upgraded system thoroughly. You never know what might be lurking underneath. You do not want your end-users / customers to find these for you. :wink:

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 sheer 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. Also, I would familiarize yourself with all of the other documentation on this web site, including the Release Notes.

  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 original 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 (with additional security and compliance tweaks made along the way).

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

  6. Apply RavenNuke™ Core Database Changes - This has now been greatly simplified (we hope). Using phpMyAdmin, navigate to your database and table nuke_config. Edit the one row that is in that table and change the field version to have a value of rn2.02.00 and save the record. From your browser, type http://www.YOURDOMAIN.com/INSTALLATION/rndb_upgrade.php. This will upgrade your core tables to the latest version of RavenNuke™ (you will have to upload the INSTALLATION directory to the root of your web site first)!

  7. What to Do About NukeSentinel™? - When the previous upgrade script ends, it will provide a button to click to upgrade NukeSentinel™. Simply click that button and follow the instructions on the page. If your version of NukeSentinel™ is very old or non-standard, you will need to get the latest version of NukeSentinel™ and run the table remove step followed by the full installation step. Please see our Configuration page for additional help on how to configure either NukeSentinel™ or RavenNuke™ to your liking.

  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 a copy of 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 detailed Installation and Configuration on-line documentation. 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. 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.

  10. 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.)

  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 still 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 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 Obsoleted 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 or negatively affect system operations.

  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 add-ons/modules that might require additional privileges.

GOOD LUCK!!

Quick RavenNuke™ Upgrade

These instructions are just the minimum list of steps needed to upgrade an existing RavenNuke™ installation to the latest. It is assumed that you already know all of the "gotchas" that are addressed in the above more detailed instructions and you just want to simple reminder of what is needed for each upgrade. Here are these highly simplified steps:

  1. Backup Current Installation FIRST! (We will NEVER suggest skipping this step!)
  2. Extract the files, merge changes and upload (include the UPLOAD of the INSTALLATION directory)
  3. Execute the rndb_upgrade.php script (take note of any installation errors that are thrown) and if at the end click the upgrade NukeSentinel™ link
  4. After successful DB upgrades, remove the INSTALLATION directory
  5. Clean-up any obsolete files
  6. Check to see if there is a more recent IP to Country (IP2C) update and apply (should really be kept up-to-date as they are released anyways)

You now have a fully functioning upgraded RavenNuke™ system as long as your Step 2 was done properly... undoubtedly the most important and time-consuming step. A tool like Beyond Compare 3 proves invaluable for that step.

GOOD LUCK!!