Upgrading: Difference between revisions From Online Manual

Jump to: navigation, search
(I took all the pages from the OM that were related to upgrading, and fit them into one page.)
m (Full stop placement fixed.)
 
(71 intermediate revisions by 17 users not shown)
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.
{{TOCright}}Upgrading is moving to a more recent version of SMF by getting a fresh set of all necessary files.  It is necessary when moving from an earlier major version to a more recent one (SMF 1.1.x to SMF 2.0.x, for example). If you want a clean start with the same version you have now, take a look at [[How to upload a fresh set of files]].


The requirements for upgrading SMF can be viewed by visiting the following page:
If you are moving from an older version of SMF (for example 1.1.1) to a newer version in the same series (for example 1.1.2) and you want to avoid uninstalling your mods, you may consider [[Patching|patching]]. If you want to install a forum from scratch, please see the instructions on [[Installing|installing]] SMF.


    * [http://wiki.simplemachines.org/index.php?title=Client_and_Server_Requirements Client and Server Requirements]
Upgrading an SMF forum can be done in six quick and simple steps:
 
Note that they would be the same requirements as the requirements for installing SMF.


==Download The Upgrade Archive==
The latest SMF large upgrade package can be found on the "[http://download.simplemachines.org/ Download]" page of our website.


== The Change Log ==
First, you should download the appropriate package. The '''Large upgrade''' is the one required for upgrading. Usually, .zip files are the file type that most forum administrators find the easiest to use. Most operating systems already have tools to extract .zip archives installed.


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.
{{ambox|type=notice
|text=Please note that when using the large upgrade, all the [[mods]] that you have installed will have their edits to files removed.}}


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.
==Back up Your Forum==
Before starting the upgrade process, a [[backup]] should be taken. This includes, specifically, the database as it contains all the members, posts, and other items in the forum. This protects the forum from accidental damage and any issues from upgrading. Although extensive testing is always carried out, sometimes unforeseen issues develop. Therefore, having a backup is crucial. The upgrading tool can backup all database tables before it runs, but the files are not backed up and the best practice is to have a full backup available.


== Uploading SMF ==
'''For more details on backing up your forum, please see the [[backup]] page.'''


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.
===Back up Your Files===
Using an [[FTP_-_How_do_I_use_FTP|ftp client]] access your forum directory and download all the files and directories present in there.


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.
==Extract The SMF Archive and Upload The Files to Your Website==
The SMF upgrade archive contains all of the files that need to be uploaded to the same location where the current forum is located, and overwrite all of the existing files with new files.


== Beginning the Upgrade ==
You will need to use either [[FTP - How do I use FTP|FTP]] or the tools in your hosting account's control panel. (For more information on the control panel supplied by your hosting service, please see the documentation provided by your hosting service).


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.
{{Set file permissions|upgrade}}


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:
==Run the Upgrading Tool==
The final step in upgrading SMF, is to run the upgrading tool. Navigate with your browser to the upgrade.php file (it can be found in the directory where SMF is located) and run the upgrade, for example: <nowiki>www.yourdomain.com/forum/upgrade.php</nowiki>.


    * Backup database with the prefix "backup_yourprefix_".
===Upgrade Settings===
      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 database with the prefix "backup_"
    * Put the Forum into maintenance mode during upgrade.
:Selecting this option will get the upgrade tool to copy all data in the database before upgrading within the original database.
      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.
;Maintenance Mode
    * Output extra debugging information.
:Selecting this option will place the forum into maintenance mode while upgrading rather than showing errors, this is highly recommended.
      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.  
;Output extra debugging information.
:The upgrade tool can give detailed information while performing an upgrade by selecting this option, it will aid the SMF Support Team in solving any errors if they occur while upgrading.


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.  
==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. These files are upgrade.php and the .sql files whose name starts with 'upgrade'.  They are a major security risk if they are left on a server unattended. Once SMF has been upgraded, they are no longer needed.


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.
If you were already using SMF 2.0 prior to the upgrade, and had mods installed, you may also want to use [[Manually setting a package installed or uninstalled|Fix_Packages.php]] to remove any hooks that the mods had installed, in order to avoid issues from partially erased mod installations.


== Finishing the Upgrade ==
===Upgrading Using the Command Line===
It is also possible to upgrade to a more recent version of SMF using the Command Line Interface (CLI).  This is particular useful if you have experienced errors trying to upgrade your forum using the method outlines above, as the CLI is more effective in providing an error code, which is helpful in identifying any issues that are preventing the upgrade from being completed.


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.
To upgrade using this method, go to a command line prompt, navigate to the folder where your settings.php and upgrade.php files are, and issue the following command:<br>
<code>php upgrade.php</code>


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!)
There are some options, which you can query using --help.  You will see something like this:<br>
<code>$ php upgrade.php --help
SMF Command-line Upgrader
Usage: /path/to/php -f upgrade.php -- [OPTION]...


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.
        --language=LANG        Reset the forum's language to LANG.
        --no-maintenance        Don't put the forum into maintenance mode.
        --debug                Output debugging information.
        --backup                Create backups of tables with "backup_" prefix.
</code>
 
Note that sometimes your host offers multiple versions of php, so you need to specify the correct version when running the command.  You might need to ask your host what the proper path to use is.  If this is the case, your command line would end up looking something like this:<br>
<code>/opt/php56/bin/php upgrade.php</code>
 
{{Upgrade FAQ}}
 
{{Installing SMF}}

Latest revision as of 23:25, 2 January 2024

Upgrading is moving to a more recent version of SMF by getting a fresh set of all necessary files. It is necessary when moving from an earlier major version to a more recent one (SMF 1.1.x to SMF 2.0.x, for example). If you want a clean start with the same version you have now, take a look at How to upload a fresh set of files.

If you are moving from an older version of SMF (for example 1.1.1) to a newer version in the same series (for example 1.1.2) and you want to avoid uninstalling your mods, you may consider patching. If you want to install a forum from scratch, please see the instructions on installing SMF.

Upgrading an SMF forum can be done in six quick and simple steps:

Download The Upgrade Archive

The latest SMF large upgrade package can be found on the "Download" page of our website.

First, you should download the appropriate package. The Large upgrade is the one required for upgrading. Usually, .zip files are the file type that most forum administrators find the easiest to use. Most operating systems already have tools to extract .zip archives installed.

Back up Your Forum

Before starting the upgrade process, a backup should be taken. This includes, specifically, the database as it contains all the members, posts, and other items in the forum. This protects the forum from accidental damage and any issues from upgrading. Although extensive testing is always carried out, sometimes unforeseen issues develop. Therefore, having a backup is crucial. The upgrading tool can backup all database tables before it runs, but the files are not backed up and the best practice is to have a full backup available.

For more details on backing up your forum, please see the backup page.

Back up Your Files

Using an ftp client access your forum directory and download all the files and directories present in there.

Extract The SMF Archive and Upload The Files to Your Website

The SMF upgrade archive contains all of the files that need to be uploaded to the same location where the current forum is located, and overwrite all of the existing files with new files.

You will need to use either FTP or the tools in your hosting account's control panel. (For more information on the control panel supplied by your hosting service, please see the documentation provided by your hosting service).

Set File and Directory Permissions

File and directory permissions control who can see your files and use your directories. They can control whether you will be able to install mods to your forum. On Linux and other Unix-like servers the chmod command is used to designate permissions. On most servers, a setting of 755 for directories and 644 for files will work. If this does not work on your hosting service, you may need 777 or 775 for directories, and 666 or 664 for files. Some hosts do not allow using 777 for directories or 666 for files -- using such high values will cause Internal Server Errors, 500 erors, or other errors. If the permission on your files or directories does not make them writable, the SMF upgrader will report the problem -- if it can detect it.

Note: If a Windows server is being used rather than a Linux server, then you will need to contact your host to change the file/directory permissions.

Setting File Permissions with the Upgrader

In many cases, the SMF upgrader can handle this for you. If you want to give this a try, skip this step for now, and wait until you come to the appropriate point in the upgrader. The upgrader might need to ask you for FTP login details to get the job done, so be sure to make a note of them. If you run into any problems setting file permissions with the upgrader, you can use the instructions below for setting file permissions with FTP to handle it yourself.

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.


Run the Upgrading Tool

The final step in upgrading SMF, is to run the upgrading tool. Navigate with your browser to the upgrade.php file (it can be found in the directory where SMF is located) and run the upgrade, for example: 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 SMF Support Team in solving 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. These files are upgrade.php and the .sql files whose name starts with 'upgrade'. They are a major security risk if they are left on a server unattended. Once SMF has been upgraded, they are no longer needed.

If you were already using SMF 2.0 prior to the upgrade, and had mods installed, you may also want to use Fix_Packages.php to remove any hooks that the mods had installed, in order to avoid issues from partially erased mod installations.

Upgrading Using the Command Line

It is also possible to upgrade to a more recent version of SMF using the Command Line Interface (CLI). This is particular useful if you have experienced errors trying to upgrade your forum using the method outlines above, as the CLI is more effective in providing an error code, which is helpful in identifying any issues that are preventing the upgrade from being completed.

To upgrade using this method, go to a command line prompt, navigate to the folder where your settings.php and upgrade.php files are, and issue the following command:
php upgrade.php

There are some options, which you can query using --help. You will see something like this:
$ php upgrade.php --help SMF Command-line Upgrader Usage: /path/to/php -f upgrade.php -- [OPTION]...

       --language=LANG         Reset the forum's language to LANG.
       --no-maintenance        Don't put the forum into maintenance mode.
       --debug                 Output debugging information.
       --backup                Create backups of tables with "backup_" prefix.

Note that sometimes your host offers multiple versions of php, so you need to specify the correct version when running the command. You might need to ask your host what the proper path to use is. If this is the case, your command line would end up looking something like this:
/opt/php56/bin/php upgrade.php


Useful FAQ



Advertisement: