Upgrading TNG

From TNG Wiki
Jump to: navigation, search

When a new version of TNG is released by the publisher, each TNG site is responsible for upgrading that site (if the administrator wants to). If you have installed TNG Mods or done other customization, you need to carefully back out your changes before doing the TNG version upgrade. This article describes a procedure for performing an upgrade to a new TNG version.

Note that the following is a comprehensive procedure that is not necessary in all cases. If the upgrade modifies only a few TNG files, then you may not need to uninstall and reinstall your TNG mods, but it usually won't hurt for you to uninstall and reinstall them just to be safe.

These steps are one approach to doing a major TNG version upgrade. When doing a minor release, several of the steps are not necessary.

Backup Your Files

The backup steps below are for a major upgrade to allow reverting back to the previous version of TNG and may be overkill in its approach.

Major Upgrade

For minor release upgrades within the same TNG version, this section can often be skipped. Skip to Minor Upgrade.

For a major version upgrade you may want to:

1 - Use the form at Administration >> Utilities >> Tables to create a backup of your database tables.

a - Select all tables, and then select "Backup" from the pull-down menu and click on "Go".

b - Wile you're there, go ahead and select "Optimize" action and click on "Go" to clean up your tables a bit.

Your backup folder is specified in the form at Administration >> Setup >> Configuration tab >> General Settings, as shown in the illustration to the right. Depending on the status of your database backups, you may want to create a new backup folder before doing the database backup.

TNG backup folder

2 - Make a complete backup of your TNG folders - perhaps excluding your media folders, since TNG upgrades won't affect your media.

Most site administrators can do this by FTPing the site to a new folder on your PC. You may, of course, already have a PC backup, and can just make a copy of that folder. Remember that your configuration files may be in a separate folder. The file subroot.php points to your configuration folder. Be sure to back up that folder, too.


3 - Create a backup copy of your existing TNG database.

With this step, you will create a second database on your database server that is a complete copy of your TNG database. This step might appear as redundant, but in the case where you decide to back off the upgrade, it will allow you to quickly switch the database name in the TNG configuration without having to do a restore database.
a - Use MySQL tool phpMyAdmin, and selection Operations >> Copy Database function
b - Test that your database copy for the backup works
  • Go to Admin >> Setup >> General Settings
  • Expand the Database section
  • Update the Database name to your new copy
  • Go to your site and make sure it works with the database copy.
  • Go back to Admin >> Setup >> General Settings >> Database, and update the database name to your regular copy of the database.
See Database - Backup and MySQLDumper for additional database backup options, both of which will require a restore in the case of a back off.

4 - If your host is not routinely creating backups of your site, use your hosting service Contol Panel to create the site and database backups (if you can).

This step is intended to create a site and database backup at your hosting service, rather than on your PC.
Many hosting services do this routinely, so many TNG administrators can skip this step.

Select and Download the Upgrade

5 - Download the appropriate upgrade for the version you are currently running and the version you are upgrading to.

The upgrades are zip files, which you can download to any folder you want, as long as you ultimately unzip the upgrade to your TNG folder.
Note that some administrators prefer to download a full upgrade, as though they are doing a new installation, so that they have a "pristine" copy of every TNG file. It can be useful to download and extract the full upgrade to a completely separate folder on your PC, and also to download the appropriate version a-to-version b upgrade that you extract to your main TNG folder.
If you download only a version a-to-version b upgrade, you will have only the files that have been changed, and, if you find that you need to restore a file, you may need to use your old version backup rather than the "pristine" copy.

Local PC Test Site

If you have a working PC (Macintosh or Windows) test environment, you should do the remaining steps on your PC before upgrading your production site.
See WampServer, XAMPP, or MoWeS for setting up a local computer TNG environment.

Uninstall Mods

Note that this section does not apply if you have not installed any TNG mods, or if the upgrade does not modify and of the files that you have modified.

6 - Uninstall your existing Mod Manager mods

  • On a major upgrade, you may want to remove all your TNG Mods using the Mod Manager's so-called "batch" capability to uninstall several mods at once. Mod Manager - Remove capability.
If you are not using the Mod Manager but making modifications manually in TNG, you may need to use WinMerge or some other appropriate compare utility to determine how to rework your existing modifications. You should also check the TNG Change Log to see if your modification is still needed or has been replaced by new features. It might be useful for you to extract the TNG upgrade files to your local computer first to determine whether you need to rework some of your modifications.
  • On a minor upgrade, you might be able to just clean up the partially removed mods after the upgrade.

Upgrade TNG

Set Maintenance Mode

7 - Consider putting your public site in Maintenance Mode, which simply tells your users that the site is undergoing maintenance.

  • Go to Admin >> Setup >> expand the Database section
  • change Maintenance Mode to ON
  • Be sure to click the "Save" button way down at the bottom of the page. (It is not visible in the illustration to the right)
Set Maintenance Mode On

Extract Files

8 - Extract the upgrade's Zip file to your TNG folder, overlaying existing files, thereby upgrading in place

Note that if you use this approach, make sure you have taken the appropriate backup steps
Option a - Unzip on your PC and FTP to your server.
You can, if you wish, extract the upgrade to an empty folder, and then FTP all of the extracted files to the server, or you can extract the upgrade to a local copy of your TNG site. Be sure that you don't overwrite the only backup of the server that you have.

Note that you do not need the WinZip program to unzip your Zip file. On both Windows and the Macintosh, you can unzip a Zip archive simply by dragging the files in the archive to another folder on your PC.

After you have extracted all of the files to (your PC's copy of) your main TNG folder, you'll then need to FTP the updated files to your server. Depending on your FTP program, you might be able to tell which files have been changed, and you may be able to upload only those. Or you may need to upload the entire site to your server. Note that you cannot count on the file's change date to indicate which copy is the updated one, because, if you have just uninstalled some mods, the affected files will show the current date, even though the file has simply been restored to an earlier status.

Option b - Copy the upgrade Zip file to your server, and use Extract capability in CPanel.
If your hosting service offers an Extract capability, then you can extract the TNG upgrade zip file directly on your host, rather than having to FTP each upgrade file to your host.
  1. Select the folder under public_html where you FTPed the TNG upgrade zip file, which should be where you installed TNG
  2. Select the TNG upgrade zip file
  3. Click the Extract button
  4. Verify that the extract will be in the correct folder
  5. Click the Extract File(s) button
Extract TNG upgrade files
Option C - Copy the upgrade Zip file to your server, and use another server-based extract method.
If your hosting service does not offer an Extract and Compress capability from the File Manager, as is the case on ICDSoft, you might still be able to extract the TNG upgrade directly on your host by clicking on the TNG zip file. This will launch an archive extract screen, where you should do the following:
  1. Uncheck the Create Subdirectory option
  2. Check the Overwrite Existing Files option
Launched archive extract function
Uncheck and check options

Follow the Readme file

Note that the extract may contain more than one file. You need to open the readme file whose filename matches the version numbers that you are upgrading from and to.

9 - Open the appropriate readmexxx.html file in your web browser, and follow its instructions.

  • - Possibly rename and move files from a special folder
  • - Possibly update your database

Note: This might be a good place to clear your browser cache. Failure to clear cache can sometimes result in failure of the upgraded scripts to behave properly or exhibit problems such as failing to allow the dropdown items in General Settings to expand properly when clicked. See the WIKI article on Bypassing Browser Cache. Bypassing_Browser_Cache

Re-install Mods

Note that this section does not apply if you do not modify any of the TNG files.

10 - Download the appropriate versions of your mods from the TNG Wiki

Check the TNG Wiki article for each of your mods to see if the mod has been eliminated or re-worked for this TNG upgrade. If it has, you should delete the old mod (which should have been backed up with your site in step 2 above), and download the new mod zip file.

11 - Upload the downloaded zip files to your TNG mods folder and extract on your hosting site

or extract the downloaded zip files in your local computer, and upload all the extracted files to your hosting service TNG mods folder

12 - Install the each mod from the Mod Manager status (Mod List) screen

Note that if the Mod Manager status shows Clean Up and the error message includes Bad Target, the mod needs to be reworked. Contact the mod developer.
In TNG V9, a Bad Target will trigger an Unable to Install this mod error messages. If the mod is partially installed, the Bad Target error will need to be fixed before you can Clean Up the partial installation.
In TNG V10, the Bad Target will trigger a Partially Installed status if any part of the mod is installed. If no parts of the mod are installed, it will show as Cannot Install

Clean Up

13 - Delete obsolete files based on the instructions in the readmexxx.html file

or in the obsoletefiles.txt if one is provided.

14 - Delete the readme files

You should delete the readme files to prevent a re-install

15 - Delete the upgrade files

You probably don't need the update Zip file any more, though it could be useful as a backup.