Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Item9693: Update extensions documentation
  • Loading branch information
gac410 committed Jun 16, 2015
1 parent 52de18f commit e7f99a5
Showing 1 changed file with 34 additions and 60 deletions.
94 changes: 34 additions & 60 deletions core/data/System/InstallationGuidePart2.txt
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" comment="reprev" date="1429736137" format="1.1" reprev="1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1434477046" format="1.1" version="1"}%
%META:TOPICPARENT{name="InstallationGuide"}%
---+!! Installation Guide Part 2
---++!! Post-Installation Configuration and Tuning
Expand Down Expand Up @@ -187,12 +187,14 @@ Foswiki:Extensions is an extensive library of [[Plugins]] for Foswiki that enhan
Extensions can be installed using any of several different methods:
* the [[%SCRIPTURL{configure}%][configure]] web interface under the Extensions tab
* the generic shell installer =tools/extension_installer=
* by manually downloading the extension zip or tar file
* by manually downloading the attachments from the Foswiki:Extensions web
* And running the _installer
* Or by manually expanding the archive into the installation.
%X%Caution: Users of the debian =.deb= or =.rpm= packages should only use the system package tools when installing extensions.

The simplest way is to visit [[%SCRIPTURL{configure}%][configure -> Extensions -gt; Extensions operations and maintenance]] tab, and use the _[%T% search for extensions]_ button to download and install additional extensions from the foswiki.org website. If you are behind a firewall or your server has no access to the Internet, you can also install plugins manually. Installation instructions for each plugin are located in its corresponding topic on http://foswiki.org/. Additional documentation on Foswiki plugins can be found at Foswiki:Support.PluginsSupplement.

When installing an extension from the =configure= interface:
---+++++ When installing an extension from the =configure= interface:
* Even if available, local Extension installers and archives are not used
* The extension is downloaded from the configured archive
* The latest version of the Extension is always downloaded. There is no automatic means of downloading older versions.
Expand All @@ -204,72 +206,44 @@ When installing an extension from the =configure= interface:
* If previous topics or attachments are found, then the topic will be _checked in_ under the Administrators user id.
* If the topics or attachments are flagged as =!noci=, disabling checkin, they will still be checked in if existing revision control files are found, suggesting that local modifications have occurred.
* CPAN dependencies and other external packages are *not* resolved and should be resolved manually
* Plugins will be automatically enabled. Be sure to save your configuration to enable the Extension and apply the settings.

When installing extensions from the command line:
* The =_installer= package must be run from the root directory of the Foswiki installation.
* The Extension =_installer= module must be downloaded from the Extension repository. The extension archive will be downloaded if required.
---+++++ When installing extensions from the command line: (Internet access available)
* The generic =extension_installer= package must be run from the root directory of the Foswiki installation.
* =perl tools/extension_installer [SomeExtension] install=
* The [SomeExtension]_installer and archive will be downloaded if required.
* When the =_installer= is run, it will install the Extension and dependencies similar to the =configure= interface except:
* You will be given the option to use local archives if available in the root of the Foswiki installation
* You will be given the option to resolve CPAN dependencies after the Extensions and dependencies are installed.
* Any other dependencies still need to be manually resolved.

When using either the web or shell instalation tools:
* After installation, the Extension =_installer= module is saved in =working/configure/pkgdata=
* A complete log of the actions taken by the installer is saved in =working/logs/configure/[NameOfExtension]-yyyymmdd-hhmmss-[Action].log=

__Plugins must be manually enabled in the Plugins section of the =configure= page.__ In addition, some extensions also require configuration in this section.
* Plugins will be automatically enabled and the configuration saved. Add the =-noenable= option to save the configuration with the plugin(s) disabled.

---+++++ When installing extensions from the command line: (no Internet access)
* Manually copy the =[SomeExtension]_installer=, and =[SomeExtension].tgz= files into the Foswiki root.
* Alternatively, they can be copied into the =working/configure/download= directory.
* The =[SomeExtension]_installer= package must be run from the root directory of the Foswiki installation.
* =perl [SomeExtension]_installer install -o=
* Be sure to include the =-o= option to prevent the installer from downloading any dependencies.
* When the =[SomeExtension]_installer= is run, it will install the Extension similar to the =configure= interface except that you will be given the option to use local archives.
* Plugins will be automatically enabled and the configuration saved. Add the =-noenable= option to save the configuration with the plugin(s) disabled.

---+++++ Manual installation
* Most extensions can have their archives expanded from the root of the foswiki installation.
* If web and topic names are non-standard, files will need to be manually copied.
* The LocalSite.cfg file will need to be manually updated with:
* $Foswiki::cfg{Plugins}{SomePlugin}{Module}
* $Foswiki::cfg{Plugins}{SomePlugin}{Enable}
* ... and any settings copied from the extension's =Config.spec= file.

---+++++!! When using either the web or shell installation tools:
* The =[SomeExtension]_installer= module is saved in =working/configure/pkgdata=.
* The downloaded files are saved in =working/configure/download=.
* A complete log of the actions taken by the installer is saved in =working/logs/configure/[NameOfExtension]-yyyymmdd-hhmmss-[Action].log=.
* Backup of prior extension if any is saved in * =working/configure/backup/[NameOfExtension]-backup-yyyymmdd-hhmmss.tgz=.

The instructions for using the extensions installer from the shell are
retrieved by using the "usage" command: =tools/extension_installer usage= or
=./SomePlugin_installer usage=
<verbatim>
perl working/configure/pkgdata/X509UserPlugin_installer usage

Usage as a custom installer:

X509UserPlugin_installer -a -n -d -r -u -c install
X509UserPlugin_installer -a -n uninstall
X509UserPlugin_installer manifest
X509UserPlugin_installer dependencies

Usage as a generic installer:

tools/extension_installer X509UserPlugin -a -n -d -r -u -c install
tools/extension_installer X509UserPlugin -a -n uninstall
tools/extension_installer X509UserPlugin manifest
tools/extension_installer X509UserPlugin dependencies

If command (install, uninstall ..) is not provided, default is to
install the extension.

Operates on the directory tree below where it is run from,
so should be run from the top level of your Foswiki installation.

Depending upon your installation, you may need to execute perl directly
perl tools/extension_installer ... or
perl X509UserPlugin_installer ...

"install" will check dependencies and perform any required
post-install steps.

"uninstall" will remove all files that were installed for
X509UserPlugin even if they have been locally modified.

-a means don't prompt for confirmation before resolving
dependencies
-d means auto-download if -a (no effect if not -a)
-r means reuse packages on disc if -a (no effect if not -a)
-u means the archive has already been downloaded and unpacked
-n means don't write any files into my current install, just
tell me what you would have done
-c means don't try to use CPAN to install missing libraries

"manifest" will generate a list of the files in the package on
standard output. The list is generated in the same format as
the MANIFEST files used by BuildContrib.

"dependencies" will generate a list of dependencies on standard
output.</verbatim>

---++++ Removing (uninstalling) extensions

Expand Down

0 comments on commit e7f99a5

Please sign in to comment.