SMF1.1:Package manager

The package manager is a default feature of SMF that allows you to install packages for your forum. Packages consist of customizations and updates to your forum. Customizations can be a number of things: a new feature, a theme, avatar set, smiley set, a feature enhancement, or anything you can think of and program for SMF to do. Note, however, that theme installs are not handled by the Package Manager. Before we go any further, it cannot be emphasised enough, here, that you really should backup your forum, before installing any packages (mods). It is very important that you back up both your forum and the database. Detailed information on backing-up can be found here: Backup

Browse Packages
In the Browse Packages section of the package manager, you will see all of the packages that are currently downloaded on to your forum. You can install/uninstall them, view details of a package, and delete packages. Applying the package to your forum is as easy as clicking 'Proceed' next to the package you want to install, most of the time. However, you may be asked to fill in FTP information whenever the files needed are not writeable.

Latest Packages / Package of the Moment
Located at the top of the 'Browse Packages' section is a box that includes the Latest Packages that have been added to the SMF Customizations Site. Clicking on the name of any of the packages will expand information about the package taken from the mod's download/description page from the mod site.

You can select Install Now! underneath the name of the mod after it is expanded and then the package will be downloaded to your forum and the install screen will appear showing which files could be edited successfully, and which ones (if any) could not be. To go back to the list of the latest packages, you can select (go back), located at the bottom of the information about the mod.

These packages are grabbed from a javascript file on the SMF server which is automatically updated with the latest mods that have been added to the mod site.

At the bottom of the Latest Packages box is the Package of the Moment, which is chosen by selecting a random mod package from the SMF mod site. The package listed here works in the same way as the latest packages above it, and will expand, allowing you to install it.

Browse Packages
Underneath the Latest Packages box you will see the list of all the mod packages you have downloaded on to your forum. There are three options listed next to each mod:


 * Apply Mod or Uninstall
 * List Files
 * Delete

When installing a package, you must select Apply Mod next to the package you want to install. If you see failure instead of success on the pre-install, this means that there is an issue with the editing a file the package is suppose to edit or the package does not work with your version of SMF. You might want to contact the developer of the package for further information. If there are test failures, it generally not advised to proceed with the installation unless you are prepared to patch the part which has failed.

When uninstalling a package, you must click Uninstall next to the package you want to uninstall. If you get any failure notices for any files, that means the mod cannot be uninstalled completely. If there are test failures, uninstalling the mod is not recommended.

Download Packages
The download packages section of the package manager provides tools for loading and installing a package and for using the package server browser. To download a package is to obtain it from some place it is stored. In some cases, the package may be downloaded directly to your forum. In other cases, it must be first downloaded to your desktop, then uploaded from your desktop to your forum. Download packages is accessed by selecting the download packages tab from the package manager. Required FTP settings are found in the installation options section.

Package servers
An SMF package server is a repository stocked with modification packages for SMF forums.

The package server's browse feature can be used in either of the following ways:
 * To obtain packages from a local SMF package server, if one is located on the forum host
 * To obtain packages from a remote SMF package server (such as the Simple Machines third party mod site), if the forum host permits downloading SMF packages directly from a remote SMF package server

Selecting the browse button next to a server in the package servers list allows viewing of the packages available on that package server. If this feature does not work, uploading a package may be used instead, in order to upload a package that has already been manually downloaded to the desktop. The delete button is used to remove a package server listing.

Add server
To add a package server to the list, the administrator may type in a server name (e.g. Simple Machines Third-party Mod Site) and a URL (e.g. http://custom.simplemachines.org/packages/mods), then select the add server button.

Upload a Package
Upload a Package is used to upload a package from the desktop to the forum. The browse button is used to locate the package file, and the upload button is used to upload it to the forum. After an upload, the administrator is given the option to immediately apply the package, or to use browse packages to install it at a later time.

If you prefer, you may upload the package, or a directory full of package files, to your "Packages" directory, using FTP. .

Installing a Package
Once you have uploaded a package, you can install it -- either immediately, or later, from the Browse Packages list.

Under the heading Apply Mod, you'll see the warning Please remember to always make regular backups of your sources and database before installing mods, especially beta versions. Heeding this advice can save you from trouble later.

Below this, the Installation Readme will display any readme text supplied by the mod's author.

Under the heading of Installations actions, you will see a list of all the actions the package manager will take to install this mod. You will see actions of the following types.
 * Extract file: A file will be copied from the package, to the given path and file name.
 * Extract Tree: An entire directory full of files will be copied from the package to the given path
 * Adapt Database: The named script from the package will be executed. Generally, this script will get the database ready for the mod to run.

As the Package Manager prepares this list, it has made a backup of php files for the forum (please see the FAQ on using package backups for more on this file). At the same time, it tests each action it is preparing to take on your forum, and reports the results in the list. The Package manager will report whether the installation test was a success or a failure. If the test failed, it is recommended that you resolve the problem before proceeding with the installation. Installation will begin when you select the Install Now button at the bottom of the page. After a successful installation, the Package Manager may redirect you to the new mod's configuration page, or return you to the Package Manager.

Installed Packages
This page allows you to view your installed mods, the files included in each mod, and gives you the ability to uninstall any mods that you no longer want at the moment. It is similar to the Browse Packages section.

Note that the list of mods shown on this section are taken directly from the Packages/installed.list file of your forum. When mods are added or removed, the file is updated and thus the list on this page will also be updated.

You can select the Delete Mod List button at the bottom of the page to clear the list of mods you have installed, but this is generally not recommended.

Options
The installation Options section of the package manager, accessed via package manager's options tab, is for information that is sometimes required during installation. Some package installations may require FTP login information or changes to file permissions.


 * Installation Options
 * Cleanup Permissions
 * FTP Information Required

Installation Options
Settings for FTP Server, Username and Port are used by SMF to make an FTP connection in order to complete certain package installations. The Create Backup versions of replaced files with a tilde (~) on the end of their names checkbox instructs SMF to save a backup version of any file that is changed or replaced during installation.

Cleanup Permissions
Because it is generally more secure to keep as few files writeable as possible, and because some package installations involve more files than others, this section provides a quick way to change file permissions in the SMF directories. In order of increasing permission and decreasing security, the options under this heading are: The minimum files are writeable; All files are writeable; and Only the standard files are writeable. Choose one of these options and then selecting the Change file permissions button below makes the change.

FTP Information Required
After the change file permissions button is selected, SMF will display a new page prompting for additional FTP information.


 * FTP Server - The internet address of the forum ftp server (e.g. ftp.forumname.org)
 * Port - FTP port, supplied by the site host if other than 21
 * Username - The FTP username used to login to the FTP server.
 * Password - The password for the FTP username given above.
 * Local path to SMF - FTP Path to the SMF root. This may differ from the SMF path given in the core configuration section of server settings.

The What is the local path to SMF? FAQ has more information.

Following selection of the Proceed button, SMF should make the requested file permission changes at the Local path to SMF and return to the Installation Options section. If this does not happen: 1) The FTP Server does not exist, the page will be refreshed -- no error message will be displayed; 2) The FTP Server exists, but FTP login fails (incorrect username/password), a browser Error 500 message will be displayed; 3) The FTP login is successful, but the local path to SMF does not exist, a small FTP error message will be displayed.