Installation Guide Part 2
Post-Installation Configuration and Tuning
Once you have Foswiki installed and running, you can perform one or more of the following steps to tailor your installation to your needs. While most are optional, many of these will enhance your Foswiki installation's features and performance.
Set Foswiki Site Preferences
Preferences for customizing many aspects of Foswiki are set by editing
SitePreferences
. On that page you'll find some of the most common local site preferences such as the name for your site, the header logo image and, site tag line. However, there are many more site preference settings which you'll find in
DefaultPreferences
. If a given preference is
not set in
SitePreferences
, then it defaults to the value is defined in
DefaultPreferences
(or in the case of
extensions, in the respective extension topics).
Because
DefaultPreferences
is included in Foswiki upgrade packages, you will simplify upgrades by
not changing these
DefaultPreferences
. Instead,
copy any settings you want to change and add them to
SitePreferences
.
Automating Routine Tasks
Several Foswiki "house-keeping" tasks occur on daily basis and can be combined into a cron job (or equivalent). Here's a sample cron job that would combine the schedules for email notification, removal of expired sessions, and gathering of site statics:
0 0 * * * cd /usr/local/foswiki && perl -I bin tools/mailnotify -q
0 0 * * * cd /usr/local/foswiki/bin; ./statistics -subwebs 1 >/dev/null 2>&1
0 0 * * 0 cd /usr/local/foswiki/bin && perl ../tools/tick_foswiki.pl
Read further below about how to customize these schedules and script options to your particular needs. You can find some general information about cron jobs at
MailerContrib - Setting up a cron job.
Enable Email Notification
Each web has an automatic email notification service that sends you an email with links to all of the topics modified since the last alert. To enable this service:
- Confirm the Mail and Proxies settings on the
configure
page.
- Setup a cron job (or equivalent) to call the
tools/mailnotify
script, as described in the MailerContrib topic.
- To enable S/MIME signatures on notification emails, see instructions below.
Enable Site Statistics
You can manually or automatically generate a listing of the most popular pages for each web (based on number of visits) and most active editor (based on number of topic saves). For information on setting up this feature, see the
SiteToolStatistics topic.
Automate removal of expired sessions and lease files
By default Foswiki cleans out expired session and lease files each time any topic is viewed, but this has a performance cost. Instead you may wish to schedule a cron job (or equivalent) to run the
tools/tick_foswiki.pl
script, and set a negative value on the
configure
page for
{Sessions}{ExpireAfter}
. For more details, read
CommandAndCGIScripts.
Site Security
Select the desired security level
Foswiki has a many security features that can be enabled/disabled and adjusted to suit your needs.
In many cases enabling a security feature prevents other features. It is a balance that the administrator has to choose depending on the purpose of the Foswiki installation (confidential vs public knowledge), the type of installation (intranet vs internet), and your type of business.
A new administrator is encouraged to read
Foswiki:Support.SecurityFeatures which gives a walkthrough of the different security aspects and how to set the appropriate configuration settings. Note that that some security settings are only visible in configure in "expert mode" which you enter by clicking the "Show expert options" button at the top of the configure screen.
Enable Signed Email Notification
Foswiki administrative emails are an attractive target for SPAM generators and phishing attacks. One good way to protect against this possibility to enable S/MIME signatures on all administrative e-mails. To do this, you need an an X.509 certificate and private key for the the
{WebMasterEmail}
email account. Obtain these as you would for any other S/MIME e-mail user.
To enable Foswiki to sign administrative e-mails:
- Enable e-mail as described above
- Ensure that the system has the CPAN module
Crypt::SMIME
installed.
- If necessary, convert your certificate and key files to PEM format ( openssl has all the necessary utilities)
- Place the certificate anyplace convenient that the webserver can read. It should be protected against write. The conventional place under linux is
/etc/pki/tls/certs
- Place the key file in a secure location that only the webserver (or CGI user) can read. It must not be readable by anyone else, and must not be served by the webserver.
- Using the
configure
script, change the following settings under Mail and Proxies:
- "Email Server" tab. Follow the directions under
{MailMethod}
and {MailProgram}
to enable an external mail program such as sendmail. Net::SMTP
is not supported.
-
{SMTP}{MAILHOST}
, {SMTP}{SENDERHOST}
, {SMTP}{Username}
and {SMTP}{Password}
are not used an may be deleted.
- If Foswiki variable
SMTPMAILHOST
is defined in SitePreferences
it should be removed.
- "S/MIME" tab:
- Enable the S/MIME checkbox
- Enter the full path to the certificate file in the
{SmimeCertificateFile}
configuration variable
- Enter the full path to the private key file in the
{SmimeKeyFile}
configuration variable
- Save the configuration
- Re-run the
configure
script an resolve any errors that it identifies
All out-going administrative e-mails will now be signed.
Enable Localisation and Multilingual Interface
Foswiki supports displaying national (non-ASCII) characters, and using different languages for its basic interface elements. To configure localisation, modify the
Localisation
section of the
configure
page. For more information, see
Foswiki:Support.InternationalizationSupplement.
Choose an appropriate search algorithm for your Operating System
On the
Store
pane in
configure
you will find the setting
{Store}{SearchAlgorithm}
.
By default bootstrap attempts to pick the best implementation for your system. You can optimize search by choosing algorithms as follows:
- Windows servers and mod_perl installations should choose
Foswiki::Store::SearchAlgorithms::PurePerl
- Linux or any other Unix type operating system not using
mod_perl
, can set this to Foswiki::Store::SearchAlgorithms::Forking
.
- If for some reason grep / egrep is not found on default path, bootstrap will choose PurePerl. You can still use Forking search if desired by manually setting the paths to
grep
and egrep
in the configuration.
If you install Foswiki on a Windows server, using an external grep program can create problems because of limitations in the length of command lines. You may be able to run with Forking in Windows if your directory path to Foswiki is kept short (short directory names and few levels), however the recommended (safe) setting for Windows is
Foswiki::Store::SearchAlgorithms::PurePerl
.
There are several other options available for search tools via the
Extensions web, including:
Web Acceleration (mod_perl, FastCGI, …)
Foswiki is installed by default supporting standard CGI scripts as well as CLI access. For best performance, Foswiki can be accelerated using one of the several accelerators, however,
you must install the required dependencies before enabling acceleration! See the listed extensions for more information.
Caution
- Foswiki 2.0 can be "bootstrapped" with either of these accelerators active, however it is often simpler to initially configure Foswiki using CGI.
- The ApacheConfigGenerator will help creating a valid configuration for these accelerators.
- Enabling the apache configuration without installing the pre-req modules will break your site!
- The core default extensions are well tested with web acceleration, other extensions can exhibit inconsistent behaviour when accelerated.
Page Caching
By default, Foswiki renders each page dynamically when the page is requested. If you anticipate a relatively high volume of page
views in comparison to users actively editing the site, you may want to consider
PageCaching which can significantly improve the performance of a Foswiki site. To learn more about how to configure and fine-tune this feature, along with considerations for maintaining dynamic page elements, refer to
PageCaching.
Customizing your site's "look and feel"
Customize pages for managing personal information
If you are not using Foswiki to manage your users' passwords or email addresses, or would just like to enhance the default pages, then modify the following topics accordingly with information appropriate for your site:
Customize the user topic for new users
When a new user registers on your Foswiki site, a topic with a name corresponding to the user's WikiName is created in the Main web: this topic is the user's user topic. The user topic is based on the
NewUserTemplate topic; if it is not present, then
NewUserTemplate (and its associated
UserForm) is used as a default. If you want to customize the user topic for your users, copy
NewUserTemplate to
NewUserTemplate, and
UserForm to
UserForm, and make your changes to
NewUserTemplate and
UserForm. (See
ManagingTopics for instructions on copying a topic.)
You can edit these topics to suit your needs, such as the following:
- Customize the user topic for your site.
- Add an
ALLOWTOPICCHANGE
preference setting to NewUserTemplate so only the user can edit their own user topic. In particular, on a public Foswiki site, restricting edit access will avoid vandalism and spam.
- Add and remove fields defined in the UserForm. In particular, soliciting URL information for new users is an invitation for spam registrations.
If you added or removed fields from the user form you may also need to tailor
UserRegistration to match (copy over the contents from
UserRegistration to
UserRegistration when creating it).
Customize the appearance of your Foswiki site
The real power of Foswiki lies in its flexibility to be customized to meet your needs. To change the look of the default skin, PatternSkin, please refer to
PatternSkin and
PatternSkinCustomization.
At the
Foswiki website you can find more resources. A good place to start exploring is
Foswiki:Support.BestPracticeTips and
Foswiki:Support.FAQ which offer tips and tricks for customizing your Foswiki site. Many of these are best done before any content has been added to your site, so immediately after installation is a good time to consider the possibilities.
Left, Top and Bottom Bars with PatternSkin
The top bar and bottom bar are common across all webs.
To customize the top bar, copy
WebTopBarExample to
WebTopBar, and make your desired changes to
WebTopBar.
To customize the bottom bar, copy
WebBottomBarExample to
WebBottomBar, and make your desired changes to
WebBottomBar.
The side bar can be customized on a per web basis. To customize the side bar, copy the WebLeftBarExample topic in the given web to WebLeftBar, and make your desired changes to WebLeftBar. If you would like to move the side bar to the right of the page, see
PatternSkin for more details.
See
PatternSkinCustomization for detailed information on tailoring the look of your site.
Copyright, License and Classification Statements
At the bottom of each topic, there is a copyright statement that is set in the
WEBCOPYRIGHT
preference. Its default is the following:
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
If your Foswiki site is used in an environment without public access you should replace this with your normal copyright notice. You should also consider adding a security classification (e.g., For Internal Use Only) so people do not have to add this manually to every new topic.
If your Foswiki site is publicly accessible, you need to decide which copyright and license you wish to apply to all contributions. For open source applications, licenses such as
the GNU Free Documentation License,
FreeBSD Documentation License, and one of the various
Creative Commons licenses are possible licenses to consider. Remember that once people have started contributing, you cannot retroactively change the license (unless it has a provision for this).
To change the copyright statement, perform the following steps:
- Copy the
WEBCOPYRIGHT
preference setting from DefaultPreferences to Main.SitePreferences
. Change the value to your desired text. This value will be your new default across all webs.
- You can create a unique message for a specific web by setting the
WEBCOPYRIGHT
preference in the WebPreferences
topic for the given web. For example, you could add a confidential classification to a web that has restricted access.
- The
WEBCOPYRIGHT
preference setting in WebPreferences covers the documentation that comes with Foswiki, and should not be changed.
In Foswiki, the
WYSIWYG editor is used by default in edit mode. An
Edit wiki text link is available for those who prefer to edit the topic markup language (TML) directly.
There are actually two different
wiki text editors available now on Foswiki 2,0:
- NatEdit, The "Natural Editor"
- This is the new JavaScript enabled wiki text editor. This editor allows the user to directly edit the TML, but provide a JavaScript assist, to help in learning TML.
- raw editor
- This is the original wiki text editor included with Foswiki 1.0 and 1.1. It can be used without JavaScript, provided that Security & Authentication Validation tab is configured for embedded or none. The raw editor can be enabled per user by overriding the SKIN, and removing
natedit
from the default setting natedit, pattern
in their user topic: * Set SKIN = pattern
If you prefer to use the wiki text editor by default and have a separate
WYSIWYG button, then you can modify the templates that define the edit screen as described in
Foswiki:Support.FaqHowToMakeRawEditDefault.
Extensions
Foswiki:Extensions is an extensive library of
Plugins for Foswiki that enhance functionality in a huge number of ways. A few plugins are pre-installed in the Foswiki distribution. There are several types of Extensions available:
- Plugins extend Foswiki functionality without altering the core code.
- Skins Skins overlay regular templates to give different looks and feels to Foswiki screens.
- Contribs and AddOns are any other Extension that provides added functionality beyond Plugins and Skins
Installing extensions
Extensions can be installed using any of several different methods:
- the configure web interface under the Extensions tab
- the generic shell installer
tools/extension_installer
- by manually downloading the attachments from the Foswiki:Extensions web
- And running the _installer
- Or by manually expanding the archive into the installation.
To update an extension, simply re-run the installer. If prompted, tell it to download fresh copies from the repository.
If the extensions installer is not run, (for example, installing using unzip, debian/RPM packages or git clone), you must run the
Plugins
wizard to import and save the new configuration settings.
- From the configure web interface, a warning message should be generated under Extensions tab, click the
Import extension settings
button.
- or from the CLI, run
tools/configure -wizard Plugins -save
- To auto-enable the extension, include
-args ENABLE=1
on the command.
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
configure → Extensions → Extensions operations and maintenance tab, and use the
[ 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
https://foswiki.org/. Additional documentation on Foswiki plugins can be found at
Foswiki:Support.PluginsSupplement.
- 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.
- If the extension is already installed, a backup is taken to the
working/configure/backup
directory
- Dependencies on other Extensions are automatically resolved and installed
- Dependencies are downloaded from the same archive where the Extension was found. No additional searching is performed.
- The Extension is installed.
- By default, unless a collsion occurrs with an existing file, the Extension's topics will not be checked in to the revision control system.
- 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: (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
- CPAN and other dependencies need to be manually resolved.
- 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)
Use this method to install a back-level version of an extension. Manually download the old archives and installer from the repository using the attachments dialog.
- 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.
- If scripts are included, the "shebang" line might need to be adjusted.
- It is critical to always run the Plugins merge wizard after manually installing any extensions, or updating any
"*.spec"
file.:
tools/configure -wizard Plugins -save
To automatically enable extensions, add -args ENABLE=1
to the command.
- 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
Removing (uninstalling) extensions
Caution: When removing an extension, no dependency checking is performed.
- Dependencies are not removed
- Other Extensions dependent on the removed extension may become non-operational.
The web and command line interfaces can be used to uninstall extensions. When an extension is removed, the following occurs:
- The
_installer
package is used to recover the manifest. If it cannot be found locally, it will be downloaded from the configured extension repository
- A backup of the previously installed files per the manifest will be taken to the
configure/working/backup
directory
- Note: If download of the
_uninstaller
was required, the backup will be made per the current installer's manifest. It is preferable to always save the _installer
modules.
- The Extension files along with any
,v
revision control files will be removed, including the _installer
.
- Any additional files saved locally are not removed.
- A complete log of the steps taken is saved in
working/logs/configure/[NameOfExtension]-yyyymmdd-hhmmss-[Action].log
- The Plugin
{Module}
and {Enable}
settings will be removed from the configuration, and the configuration will be saved.
- Other settings from the Config.spec will be preserved.
Run the uninstall from the "root" of the Foswiki installation:
perl working/configure/pkgdata/SomeExtension_installer uninstall
Restoring a removed, or previous version of an extension
The backup can be extracted from the root directory of the Foswiki installation. The archive is taken "relative" to the root of the installation, so an
unzip
or
tar -xzf
of the backup file should be all that is required:
cd /root/of/foswiki
tar -zxvf * working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].tgz
# or
unzip working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].zip
Always run the
tools/configure -wizard Plugins -save
utility after manually changing any extension. This ensures that Foswiki is running with the
latest
Config.spec
/
Foswiki.spec
configuration information.
Related Topics: InstallationGuide,
AdminDocumentationCategory,
Foswiki:Support.SupplementalDocument