SMF1.1:Package manager: Difference between revisions From Online Manual

Jump to: navigation, search
No edit summary
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{versions|versions}}
{{TOCright}}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]]  
{{TOCright}}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]]  
(Please note that modifications have their own dedicated support topics. If you have any problems with a mod, whether it be with its installation or use, please post in the mod's support topic, rather than in the general support boards, as you are more likely to get a speedy and accurate response there. The topic can be accessed by clicking on the ''Support and comments for this mod'' link, on the mod's download page).


== Browse Packages ==
== 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 writable.
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===
===Latest Packages / Package of the Moment===
Line 18: Line 18:
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:
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'''/'''Install Mod''' or '''Uninstall'''
*'''Apply Mod''' or '''Uninstall'''
*'''List Files'''
*'''List Files'''
*'''Delete'''
*'''Delete'''


When installing a package, you must select '''Apply Mod/Install 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 [[Error in mod installation|test failures]], it generally not advised to proceed with the installation unless you are prepared to [[Manual installation of mods|manually install the mod]].
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 [[Error in mod installation|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 [[Error in mod installation|test failures]], it is generally advised to proceed only when you are prepared to [[Manual installation of mods|manually uninstall the mod]].
 
{{Version Specific|small=yes
|version=2
|content= ===Advanced===
At the bottom of the ''Browse packages'' section is a link located on the right side of the page. Clicking this will add an additional box to the page which allows you to emulate your version of SMF to another version temporarily. Just type exactly the version you want to emulate in the input box next to ''Emulate Version''. This is useful if a mod is set to only install for specific versions of SMF, however the mod may still work on your version. To revert the text entered in the input to your version of SMF, click the ''Revert'' link.


For more information on using this feature, please see [[How can I install a mod that doesn't work in my SMF version]]
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 [[Error in mod installation|test failures]], uninstalling the mod is not recommended.
}}


== Download Packages ==
== Download Packages ==
Line 47: Line 39:


===Add server===
===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/mods/), then select the add server button.
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.
 
{{Version Specific|small=yes
|version=2
|content= ===Download a package by URL===
Download a package by URL is a quick way to download a package from the web to a forum.
 
*URL - The exact URL of the desired modification package.
*Name of the file - Required if the download URL does not include the file name of the package. If left blank, the base name of the file from the URL will be used. For example, the default name of the file for a package mod_name.zip would be mod_name.
 
''For example the URL format will be: http://custom.simplemachines.org/mods/index.php?action=download;mod=1519;id=179488''
}}


===Upload a Package===
===Upload a Package===
Line 68: Line 49:
Once you have uploaded a package, you can install it -- either immediately, or later, from the Browse Packages list.
Once you have uploaded a package, you can install it -- either immediately, or later, from the Browse Packages list.


Under the heading '''Apply Mod/Install 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.
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.
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.
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.
{{ {{Localized|Version specific}}|small=yes|version=2|content=
*Execute Modification: Changes made to existing files. Select the [[File:selected.gif|alt=selected]] icon to reveal a list of exactly what is being done to this file, complete with an [[File:Package_ops.gif|alt=Package ops]] icon to show the search and/or replace strings used in this operation.}}
*Extract file: A file will be copied from the package, to the given path and file name.
*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
*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.
*Adapt Database: The named script from the package will be executed. Generally, this script will get the database ready for the mod to run.
{{ {{Localized|Version specific}}|small=yes|version=2|content=
Modification packages often make changes to the default theme.  These will be listed under '''Installation actions'''.  Often, it is possible for the package to make changes to all of your themes. These changes are optional, and won't be done unless you check the box next to the modification's name.}}


As the Package Manager prepares this list, it has made a backup of php files for the forum (please see the [[A mod broke my forum what should I do‎|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. Checking out the parser, on the mod's download page, will tell you which edits are made to which files. If you can match up the file edited, there with the edit that is failing, you can often make the failed edit, yourself, manually. If you do that, we have to stress, again, the importance of backing-up, before you do this. You can read more about [[Manual_installation_of_mods|installing mods by hand]] if you plan to make such edits.
As the Package Manager prepares this list, it has made a backup of php files for the forum (please see the [[A mod broke my forum‎|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.
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 ==
== 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.
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 [[SMF1.1:Package_manager#Browse_Packages|Browse Packages]] section.


{{ {{Localized|Version specific}}|small=yes|version=1|content=
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.
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.
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.
{{ {{Localized|Version specific}}|small=yes|version=2|content=
== File Permissions ==
You can use this section to review the writable status of critical files and directories within your forum directory. Note this only considers key forum directories and files - use an FTP client for additional options.
Please Note:
#Be careful when changing file permissions from this section - incorrect permissions can adversely affect the operation of your forum!
#On some server configurations selecting the wrong permissions may stop SMF from operating.
#Certain directories such as attachments need to be writeable to use that functionality.
#This functionality is mainly applicable on non-Windows based servers - it will not work as expected on Windows with respect to permission flags.
#Before proceeding make sure you have an FTP client installed in case you do make an error and you need to FTP into the server to remedy it.
#If you make changes to your file permissions and they do not seem to be having the effect that you expected, you will need to contact your host, asking them if you have '''full ownership''' of all of the files on your site. Do not worry, if you do not know what that means, exactly, because your host certainly will.
===Change File Permissions===
'''Apply individual file permissions settings selected above''':
:''If "Custom" has been selected use chmod value of: You can manually set the permissions you wish to set the selected files to. To do this enter the chmod value as a numeric (octet) value. Note - these flags will have no effect on Microsoft Windows operating systems.''
'''Use predefined permission profile''': this only applies the predefined profile to key SMF directories and files.}}


== Options ==
== Options ==
Line 121: Line 79:
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.
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.


{{ {{Localized|Version specific}}|small=yes|version=1|content=
===Cleanup Permissions===
===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 writable''; ''All files are writable''; and ''Only the standard files are writable''. Choose one of these options and then selecting the Change file permissions button below makes the change.
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===
===FTP Information Required===
Line 136: Line 93:
The [[Local Path - What is the local path to SMF|What is the local path to SMF?]] FAQ has more information.
The [[Local Path - What is the local path to SMF|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.}}
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.


{{ {{Localized|As an administrator}}}}
{{ {{Localized|As an administrator1.1}}}}

Latest revision as of 20:29, 11 August 2016

Please see SMF1.1:Package manager or SMF2.0:Package manager depending on the version of SMF you are using.

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. For more information about Uploading packages using FTP, see Packages - How to upload packages 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.




Main

Configuration

Forum

Members

Maintenance

Miscellaneous


Retrieved from "https://wiki.simplemachines.org/w/index.php?title=SMF1.1:Package_manager&oldid=30735"


Advertisement: