Installation Guide
The following is installation instructions for the Foswiki 1.0.0 production release on an Apache web server on Linux. Visit
Foswiki:Support.SupplementalDocuments for supplemental information on installing Foswiki or upgrading from TWiki, including notes on installing Foswiki on different platforms, environments and web hosting sites.
These installation instructions are also available online by following links from
Foswiki:Support.Foswiki01x00x00, and are available within your Foswiki installation at
System.InstallationGuide
(the InstallationGuide topic in the System web).
Preparing to install
Before attempting to install Foswiki, you are encouraged to review the
Foswiki:System.AdminSkillsAssumptions. This guide assumes the person installing Foswiki has, at a minimum, basic knowledge of server administration on the system on which Foswiki is to be installed. While it is possible to install Foswiki with FTP access alone (for example, on a hosted site), it is tricky and may require additional support from your hosting service (for example, in setting file ownership and installing missing perl CPAN libraries).
To help setup a correct Apache configuration, you are strongly encouraged to use the automatic
Foswiki:Support.ApacheConfigGenerator tool that generates an Apache config file based on the configuration options you choose.
While this installation guide specifically describes installation on an Apache web server on Linux, Foswiki can be installed on any web server and OS that meet the system requirements (see below). For additional notes on installing Foswiki on other systems, see
Foswiki:Support.SupplementalDocuments.
If you are installing Foswiki without root or administrator privileges (for example, on a hosted domain), see "
Notes on Installing Foswiki on Non-Root Account" for additional instructions beyond the basic steps presented below.
If you are upgrading from an earlier major version of Foswiki or from an old TWiki version such as Cairo (TWiki 3) you will need the information found in
Foswiki:System.UpgradeGuide. There is also a static HTML
UpgradeGuide.html
included in the root of your Foswiki distribution.
If you are upgrading from a TWiki 4 release, follow the steps described in
Foswiki:Support.UpgradingFromOlderTWikiReleases to ensure a safe upgrade without accidentally overwriting your site customizations and data.
One of the more difficult tasks is installing of additional CPAN libraries. See
Foswiki:Support.HowToInstallCpanModules for detailed information on how to install CPAN libraries.
If you need help, ask a question in the
Foswiki:Support web or on
Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki)
Basic Installation: getting Foswiki running
- Download the Foswiki distribution from http://foswiki.org/Download
- Unpack the distribution file: Change to the directory in which you want to place the Foswiki directory. Unzip or untar and gunzip the distribution; a new subdirectory called Foswiki-VERSION will be created. You can rename this directory to a shorter name. For the rest of this document, this subdirectory is assumed to have been renamed to
foswiki
.
- Note: Foswiki does not support directory paths that contain spaces, so ensure that all of its directory paths do not contain any spaces (particularly on Windows).
- Setup access file and directory rights to enable the webserver user (the user uesd by Apache to run the CGI programs) to read and write within the foswiki directory.
- Warning: Do not just run a
chmod -R 770 foswiki
. The access rules have different meaning for files and directories. This is the most common mistake installers make.
- The distribution tgz has the file and directory access rights setup to work with a reasonable security level that will work for all types of installations including shared hosting.
- The ownership of the foswiki directory tree is normally set to the user that unpacked the tgz and will have to be changed to the web server user using the command
chown -R user:group /path/to/foswiki
. The web server username varies from Distributions. Examples for some major distributions:
- RedHat, Fedora, CentOS, Gentoo, Mandriva :
chown -R apache:apache /path/to/foswiki
- debian/Ubuntu/Kubunto :
chown -R www-data:www-data /path/to/foswiki
- Suse :
chown -R wwwrun:www /path/to/foswiki
- If you mistakenly change the access rights in a way that makes Foswiki stop working, simply run the script found at Foswiki:Support.SettingFileAccessRightsLinuxUnix to set the access right of the entire Foswiki tree back to the distributed defaults.
- It is possible to define tighter access rules than the ones given by default after the installation is complete. But how tight they should be depends on your distribution and local needs. Typically you may want to limit all access from world if the web server machine has login access for other users than root and the web server administrator. For a dedicated web server made just for running Foswiki with limited login access the default access rights have a good safety level.
- Check the Perl installation. Ensure that Perl 5 and the Perl CGI library are installed on your system.
- The default location of Perl is
/usr/bin/perl
. If it's somewhere else, change the path to Perl in the first line of each script in the bin
directory. You can use the rewriteshebang.pl script in the tools directory. For example:
cd /path/to/foswiki/bin
/path/to/perl ../tools/rewriteshebang.pl
# At the prompt, enter the full path to the perl executable, including
# the full filename of the executable. You will be prompted twice for
# this information in order to confirm it.
- Some systems require a special extension on perl scripts (e.g.
.cgi
or .pl
). This is normally only needed under Windows and only where perl scripts are only recognized by file extension. Under Unix and Unix-like operating systems (including Linux), this is not required. If a special extension is necessary, rename all files in bin
; that is, rename bin/view
to bin/view.pl
, and so forth. When running the configure
tool (Step 7), set the ScriptSuffix
option to the special extension.
- Create the file LocalLib.cfg located as
bin/LocalLib.cfg
- In the bin directory, copy the template file LocalLib.cfg.txt to LocalLib.cfg . Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt.
- Edit
bin/LocalLib.cfg
so that $foswikiLibPath
is set to the absolute file path of your lib
directory. For example: /var/www/foswiki/lib
.
- If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set
$CPANBASE
to point to your personal CPAN install. Don't forget that the web server user has to be able to read those files as well.
- Configure the web server.
- First choose the best configuration method for your web server. With Apache, there are two ways to configure it: a config file included from httpd.conf or .htaccess files.
- Apache config file: The recommended method is using a config file. With a config file you can put the entire Foswiki configuration in ONE file (typically named
foswiki.conf
). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file is included from the main Apache config file http.conf. Most distributions have a directory from which any file that ends with .conf
gets included when you restart Apache (Example RedHat/Fedora/Centos: /etc/httpd/conf.d). If you use a virtual host setup in Apache you should include the foswiki.conf file from inside the desired virtual host config in your Apache configuration.
- .htaccess files: This should only be used when you cannot use a config file. Performance is slower as Apache must search through all applicable directories for any .htaccess files on each page access. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo priviledges.
- If you are using a config file:
- The easiest and best way is to use the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation, based on the options you choose in the tool.
- For a sample config file, see
foswiki_httpd_conf.txt
in the root of the foswiki installation.
- Note: you must restart Apache after making changes to your config files for the changes to take effect.
- If you are using an .htaccess file:
- In the root of the foswiki installation and in the
bin
directory, there are sample .htaccess
files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments.
- Protect the configure script
- You should never leave the
configure
script open to the public. Limit access to the bin/configure
script to either localhost, an IP address or a specific user using basic Apache authentication. The Foswiki:Support.ApacheConfigGenerator lets you setup who has access to the configure
script. Also see the foswiki-httpd-conf.txt or bin/.htaccess.txt file for an example of the setting required to protect the configure
script.
- If you limit the access to a particular user then you need to setup an .htpasswd file that contains the user name and password that Apache will use to authenticate the user. Both the Foswiki:Support.ApacheConfigGenerator tool and the sample config files and .htaccess files uses
data/.htpasswd
but this file does not exist until you have Foswiki running and have registered the first user, so you must manually create an .htpasswd file:
- Change to the
foswiki/data
directory.
- Issue the command
htpasswd -c .htpasswd <username>
, where <username> is the name of the user you will use to access the configure
script. Enter a password when prompted. Note this username cannot be used later on to register in Foswiki.
- When limiting access to a particular user, the Apache config file / .htaccess file will have a
Require user <username>
directive to restrict access to the configure
script. Note the user specified in the directive must match the <username> you entered in the .htpasswd file.
- Run the
configure
script from your browser (enter http://yourdomain/foswiki/bin/configure
into your browser address bar).
- Resolve any errors or warnings it tells you about.
- Note: When you run
configure
for the first time, you can only edit the section General Path Settings
. Save these settings, and then return to configure
to continue configuration.
- If your web server can be accessed by more than one domain name make sure to add the additional alternative URLs to
{PermittedRedirectHostUrls}
- When you return to
configure
you now need to setup Mail and Proxies. The {WebMasterEmail}
and {SMTP}{MAILHOST}
settings must be defined so Foswiki can send registration emails. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username}
and {SMTP}{Password}
. If you do not want to enable sending registration emails or want to enable it later you can uncheck {EnableEmail}
.
You now have a basic, unauthenticated installation running. At this point you can just point your Web browser at
http://yourdomain.com/foswiki/bin/view
and start using your Foswiki site!
Important Server Security Settings
Before you continue any further there are some basic and very important security settings you have to make sure are set correctly.
- As described in Step 6 of "Basic Installation", you should protect the
configure
script from general access. The configure
script must be restricted to use by administrators only, using your web server access control mechanisms. When accessing the configure
URL for the first time, you should save at least one setting and set a configuration password at this time. Even after a configuration password has been set, you should still keep access to the configure
script restricted, to avoid revealing internal details about your web server.
- You absolutely must turn off any kind of PHP, Perl, Python, Server Side Includes, or other software execution mechanisms supported by your web server in the
pub
directory. Most Linux distributions have a default Apache installation with PHP and server side include (SSI) enabled; make sure you disable this in the pub
directory.
Foswiki has some built-in protection: it renames files with dangerous filenames by appending .txt to the filename. However you must not rely on this to protect your server.
- Make sure that you deny access to all foswiki subdirectories other than the
bin
and pub
directories, as described in Step 6 of "Basic Installation". The sample foswiki_httpd_conf.txt
and subdir-htaccess.txt
files show how to configure Apache to deny access to these subdirectories, and the Foswiki:Support.ApacheConfigGenerator tool will generate the appropriate settings automatically.
Beyond the basic installation
Once you have Foswiki installed and running, you can perform one or more of the following steps to tailor your installation to your needs. Many of the references in this section refer to topics within your Foswiki installation. For example,
System.Skins
refers to the
Skins
topic in your System web. To go directly to a topic, enter the full topic name, such as
System.Skins
, into the "Jump" text box at the top right of any Foswiki page.
To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering
System.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
All of the Foswiki documentation can also be found online in the
Foswiki documentation section (the "System" web) of the Foswiki web site.
Note the
configure
page mentioned in this section is accessible via your web browser at
http://yourdomain/foswiki/bin/configure .
Enable authentication of users
By enabling authentication, you can control access to your site and track the activity of your users.
This is particularly important for sites that are publicly accessible on the web. You are strongly encouraged to read
System.UserAuthentication and
Foswiki:Support.UserAuthenticationSupplement for further information about managing users and access controls for your Foswiki site.
The most common authentication methods used for public Foswiki installations are Template Login and Apache Login.
Template Login authentication
With Template Login enabled, when Foswiki needs to authenticate the user, it will redirect to a login web page. A list of all users is shown in the
System.WikiUsers? topic. Internally, Foswiki stores the users and passwords using the Apache htpasswd utility.
To setup Template Login, perform the following steps:
- Configure Template Login. Under the
Security Settings
pane of the configure
page:
- Select
Foswiki::LoginManager::TemplateLogin
for {LoginManager}
.
- Select
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
- Select
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
- Save your settings.
- Verify that registration works. Register yourself using the System.UserRegistration topic.
Check that the password manager recognizes the new user by verifying that a new line is added to the foswiki/data/.htpassswd
file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on foswiki/data
or foswiki/data/.htpasswd
may not be set to allow the web server user to modify the file.
- Check that authentication works. Edit a topic by clicking on the
Edit
link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.
As Template Login uses a web page for its login prompt, there is a great deal of flexibility in customizing the login page for your purposes.
Apache Login authentication
With Apache Login enabled, when Foswiki needs to authenticate the user, the standard HTTP authentication mechanism is used: the browser itself will prompt for a user name and password.
To setup Apache Login, perform the following steps:
- Configure Apache Login. Under the
Security Settings
pane of the configure
page:
- Select
Foswiki::LoginManager::ApacheLogin
for {LoginManager}
.
- Select
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
- Select
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
- Save your settings.
- Configure your Apache settings for HTTP authentication. Use the Foswiki:Support.ApacheConfigGenerator tool or the
foswiki/bin/.htaccess
file to set the following Apache directives on the bin
scripts:
<FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*">
require valid-user
</FilesMatch>
You can also refer to the sample foswiki_httpd_conf.txt
and bin/.htaccess.txt
files to see how the appropriate Apache directives are specified.
- Verify that registration works. Register yourself using the System.UserRegistration topic.
Check that the password manager recognizes the new user by verifying that a new line is added to the foswiki/data/.htpassswd
file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on foswiki/data
or foswiki/data/.htpasswd
may not be set to allow the web server user to modify the file.
- Check that authentication works. Edit a topic by clicking on the
Edit
link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.
Apache Login is required for Apache-based login methods such as mod_ldap.
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:
Define the administrator user(s)
Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. After installing Foswiki and registering a user, you should make the user an administrator by adding the
WikiName for the user to the
AdminGroup
, defined in the
Main.AdminGroup
topic:
- If you are not already logged in with your WikiName, then login.
- Go to the
Main.AdminGroup
topic and select the "internal admin login" link. Login using the password you set on the configure
page.
- After logging as the internal admin, edit the
Main.AdminGroup
topic. Follow the instructions on the page carefully and add your WikiName to the group.
- Test that you have been added successfully: On the
Main.AdminGroup
page, select the "Logout link" and logout from being the internal admin. Select the "Edit" link for the Main.AdminGroup
page. If you successfully added yourself as an admin user, you should see the edit page.
Once the
AdminGroup
is no longer empty, then any member of the group can add subsequent members — you do not have to use the internal admin login.
To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to the
AdminGroup
that you use only for administering your Foswiki site.
Set Foswiki Preferences
Preferences for customizing many aspects of Foswiki are set by editing
Main.SitePreferences
. If a given preference is not set in
Main.SitePreferences
, then a default value is picked up from
System.DefaultPreferences
, if present, or, for extensions, from the extension topics.
To simplify your upgrades, do not modify
System.DefaultPreferences
. Instead, copy any settings you want to change from
System.DefaultPreferences
to
Main.SitePreferences
.
To see the available preferences that can be set, look through
System.DefaultPreferences
.
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 System.MailerContrib topic.
Enable WebStatistics
You can manually or automatically generate a listing of the most popular pages for each web, based on number of visits. For information on setting up this feature, see the
System.SiteTools 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. This has a performance cost, however. 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
System.CommandAndCGIScripts#tick_foswiki_pl.
Enable Localisation
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.
Customize the home topic for new users
When a new user registers on your Foswiki site, a home topic is created for the user based on the
System.NewUserTemplate topic (and its associated
System.UserForm). If you want to customize the home topic for your users, you should copy
System.NewUserTemplate
and
System.UserForm
to
Main.NewUserTemplate?
and
Main.UserForm?
, so you will not lose your customizations the next time you upgrade Foswiki. Your versions in the Main web will override the default versions in the System web.
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
Main.NewUserTemplate?
so only the user can edit their own home topic. We do not encourage this for Intranet sites as it sends a wrong signal to new users, but it can be necessary on a public Foswiki site to prevent spam.
- Add and remove fields defined in the
Main.UserForm?
.
If you added or removed fields from the user form you may also need to tailor
Main.UserRegistration?
to match (again, copy over the contents from
System.UserRegistration).
Install plugins
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.
In the
Plugins section of the
configure
page, you can select the
Find More Extensions button to download and install additional plugins 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.
Plugins are activated in the
Plugins section of the
configure
page. In addition, some plugins are also configured in this section.
TWiki Compatibility
Foswiki is 100% backwards compatible with TWiki markup up to and including TWiki 4.2.4.
To support a seamless transition to TWiki, Foswiki ships with a plugin called
TWikiCompatibilityPlugin
. This plugin enables most TWiki extensions to work without modifications with Foswiki. It also maps requests for legacy TWiki web topics to their Foswiki equivalents, as defined in
Foswiki:Development.TopicNameMappingTable. The TWIKIWEB and MAINWEB TWiki variables are also mapped to the new Foswiki macros SYSTEMWEB and USERSWEB.
If you are not upgrading an existing TWiki installation and do not plan to install plugins from the TWiki web site, it is recommended that you disable the TWikiCompatibilityPlugin in the
Plugins Section on the
configure
page.
If a plugin exists both in a TWiki version and a Foswiki version, it is strongly recommended that you use the Foswiki version, as this is coded to work optimally with Foswiki. As part of the creation of the Foswiki project, the Foswiki community is evaluating all of the extensions that are available for TWiki, and porting them over to the Foswiki name space. Many of them are being enhanced through the removal of bugs and security vulnerabilities, resulting in better, more functional plugins for Foswiki.
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
System.PatternSkin and
System.PatternSkinCustomization.
At the
Foswiki website you can find more resources. A good place to start exploring is the
Foswiki:Support.AdministratorsCookBook which offers 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
System.WebTopBarExample
to
System.WebTopBar?
, and make your desired changes to
System.WebTopBar
.
To customize the bottom bar, copy
System.WebBottomBarExample
to
System.WebBottomBar?
, and make your desired changes to
System.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
System.PatternSkin for more details.
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 a commercial application 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 accessible publicly, 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
System.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
System.WebPreferences
covers the documentation that comes with Foswiki, and should not be changed.
WYSIWYG vs Raw Edit
In Foswiki 1.0.0, the WYSIWYG editor is used by default in edit mode. An
Edit Raw link is available for those who prefer to edit the raw topic text.
If you prefer to use the raw text editor by default and have a separate WYSIWYG button, as in TWiki 4.1, then you can modify the templates that define the edit screen as described in
Foswiki:Support.FaqHowToMakeRawEditDefault.
Troubleshooting
The first step is to re-run the
configure
script and make sure you have resolved all errors, and are satisfied that you understand any warnings.
Failing that, consult the resources you can find in
Foswiki:Support.SupplementalDocuments and
Foswiki:Support.AskedQuestions.
If you need help, ask a question in the
Foswiki:Support web or on
Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).
Appendices
Foswiki System Requirements
Foswiki is capable of running on a variety of operating systems and supporting a wide range of browsers, due to its minimal client and server requirements.
Server Requirements
Foswiki is written in Perl 5 and is supported on Microsoft Windows as well as Unix and Unix-like systems (including Linux), on which it uses a number of shell commands and
RCS (Revision Control System), a GNU Free Software package. It should be able to run on any server platform that meets the following requirements.
Resource |
Required Server Environment |
Perl |
5.8.4 or higher is recommended. Foswiki will run in perl 5.6.1 but only with Wysiwyg editor disabled. Wysiwyg requires Unicode support which is provided by perl 5.8.1 onwards. |
RCS |
5.7 or higher (including GNU diff ) Optional. Foswiki includes a pure perl implementation of RCS (RcsLite?) that can be used instead, at the cost of performance |
GNU diff |
GNU diff 2.7 or higher is required when not using the all-Perl RcsLite?. Install within the PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
Other external programs |
fgrep, egrep |
Cron/scheduler |
• Unix: cron • Windows: cron equivalents |
Web server |
Apache is well supported; for information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms. |
Required CPAN Modules
Most of the CPAN libraries listed below are part of a standard Perl installation. See
Foswiki:Support.HowToInstallCpanModules for detailed information on how to install any CPAN libraries not present in your installation.
The following Perl
CPAN modules are used by Foswiki:
Module |
Preferred version |
Algorithm::Diff (included with Foswiki) |
|
CGI |
Versions 2.89 and 3.37 must be avoided. Most version from 3.15 and onwards should work. |
CGI::Carp |
>=1.26 |
Config |
>=0 |
Cwd |
>=3.05 |
Data::Dumper |
>=2.121 |
Error (included) |
|
File::Copy |
>=2.06 |
File::Find |
>=1.05 |
File::Spec |
>=3.05 |
FileHandle |
>=2.01 |
IO::File |
>=1.10 |
Text::Diff (included with Foswiki) |
|
Time::Local |
>=1.11 |
You can check version numbers from the command line (replace "ModuleName" with the name of the module):
perl -e 'use ModuleName; print $ModuleName::VERSION."\n"'
Optional CPAN Modules
The following Perl modules may be used by Foswiki. See
Foswiki:Support.HowToInstallCpanModules for detailed information on how to install CPAN libraries.
Module |
Preferred version |
Description |
Archive::Tar |
|
May be required by the Extensions Installer in configure if command line tar or unzip is not available |
CGI::Cookie |
>=1.24 |
Used for session support |
CGI::Session |
>=3.95 |
Highly recommended for session support |
Digest::base |
|
|
Digest::SHA1 |
|
|
Jcode |
|
Used for I18N support with perl 5.6 |
Locale::Maketext::Lexicon |
>=0 |
Used for I18N support |
Net::SMTP |
>=2.29 |
Used for sending mail |
Unicode::Map |
|
Used for I18N support with perl 5.6 |
Unicode::Map8 |
|
Used for I18N support with perl 5.6 |
Unicode::MapUTF8 |
|
Used for I18N support with perl 5.6 |
Unicode::String |
|
Used for I18N support with perl 5.6 |
URI |
|
Used for configure |
Most of these modules will probably already be present in your installation. You can check version numbers with the
configure
script, or if you're still trying to get to that point, check from the command line (replace "ModuleName" with the name of the module):
perl -e 'use ModuleName; print $ModuleName::VERSION."\n"'
Client Requirements
Browser clients must support the following capabilities:
- HTML 3.2
- Cookie support enabled, if persistent sessions are required
Most skins also require CSS and Javascript support. There is a low-fat skin (Classic) that minimises these requirements. Some skins require newer browser version. The default skin (Pattern) is tested on IE 6, Safari, and Mozilla 5.0 based browsers (such as Firefox).
You can easily select a balance of browser capability versus look and feel. Try the installed skins in the
skin browser and more at
Foswiki:Extensions.SkinPackage.
Important note about Foswiki Plugins
- Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
- Note: Plugins included in the Foswiki distribution do not add requirements, except for the CommentPlugin which requires Perl 5.6.1.
Notes on Installing Foswiki on Non-Root Account
This section provides additional notes on installing Foswiki on a system where you don't have root or administrator privileges, such as on a shared hosting Web account, or on an intranet server maintained by someone else.
The following items provide supplemental information for the referenced step from the
Basic Installation section:
- Step 2: If you cannot unpack the Foswiki distribution directly in your installation directory, you can unpack the distribution on your local PC and then manually create the directory structure on your host server and upload the files as follows:
- Using the table below, create a directory structure on your host server
- Upload the Foswiki files by FTP (transfer as text except for the image files in
pub
directory.)
- Note: Don't worry if you are not able to put the
lib
directory at the same level as the bin
directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the bin/setlib.cfg
file (done in Step 2).
Foswiki dir: |
What it is: |
Where to copy: |
Example: |
foswiki |
start-up pages |
root Foswiki dir |
/home/smith/foswiki/ |
foswiki/bin |
CGI bin |
CGI-enabled dir |
/home/smith/foswiki/bin |
foswiki/lib |
library files |
same level as bin |
/home/smith/foswiki/lib |
foswiki/locale |
language files |
dir secure from public access |
/home/smith/foswiki/locale |
foswiki/pub |
public files |
htdoc enabled dir |
/home/smith/foswiki/pub |
foswiki/data |
topic data |
dir secure from public access |
/home/smith/foswiki/data |
foswiki/templates |
web templates |
dir secure from public access |
/home/smith/foswiki/templates |
foswiki/tools |
Foswiki utlilities |
dir secure from public access |
/home/smith/foswiki/tools |
foswiki/working |
Temporary and internal files |
dir secure from public access |
/home/smith/foswiki/working |
- Step 3: Files in the pub directory must be readable as a url. This means that directory permissions should be set to
755
(or 775
) and file permissions should be set to 644
(or 664
). If you can run a chmod
command, you can accomplish this in two quick steps by running these commands from the root direct:
-
chmod -R 755 pub
-
chmod 644 `find pub -type f -print`
- In addition, you should create a
.htaccess
file in the pub directory, using the template included in the root level of the distribution entitled pub-htaccess.txt
.
- Note: This setup does not provide for absolute security for Foswiki attachments. For more information, see Foswiki:Support.SecuringYourSite.
- Step 6: In order to run the configure script, create a file called
.htaccess
in the bin directory that includes the following single line: SetHandler cgi-script
. This informs the server to treat all the perl scripts in the bin directory as scripts.
For additional information about installing Foswiki on a hosted accounts, see
Foswiki:Support.InstallingOnSharedHosts
Installing Manually Without Configure
It is highly recommended to use run configure from the browser when setting up Foswiki. Configure does a lot of the hard work for you.
But there may be instances where you do not want to use configure or where configure simply won't run because of a missing dependency.
The manual steps you have to take are:
- Copy the file
lib/Foswiki.spec
to lib/LocalSite.cfg
- Remove the comment # in front of
$Foswiki::cfg{DefaultUrlHost}
, $Foswiki::cfg{ScriptUrlPath}
, $Foswiki::cfg{PubUrlPath}
, $Foswiki::cfg{PubDir}
, $Foswiki::cfg{TemplateDir}
, $Foswiki::cfg{DataDir}
, $Foswiki::cfg{LocalesDir}
, and $Foswiki::cfg{OS}
and make sure these settings have the correct values.
- Make sure to define at least these settings:
$Foswiki::cfg{LoginManager}
, $Foswiki::cfg{WebMasterEmail}
, $Foswiki::cfg{SMTP}{MAILHOST}
, $Foswiki::cfg{SMTP}{SENDERHOST}
.
Related Topics: AdminDocumentationCategory,
Foswiki:Support.SupplementalDocuments