Installation Guide Part 1

This guide describes the steps for manually installing Foswiki, with specific steps for installations on Linux with the Apache web server. If you are using a different web server or operating system, in addition to reviewing this document, check any additional information specific to your platform at Foswiki:Support.SupplementalDocuments. Foswiki:Support.SupplementalDocuments also has information for other scenarios, such as shared web hosting environments.

These installation instructions are also available online at Foswiki:System.InstallationGuide, and are available within your Foswiki installation at System.InstallationGuide (the InstallationGuide topic in the System web).

For information on upgrades, please also refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, UpgradeGuide.html, is included in the root of your Foswiki distribution.

On this page:

Initial Installation

System Requirements

Please see the section "Foswiki system requirements" for the server and client requirements to run Foswiki, including the Perl modules required on the server. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.

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 a 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).

If you are upgrading from a previous Foswiki version or from a TWiki installation, please refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, UpgradeGuide.html, is included in the root of your Foswiki distribution.

Verify that your server meets the Foswiki system requirements, including having the minimum required Perl version and all required Perl modules installed. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.

If you need help, feel free to ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

Basic installation: getting Foswiki up and running

To install Foswiki, complete the following steps:

  1. Download and unpack the Foswiki distribution.
  2. Set the file and directory permissions for the installation.
  3. Configure the locations of the Perl executable and the Foswiki modules.
  4. Configure the web server.
  5. Configure Foswiki.
  6. Enable authentication of users (if desired).
  7. Define the administrator users.

Download and unpack the Foswiki distribution

Download the Foswiki distribution from http://foswiki.org/Download

Unpack the distribution file: Change to the directory where 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 subdirectory to a shorter name. For the rest of this document, this subdirectory is assumed to be at /path/to/foswiki.

If you do not have shell access to your web server host, see the section "Uploading the Foswiki distribution to your web server host".

Set the file and directory permissions for the installation

Set up access file and directory rights, as well as file ownership, as required by your web server configuration so that the web server user (the user used by the web server to run CGI programs) can read and write within the foswiki directory tree.

Note: for more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.

The default file and directory access permissions as set by the distribution define a reasonable security level that will work for many types of installations, including shared hosting. Nonetheless, you should verify that the web server user has read access to all files and directories beneath the foswiki directory, and execute access for all directories. Also verify that the data and pub directories and all the subdirectories and files beneath them allow write access for the web server user.

It is possible to define tighter access permissions than the default ones; how tight they should be depends on your web server environment and local needs. Typically you should limit all access from others if the web server machine has login access for users other than root and the web server administrator. For a dedicated web server that just runs Foswiki and has limited login access, the default access permissions have a good safety level.

If you have root user permissions, then for additional security, you can change the ownership of the foswiki directory tree to the web server user, using the command chown -R user:group /path/to/foswiki. The web server username varies in different installations; here are some sample commands for various Linux distributions:

If Foswiki stops working after you applied a change in access permissions and you wish to restore the original permissions, run the Unix commands located at Foswiki:Support.SettingFileAccessRightsLinuxUnix.

(optional) Configure the locations of the Perl executable and the Foswiki modules

If you are running on a Linux system with Perl found in /usr/bin/perl then this step is not required. This step is required on Windows installations.

Find the location of your system's Perl interpreter. Change the path to Perl in the first line of each script (you may have to give yourself write permission first) in the bin and tools directories. You can use the tools/rewriteshebang.pl script to do this; 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.
cd /path/to/foswiki/tools
/path/to/perl rewriteshebang.pl

(optional) Configuration of a script suffix for the perl scripts

Some web servers require a special extension on perl script files (e.g. .cgi or .pl). This is not normally required with the Apache web server, though some hosted web servers are configured to require it. If the documentation for your web server indicates that a special extension is necessary, rename all the executable scripts in bin; that is, rename bin/view to bin/view.pl, and so on. When configuring Foswiki (see the section "Configure Foswiki"), set the ScriptSuffix option to the special extension.

(optional) Configuration for non-standard library locations

A standard Foswiki install has the directories bin/ and lib/ located under the Foswiki installation directory. If you have moved these directories, or if your system requires changes to the default Perl libraries, then this step is required.

Create the file LocalLib.cfg located at bin/LocalLib.cfg

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.

If you are using a config file:

If you are using a .htaccess file:

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. For example, most Linux distributions have a default Apache installation with PHP and server side include (SSI) enabled. This would allow PHP scripts uploaded as attachments to be executed, which is a security risk, so it should be disabled in the Apache configuration with php_admin_flag engine off.

Different script execution mechanisms are disabled in different ways; see your web server configuration and documentation for more details.

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.

To limit access to a particular user, set up a .htpasswd file that contains the user name and password that Apache will use to authenticate the user:

The Foswiki:Support.ApacheConfigGenerator tool and the sample config files and .htaccess files show how to configure Apache so that the configure web page will be protected using the user and password held in the data/.htpasswd file. The Apache config file or .htaccess file will have a Require user <username> directive to restrict access to the configure script. Ensure the user specified in the directive matches the <username> you used when creating the .htpasswd file.

Note: In addition to any web server security protection that you have set up, when saving any configuration settings for the first time on the configure web page, you will be prompted to set a configuration password. This password must be entered on all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)"). Even after a configure password has been set, access to the configure page should still be restricted by the web server, in order to avoid revealing internal information to potential attackers.

For more information, refer to Foswiki:Support.ProtectingYourConfiguration.

Configure Foswiki

Run the configure script from your browser: enter http://yourdomain/url/to/foswiki/bin/configure into your browser address bar.

If there is a problem with your setup that prevents you from accessing the configure page, you can configure Foswiki manually.

Authentication

Authentication of users means their activity can be tracked, and access to your site can be controlled. 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. They have the following relative advantages:

Note that the password databases for both of these authentication mechanisms are compatible, so you can switch between them at a later date.

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.

Template Login authentication
Template Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users. Users can choose to have their session remembered so they will automatically be logged in the next time they start their browser.

Enabling Template Login

By default, your Foswiki installation is probably already using TemplateLogin, HtPasswdUser and TopicUserMappingContrib as the default Login, Password and user mapping options.
  1. Using configure:
    1. Navigate to the Login tab on the Security and Authentication panel. Select the Foswiki::LoginManager::TemplateLogin login manager.
    2. Navigate to the Passwords tab. Select the appropriate PasswordManager for your system - the default is Foswiki::Users::HtPasswdUser.
      There is also an EXPERT configure setting {TemplateLogin}{PreventBrowserRememberingPassword} that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
  2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
    1. If you are reading this from the INSTALL.html file, you can enter System.UserRegistration into the 'Jump' box in the top right of any Foswiki page.
    2. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
    3. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
  3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
  4. Add users to the Main.AdminGroup. Edit the Main.AdminGroup topic in the Main web to include users that should have administrator status. Read defining adminstrator user(s) for more information.
    This is a very important step, as users in this group can access all topics, independent of Foswiki access controls.

AccessControl has more information on setting up access controls.

Foswiki AccessControls do not protect topic attachments unless the web server has been configured to do so using the viewfile script. Visit Foswiki:Support.ApacheConfigGenerator for examples using Apache.

As Template Login uses a wiki page for its login prompt, there is a great deal of flexibility in customizing the login page for your purposes.

The default new user template page is in System.NewUserTemplate. The same macros get expanded as in the template topics. You can create a custom new user topic by creating the NewUserTemplate topic in Main web, which will then override the default in System web. See System.UserForm for copy instructions.

Custom registration page

You can customize the default System.UserRegistration topic by first copying System.DefaultUserRegistration to UserRegistration in Main web. This will ensure that your changes will remain intact next time you upgrade.

A couple of common fields are hidden from normal view to make the registration page as lean as possible. You can unhide those fields on the page by removing EXCLUDED_ from the INCLUDE tags) or add new ones.

New fields may also be added. The name="" parameter of the <input> tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.

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.

The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap or mod_auth_mysql you can just plug in to them directly.

The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.

Foswiki maps the REMOTE_USER that was used to log in to the webserver to a WikiName using the table in Main.WikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).

The same private .htpasswd file used in Foswiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.

Do not use the Apache htpasswd program with .htpasswd files generated by Foswiki! htpasswd wipes out email addresses that Foswiki plants in the info fields of this file.

Apache Login is required for Apache-based login methods such as mod_ldap

You can use any Apache authentication module that sets the REMOTE_USER environment variable.

To setup Apache Login, perform the following steps:

  1. Configure Apache Login. Under the Security and Authentication pane on the Login tab in configure:
    1. Select Foswiki::LoginManager::ApacheLogin for {LoginManager}.
    2. Select Foswiki::Users::HtPasswdUser for {PasswordManager}.
    3. Select Foswiki::Users::TopicUserMapping for {UserMappingManager}.
    4. Save your settings.
    5. 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.
  2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
    1. If you are reading this from the INSTALL.html file, you can enter System.UserRegistration into the 'Jump' box in the top right of any Foswiki page.
    2. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
    3. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
  3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
  4. Add users to the Main.AdminGroup. Edit the Main.AdminGroup topic in the Main web to include users that should have administrator status. Read defining adminstrator user(s) for more information.
    This is a very important step, as users in this group can access all topics, independent of Foswiki access controls.

Choose an appropriate search algorithm for your Operating System

On the Store pane in configure you will find the setting {RCS}{SearchAlgorithm}.

By default it is set to Foswiki::Store::SearchAlgorithms::Forking which is what you should keep if you install Foswiki in Linux or any other Unix type operating system.

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.

Define the administrator user(s)

About Administrators

Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. The special user Main.AdminUser ships with Foswiki and is accessed using by logging in with user admin and the password established when initially saving the configuration. Don't log in with the wikiname AdminUser.

After installing Foswiki, you can also register other users that you will use to administer Foswiki. To make a user an administrator, add the WikiName for the user to the AdminGroup, defined in the Main.AdminGroup topic in your Foswiki installation.

Note that with the sudo or internal admin login, it is not necessary to add other users to the AdminGroup. However if you have more than one administrator, you may still want to do this to ensure that topic changes are attributed to a specific user instead of the default Main.AdminUser.

By adding users to Main.AdminGroup:

By using the internal admin login:

Adding users to the Main.AdminGroup
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.

To add an initial administrator to the AdminGroup, perform the following steps:

Any member of the Main.AdminGroup 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. See System.AccessControls for more information on access controls and user groups.

Congratulations!

You now have a basic installation running. At this point you can just point your Web browser at http://yourdomain.com/url/to/foswiki/bin/view/System/InstallationGuidePart2 to proceed with further tailoring your site..

In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See System.ManagingWebs for more information on Wiki webs and how to create one.

Troubleshooting

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, which is supported on Microsoft Windows as well as Unix and Unix-like systems (including Linux and OSX), 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.8 or higher is recommended and it will run with Perl >=5.8.4 and <5.8.8 but this is untested. It also runs 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.

CPAN modules

Most of the CPAN libraries used by Foswiki are part of a standard Perl installation >=5.8.8 (recommended). A version >=5.8.4 and <5.8.8 will also work although untested. Please see Foswiki:Support.HowToInstallCpanModules for detailed information on how to install any CPAN libraries not yet present in your installation.

A more complete module status is listed in Foswiki configure (Foswiki 1.0.x: CGI Setup, 1.1.x: Web Server Environment > Perl modules). It should be easier to deal with CPAN modules from this perspective.

The following CPAN modules are shipped with Foswiki, require a comment or may optionally be needed. In case the standard Foswiki will be enhanced with Foswiki:Extensions, please look at the related extension page for dependencies which may require additional modules.

Module Preferred version Required/Optional Description
Algorithm::Diff   Required Included with Foswiki
CGI Versions 2.89, 3.37, 3.43, and 3.47 must be avoided. Most versions from 3.15 and onwards should work. Required Included with Perl core since Perl 5.4
Error   Required Included with Foswiki
Apache::Htpasswd   Optional May be required for ApacheHtpasswd password manager
Archive::Tar   Optional May be required by the Extensions Installer in configure if command line tar or unzip is not available, since Perl 5.9.3 part of core.
Archive::Zip   Optional Alternative to Archive::Tar, used by the Extensions Installer if Archive::Tar also unavailable
CGI::Session   Optional Required for Sessions support, available from the CPAN archive
Digest::SHA   Optional May be required for password encryption, since Perl 5.9.3 part of core
Digest::SHA1   Optional  
Encode::compat   Optional May be required for international characters
HTML::Entities   Optional Required for Foswiki:Extensions.WysiwygPlugin
HTML::Parser   Optional Required for Foswiki:Extensions.WysiwygPlugin
Lingua::EN::Sentence   Optional May be required for generating new language files
Locale::Maketext::Lexicon >=0 Optional Used for I18N support
LWP   Optional Required for the Configure Extensions Installer, and for external URL based INCLUDEs
URI   Optional Required by the configure script
Win32::Console   Optional May be required for Windows

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 -le 'use ModuleName; print "ModuleName"->VERSION'

Client requirements

Browser clients must support the following capabilities:

Most skins also require CSS and Javascript support. There is a low-fat skin (Plain) 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.

Uploading the Foswiki distribution to your web server host

If you cannot unpack the Foswiki distribution directly in your installation directory, you can unpack the distribution on your local computer, manually create the directory structure on your host server and upload the files as follows:

Configuring Foswiki manually (without using the configure page)

It is highly recommended that you configure Foswiki by using your browser to access the configure page. However, if you are unable to get the configure page to display (for example, if a dependency is missing), or for some reason you do not wish to use the configure page, then you can configure Foswiki manually

Perform the following steps to manually configure Foswiki:

Related Topics: InstallationGuidePart2, AdminDocumentationCategory, Foswiki:Support.SupplementalDocuments

TWiki is a registered trademark of Peter Thoeny.