Difference between revisions of "Upgrading"

From Online Manual

Jump to: navigation, search
(2 rollbacks in a row reverts your revert. Oops.)
(Major re-write and work.)
Line 1: Line 1:
The requirements for SMF are higher than the requirements for YaBB SE. To begin the conversion, the user should make sure that the server they intend to use, meets the requirements. Failure to do so may leave them with a broken board.
+
Upgrading an SMF forum has never been easier! Upgrading SMF from any version can be done in five fast and simple steps:
  
The requirements for upgrading SMF can be viewed by visiting the following page:
+
==Download the Upgrade Archive==
 +
The latest SMF upgrade package can be found on the downloads page of the official Simple Machines website.
  
[http://wiki.simplemachines.org/index.php?title=Client_and_Server_Requirements Client and Server Requirements]
+
Download the latest version of SMF from the official Simple Machines website. Commonly, .zip files are the preferred download type. Most operating systems have the tools available to extract .zip archives already installed.  
 
 
Note that they would be the same requirements as the requirements for installing SMF.
 
  
 +
==Extract and Upload the Install Archive==
 +
Once the upgrade archive has been downloaded it will need to be uploaded and extracted before the upgrade tool can be run. There are two possible methods for this step. The method used will depend on the tools available with the control panel supplied by the hosting service provided. Please ensure you upload in Binary if using an FTP client.
  
== The Change Log ==
 
  
A change log is a list of improvements, bug fixes and corrections that have been made through the various versions of SMF. This is a great reference to see what has been enhanced over the course of development, and a great resource for checking changes.
+
===Uploading Before Extracting===
 +
Some control panels have the ability to extract an archive, such as cPanel. This allows for hassle free uploading and extraction of the archive. Once the archive is uploaded, select the extract option to extract the archive to the desired location. Ensure that overwrite files is selected to have the newer files replace the old ones.
  
Versions before SMF 1.1.4 have a changelog.txt file among the files inside the download-able archives. Versions after this require a separate download from the downloads page.
+
===Extracting Before Uploading===
 +
If extracting abilities are not available inside the control panel, the archive can be extracted before uploading. Generally right clicking the archive and selecting the extract all option will work. The directory structure should be retained when the upgrade archive is extracted, so all files and directories are in the correct places.
  
== Uploading SMF ==
 
  
To upload SMF to the server, a user must use a FTP client and initiate a connection to their server. They need to overwrite the old files with the new ones. This step may take time, depending on how fast the user's internet connection is.
+
==Set File Permissions==
 +
After the upgrade archive has been uploaded and extracted, the files need to have their permissions set. This is commonly called CHMOD. The correct for SMF files is either 777, 775 or 755, depending on the hosting service provided. There are two methods for this step, the method used depends on the hosting service provided.
  
Once all the files are uploaded, if they are using a Unix-style server, they will need to change the permissions using CHMOD on a few of the files and directories. The procedure to do this varies between different FTP programs, but generally, the user should right click on the file or directory whose permissions they wish to change, and select Properties > Permissions > CHMOD and enter a number (777 or 755 in this case) in the permissions field. A list of files which need their permissions changed can be found on the installing SMF page.
+
===Setting File Permissions With the Upgrade Tool===
 +
The SMF upgrade tool can set file permissions simply and easily. Navigating to the directory where SMF resides, should redirect to the upgrade.php file and prompt the upgrade tool. For eg: www.yourdomain.com/forum/upgrade.php. If the upgrade detects files that need their permissions adjusted it will prompt for FTP details so it can CHMOD the files it requires for the install. This may not work on some servers.
  
== Beginning the Upgrade ==
+
===Setting File Permissions With FTP===
 +
Using a control panel or FTP client, file permissions can be changed quickly and easily. Usually, FTP programs will allow permissions to be changed by right clicking files/directories and selecting properties, attributes or permissions. The desired numerical value can be entered, or if provided, check boxes can be changed.
  
Assuming the previous steps went well, the user should now have the SMF source files on their server and the relevant permissions set. They practically have the new version of SMF already. All that the user needs to do now, is run the upgrade.php file to make the necessary changes in their database structure and their Settings.php file.
+
The Following files and directories should have CHMOD values of 777, 775 or 755:
 +
*/attachments
 +
*/avatars
 +
*/Packages
 +
*/Packages/installed.list
 +
*/Smileys
 +
*/Themes
 +
*/Themes/default/languages/Install.english.php
 +
*agreement.txt
 +
*Settings.php
 +
*Settings_bak.php
 +
*upgrade.php
  
To do these things, the user should open their favorite web browser and browse to http://www.usersdomain.tld/forum/upgrade.php. If the user set the permissions correctly on Settings.php and Setting_bak.php and uploaded all the files, they should see a form with the following checkboxes:
 
  
* '''Backup database with the prefix "backup_yourprefix_".''' Checking this box will cause the SMF upgrade utility to save a copy of the original forum database tables prior to upgrading their structure (it is a good idea for the user to make their own backups anyways.)
+
==Backup the Database==
* '''Put the Forum into maintenance mode during upgrade.''' Checking this box will put the forum into maintenance mode during the upgrade process so the forum's users will see a friendly note that the forum is being upgraded, rather than a page full of errors.
+
Before starting the upgrade process a backup of the live database should be taken, this protects the forum from accidental damage and any issues from upgrading. Although all steps are taken, and extensive testing carried out, sometimes issues develop so having a backup is crucial. The upgrade tool can backup all database tables before it runs, however best practice is to have a full backup downloaded.
* '''Output extra debugging information.''' Checking this box will cause the upgrade utility to display extra debugging information during the conversion or upgrade process. This is useful if the user experiences problems and they want to report them.  
 
  
There may also be a "Convert the existing YaBB SE template and set it as default option", which is only shown if the user has an existing template.php from YaBB SE, and they have not already converted it to an SMF-style template. Using this option, when upgrading from YaBB SE, is recommended. It will make the forum, by default, look very similar to how it did before.  
+
===Backup a Database using SMF===
 +
From within SMF navigate to Forum Maintenance, (Administration Center -> Maintenance -> Forum Maintenance), in the database section select to save the data, and the structure, and finally to compress the file. Select download and wait for the database to complete downloading in full.
  
Once the user has selected the desired options, they should select the continue link. Depending on the size of the forum, the upgrade process may take a while.
+
===Backup a Database Using phpMyAdmin===
 +
phpMyAdmin allows the option to export a database, from the initial page select the export option and follow the instructions and select your SMF database, these are different based on host.
  
== Finishing the Upgrade ==
+
===Backup a Database Using a Control Panel===
 +
If the hosting service provides a control panel interface, this can be used to backup a database. Selecting the Backups or Backups Wizard option should take you to prompts for backing up a database. With different hosts these options may have different names.
  
To avoid time outs during the conversion process, the SMF upgrade utility uses several separate steps. Once the first step has finished, the user will see a summary of what has been done; most things should report as "Successful", but if there are any error messages, SMF's beta tester team would appreciate if the user reports them on the SMF Community Forum. If there are no errors, everything has finished, and if JavaScript is disabled, the user should select the continue button. They need to continue this procedure until the upgrade utility is finished and they have a link to return to their forum.
 
  
The forum should now be successfully converted to SMF and the user can explore the new features and start using their forum; however, before doing so, they MUST delete the upgrade.php file from the server, since leaving it there can be a major security risk. (Anyone could put the forum into maintenance mode!)
+
==Run the Upgrade Tool==
 +
The final step in upgrading SMF is running the upgrade tool. Navigating to the directory where SMF resides, should redirect to the upgrade.php file and prompt the upgrade tool to run. For eg: www.yourdomain.com/forum/upgrade.php.
  
To do so, the user needs to return to their FTP program. In the directory that SMF is installed in, the user needs to locate upgrade.php, select it, and select "Delete". They may also be able to check the box that says to delete the upgrade file, without having to delete it through an FTP program, however, this will not work on all servers.
+
===Upgrade Settings===
 +
;Backup database with the prefix "backup_"
 +
:Selecting this option will get the upgrade tool to copy all data in the database before upgrading within the original database.
 +
;Maintenance Mode
 +
:Selecting this option will place the forum into maintenance mode while upgrading rather than showing errors, this is highly recommended.
 +
;Output extra debugging information.
 +
:The upgrade tool can give detailed information while performing an upgrade by selecting this option, it will aid the support team to solve any errors if they occur while upgrading.
  
[[Category:Installing SMF]]
+
 
 +
==Finishing the Upgrade Process==
 +
Once all parts of the upgrade have completed, check the box to remove the upgrade files from the server. If this does not work they will need to be deleted via FTP. All upgrade files should be removed from the server once the upgrade process is complete as they are a major security risk if left on a server unattended. Once SMF is upgraded they are no longer needed. The upgrade.php file will be the only file needing removed.
 +
 
 +
'''Congratulations on upgrading SMF successfully! Simple Machines hopes you enjoy using SMF! '''

Revision as of 08:10, 4 November 2010

Upgrading an SMF forum has never been easier! Upgrading SMF from any version can be done in five fast and simple steps:

Download the Upgrade Archive

The latest SMF upgrade package can be found on the downloads page of the official Simple Machines website.

Download the latest version of SMF from the official Simple Machines website. Commonly, .zip files are the preferred download type. Most operating systems have the tools available to extract .zip archives already installed.

Extract and Upload the Install Archive

Once the upgrade archive has been downloaded it will need to be uploaded and extracted before the upgrade tool can be run. There are two possible methods for this step. The method used will depend on the tools available with the control panel supplied by the hosting service provided. Please ensure you upload in Binary if using an FTP client.


Uploading Before Extracting

Some control panels have the ability to extract an archive, such as cPanel. This allows for hassle free uploading and extraction of the archive. Once the archive is uploaded, select the extract option to extract the archive to the desired location. Ensure that overwrite files is selected to have the newer files replace the old ones.

Extracting Before Uploading

If extracting abilities are not available inside the control panel, the archive can be extracted before uploading. Generally right clicking the archive and selecting the extract all option will work. The directory structure should be retained when the upgrade archive is extracted, so all files and directories are in the correct places.


Set File Permissions

After the upgrade archive has been uploaded and extracted, the files need to have their permissions set. This is commonly called CHMOD. The correct for SMF files is either 777, 775 or 755, depending on the hosting service provided. There are two methods for this step, the method used depends on the hosting service provided.

Setting File Permissions With the Upgrade Tool

The SMF upgrade tool can set file permissions simply and easily. Navigating to the directory where SMF resides, should redirect to the upgrade.php file and prompt the upgrade tool. For eg: www.yourdomain.com/forum/upgrade.php. If the upgrade detects files that need their permissions adjusted it will prompt for FTP details so it can CHMOD the files it requires for the install. This may not work on some servers.

Setting File Permissions With FTP

Using a control panel or FTP client, file permissions can be changed quickly and easily. Usually, FTP programs will allow permissions to be changed by right clicking files/directories and selecting properties, attributes or permissions. The desired numerical value can be entered, or if provided, check boxes can be changed.

The Following files and directories should have CHMOD values of 777, 775 or 755:

  • /attachments
  • /avatars
  • /Packages
  • /Packages/installed.list
  • /Smileys
  • /Themes
  • /Themes/default/languages/Install.english.php
  • agreement.txt
  • Settings.php
  • Settings_bak.php
  • upgrade.php


Backup the Database

Before starting the upgrade process a backup of the live database should be taken, this protects the forum from accidental damage and any issues from upgrading. Although all steps are taken, and extensive testing carried out, sometimes issues develop so having a backup is crucial. The upgrade tool can backup all database tables before it runs, however best practice is to have a full backup downloaded.

Backup a Database using SMF

From within SMF navigate to Forum Maintenance, (Administration Center -> Maintenance -> Forum Maintenance), in the database section select to save the data, and the structure, and finally to compress the file. Select download and wait for the database to complete downloading in full.

Backup a Database Using phpMyAdmin

phpMyAdmin allows the option to export a database, from the initial page select the export option and follow the instructions and select your SMF database, these are different based on host.

Backup a Database Using a Control Panel

If the hosting service provides a control panel interface, this can be used to backup a database. Selecting the Backups or Backups Wizard option should take you to prompts for backing up a database. With different hosts these options may have different names.


Run the Upgrade Tool

The final step in upgrading SMF is running the upgrade tool. Navigating to the directory where SMF resides, should redirect to the upgrade.php file and prompt the upgrade tool to run. For eg: www.yourdomain.com/forum/upgrade.php.

Upgrade Settings

Backup database with the prefix "backup_"
Selecting this option will get the upgrade tool to copy all data in the database before upgrading within the original database.
Maintenance Mode
Selecting this option will place the forum into maintenance mode while upgrading rather than showing errors, this is highly recommended.
Output extra debugging information.
The upgrade tool can give detailed information while performing an upgrade by selecting this option, it will aid the support team to solve any errors if they occur while upgrading.


Finishing the Upgrade Process

Once all parts of the upgrade have completed, check the box to remove the upgrade files from the server. If this does not work they will need to be deleted via FTP. All upgrade files should be removed from the server once the upgrade process is complete as they are a major security risk if left on a server unattended. Once SMF is upgraded they are no longer needed. The upgrade.php file will be the only file needing removed.

Congratulations on upgrading SMF successfully! Simple Machines hopes you enjoy using SMF!