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.

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.

You should also take this opportunity to consider the automated installers, virtual machine images and (currently) Debian and CentOS packages at Foswiki:Download.OtherFoswikiInstallers. These automate much of the install process and may help some users get started more easily.

Note that the installers are optimized for the target system, and typically do not follow the normal Foswiki directory structure documented below. Files are installed into system locations that are appropriate to the target OS. Review the steps below, but recognize that file locations may be different, and some installation steps such as customization of the Web Server and Foswiki,setting file ownership and permissions will have been done automatically during the package installation.

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

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

(Not applicable on Windows) 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.
  • Warning: Do not just run a chmod -R 770 foswiki. Providing execute access to all files is potentially dangerous. This is a common mistake made by Foswiki installers. See Foswiki:Support.SettingFileAccessRightsLinuxUnix for a sample set of Unix commands to set the file and directory permissions.

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:
  • RedHat, Fedora, CentOS, Gentoo, Mandriva : chown -R apache:apache /path/to/foswiki
  • debian/Ubuntu/Kubuntu : chown -R www-data:www-data /path/to/foswiki
  • Suse : chown -R wwwrun:www /path/to/foswiki

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 - required on Windows ) 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.

The easiest way to fix up the bin scripts is to run the tools/rewriteshebang.pl script. If the Perl interpreter is in the default execution path, follow these steps:

cd /path/to/foswiki/tools
perl -I ../lib rewriteshebang.pl

or for Windows users:

cd C:\path\to\foswiki\tools
perl -I ..\lib  rewriteshebang.pl

The script will determine the location of the Perl interpreter and will prompt to update both the bin and tools scripts in a single step. The changed files will be reported, and it is safe to rerun the script.

If the perl command does not work from the command line, then you need to find the location of your system's Perl interpreter. Insert the path to Perl in the first line of the rewriteshebang script. For example:

cd C:\path\to\foswiki\tools
C:\path\to\perl -I ..\lib  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
  • 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: /path/to/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 can be included from the main Apache config file. (Typically httpd.conf or apache.conf depending on your distribution). However 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, Gentoo: /etc/apache2/vhost.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 method 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 privileges.

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.
  • If you can't use the online configuration generator, a sample config file called foswiki_httpd_conf.txt can be found in the root of the foswiki installation.
  • Ensure that web access is denied to all Foswiki subdirectories other than bin and pub.
  • Ensure there is either a ScriptAlias directive for the bin subdirectory, or an Alias directive with SetHandler cgi-script and Options ExecCGI directives for the bin subdirectory, so that the bin scripts will be executed by Apache.
  • Note: you must restart Apache after making changes to your config files for the changes to take effect.

If you are using a .htaccess file:
  • In the root of the foswiki installation, 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.
    location and name of sample .htaccess file copy sample file to the following location
    foswiki/root-htaccess.txt foswiki/.htaccess
    foswiki/bin-htaccess.txt foswiki/bin/.htaccess
    foswiki/pub-htaccess.txt foswiki/pub/.htaccess
    foswiki/subdir-htaccess.txt foswiki/<subdir>/.htaccess
    Copy to all other subdirectories below foswiki, including data, lib, locale, templates, tools, working. Copy to any other directories except for bin and pub addressed above.
  • Ensure that web access is denied to all Foswiki subdirectories other than bin and pub. The sample .htaccess files show how to configure Apache appropriately. It is important to verify that none of these directories can be directly accessed.
  • Ensure that the foswiki/bin/.htaccess files contains the line SetHandler cgi-script so that all scripts in the bin directory will be executed by Apache.
  • Note: On Linux systems, files named with the leading "." like .htaccess are hidden files and will not be listed unless using the -a option, ex. ls -la

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:
  • Caution! Do not follow these steps on an existing Foswiki .htpasswd file. It will destroy the email addresses stored in that file! If the file already exists, you can choose an existing user for access to configure.
  • 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. Choose the username with care: the username cannot be an existing login name for your Foswiki installation, nor can it be used later on to register in Foswiki. Enter a password when prompted.

All of the above methods - Sample configuration files, Foswiki:Support.ApacheConfigGenerator and sample .htaccess files, all include example settings to protect the configure script with a password. The critical section looks something like:
<FilesMatch "configure.*">
    SetHandler cgi-script
    Order Deny,Allow
    Deny from all
    # List of IP addresses allowed to access configure
    Allow from 127.0.0.1 192.168.1.10
    # specify username used on the "htpasswd" command above
    Require user someuserid
    # Set to "Any" to allow IP -or- userid,  set to "All" to require both match
    Satisfy Any
    ErrorDocument 401 default
</FilesMatch>

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.

Tip: You do not have to use the same password file for both Configure and for Foswiki user registration. If you use a separate file, you can create it using the htpasswd commmand and complete segregate configure access from Foswiki access. This is probably safer, but does not allow users to change their configure password using Foswiki services. The password file has to be manually maintained..
  1. Generate an alternate password file to protect configure. htpasswd -c -s /path/to/data/.htpasswd-admin configuserid
  2. Add / modify and delete this alternate file using the htpasswd command. Don't mix them up and use htpasswd on the Foswiki .htpasswd file!
  3. Edit the foswiki apache configuration and modify the block (shown above) that protects the configuration command. Add or modify the following statements in the block. Don't remove the other statements!
<FilesMatch "configure.*">
        AuthType Basic
        AuthName "admins only"
        AuthUserFile /path/to/data/.htpasswd-admin
        # Changing the Require user to Require valid-user allows any ID in the
        # file access to configure!
        Require valid-user
</FilesMatch>
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.
  • When you access the configure web page for the first time, you can only edit the section General Path Settings. Make any required changes, and save the settings, whether or not you needed to make any changes. You will be prompted to set a password for the configure page: this password must be entered for all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)").
    IDEA! Note: The configure password is remembered by configure, separate to web server access controls mentioned in "Protect the configure script".
  • After saving the General Path Settings, continue configuring Foswiki. Configuration items which may require further attention will be highlighted.
  • If the Foswiki installation can be accessed by more than one protocol://domain, ensure the additional alternative URLs are set in {PermittedRedirectHostUrls}.
    TIP Example: if {DefaultUrlHost} is set to https://wiki.company.com, an example {PermittedRedirectHostUrls} might contain:
    https://company.com, http://111.222.123.234
  • Setup the Mail and Proxies section. Email must be available so Foswiki can send registration emails.
    • Under the "Email General" tab, If you do not want to enable sending registration emails or want to enable it later you can uncheck {EnableEmail}. Otherwise the {WebMasterEmail} parameter must be configured.
    • Under the "Email Server" tab, you can choose 3 methods of sending email. This is explained in detail under the help text for this tab.
      • MailProgram is typically suitable on most Linux systems, and no further configuration is required.
      • If you chose either of the Net::SMPT methods, you must also configure {SMTP}{MAILHOST}. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username} and {SMTP}{Password}.
      • Net::SMTP::SSL will encrypt the connection to the e-mail server and is required for some email services like Google's GMail.
    • Under the "Proxy" tab, if your server is behind a firewall with a proxy, and you wish to install extensions via configure, you may have to set {PROXY}{HOST} and {PROXY}{PORT}.
      ALERT! Note: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the Mail and Proxies, Email Test tab in configure and verify that Foswiki can successfully send e-mail.
      SMTP authentication requires additional perl modules including Authen::SASL and MIME::Base64,

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:
  • Template Login can be set up without any web server configuration, and users can log off without restarting the browser. As the login page is just a Wiki page, you can customize it to suit your needs.
  • Apache Login allows you to use any Apache-module based authentication scheme, such as mod_auth_ldap or mod_auth_mysql. However, as your browser is caching your login, you must restart the browser to log out.

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 (or optionally e-mail address) 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

IDEA! 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, Security And Authentication tab
    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.
      HELP There is 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.
      HELP There is an EXPERT configure setting {TemplateLogin}{AllowLoginUsingEmailAddress} that you can set to allow users to login using their password system registered e-mail addresses.

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 rest of this section describes Webserver Login using the Apache web server, but the same process is applicable to other webserver implementations as well (though you may require a customised version of the ApacheLogin module to do it).

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 username is used for their signature) or register (in which case that username 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.

ALERT! Do not use the Apache htpasswd program to modify .htpasswd files generated by Foswiki! htpasswd wipes out e-mail addresses that Foswiki saves in the info fields of this file.

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

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

To set up 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-advanced.txt file to set the following Apache directives on the bin scripts:(This example is for Apache 2.2, there are changes required if using Apache 2.4)
       AuthType Basic
       <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|.*auth).*">
       require valid-user
       </FilesMatch>
      You can also refer to the sample foswiki_httpd_conf.txt and bin-htaccess-advanced.txt files to see how the appropriate Apache directives are specified.

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:
  • Users with Admin rights will have routine access to topics that might normally be denied.
  • These users will be unable to test or demonstrate access controls.
  • Changes made are always attributed to a unique logged in user.
  • Password sharing of the bin/configure password is not required

By using the internal admin login:
  • You don't need to grant admin rights to individual users
  • All users will be subject to access controls.
  • Changes made while using the internal admin login are attributed to Main.AdminUser
  • The "save" password for bin/configure will need to be shared among administrators

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:

  • 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, view the Main.AdminGroup topic. Follow the instructions on the page to add users to the AdminGroup. You do not need to edit the topic.

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

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 Unix-like systems, it uses a number of shell commands. It should be able to run out-of-the-box on any server platform that meets the following requirements.

Resource Required Server Environment
Perl 5.8.8 or higher. A minimum of perl 5.12 is recommended.
External programs GNU diff 2.7 or higher, fgrep, and egrep (not required on Windows)
Web server Apache, Nginx and Lighttpd are all well supported; Apache sample configs are provided. For information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms.

Foswiki is designed to automatically detect the platform and generate a basic configuration the first time the configure script is run, but start from your expected default "view" URL, so that Foswiki can figure out your URL scheme.

Prior versions of Foswiki shipped with the important CPAN modules. Foswiki 2.0 does not, and you must ensure that the perl dependencies listed below are installed before attempting to use Foswiki. For a detailed report, System.PerlDependencyReport (admin access only!) or the shell script tools/dependencies.

If you are unable to install CPAN modules, see Foswiki:Extensions.CpanContrib. Install this extension into your Foswiki installation directory if you cannot install Perl modules otherwise.

You can check the dependencies before Foswiki is fully operational with the following command. It will list all potentially missing dependencies. Not all listed dependences are required on all installations, Refer to the usage message that accompanies each missing dependency in the report.

cd /path/to/foswiki
perl tools/dependencies

Specific distribution details

Find the closest match to your installed system. and click on the "Show ..." link to reveal the details.

Ubuntu and other Debian derived distributions

Minimum requirements

Install apache and rcs: apt-get install apache2 rcs

Perl Module Package to install Notes
Algorithm::Diff libalgorithm-diff-perl  
Archive::Tar libarchive-tar-perl  
Authen::SASL libauthen-sasl-perl  
CGI libcgi-pm-perl  
CGI::Session libcgi-session-perl  
Crypt::PasswdMD5 libcrypt-passwdmd5-perl  
Digest::SHA libdigest-sha-perl *First shipped in perl 5.9.3
Email::Address libemail-address-perl  
Email::MIME libemail-mime-perl  
Encode libencode-perl  
Error liberror-perl  
File::Copy::Recursive libfile-copy-recursive-perl  
HTML::Parser libhtml-parser-perl  
HTML::Tree libhtml-tree-perl  
IO::Socket::IP libio-socket-ip-perl First shipped perl 5.19.8
IO::Socket::SSL libio-socket-ssl-perl  
JSON libjson-perl  
Locale::Maketext liblocale-maketext-perl  
Locale::Maketext::Lexicon liblocale-maketext-lexicon-perl Optional, needed for internationalization
Locale::Msgfmt liblocale-msgfmt-perl Optional, needed for internationalization
LWP libwww-perl  
LWP::Protocol::https liblwp-protocol-https-perl  
URI liburi-perl  
version libversion-perl Must be version 0.77 or newer, included with perl 5.10.1 and newer.

Note: to install all the above:
apt-get install libalgorithm-diff-perl libarchive-tar-perl libauthen-sasl-perl libcgi-pm-perl libcgi-session-perl libcrypt-passwdmd5-perl libdigest-sha-perl libemail-address-perl libemail-mime-perl libencode-perl liberror-perl libfile-copy-recursive-perl libhtml-parser-perl libhtml-tree-perl libio-socket-ip-perl libio-socket-ssl-perl libjson-perl liblocale-maketext-perl liblocale-maketext-lexicon-perl liblocale-msgfmt-perl libwww-perl liblwp-protocol-https-perl liburi-perl libversion-perl

Optional dependencies

Install as needed.

Perl Module Package to install Notes
mod_perl2 libapache2-mod-perl2 Required if using Apache 2 and mod_perl
Apache2::Request libapache2-request-perl Required if using Apache 2 and mod_perl
DBI libdbi-perl Used for the Foswiki Page cache
DBD::mysql libdbd-mysql-perl Used for MySQL based Page Cache
DBD::Pg libdbd-pg-perl Used for PostgreSQL based Page Cache
DBD::SQLite libdbd-sqlite3-perl Used for SQLite based Page Cache
FCGI libfcgi-perl Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager libfcgi-procmanager-perl Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME libcrypt-smime-perl Optional, used for S/MIME email signing
Crypt::X509 libcrypt-x509-perl Optional, used for S/MIME email signing
Convert::PEM libconvert-pem-perl Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:
  • Debian, Ubuntu, Kubunto: chown -R www-data:www-data /path/to/foswiki

Apache user should issue the following commands:
a2enmod rewrite
Enables mod_rewrite
a2enmod cgi OR a2enmod cgid
Enables CGI. May need cgid if using a threaded mpm.
a2enmod access_compat
Apache 2.4: Enables compatibility with foswiki example apache configurations.

RedHat, SuSE, CentOS and other RPM based distributions

Minimum requirements

Install apache2, rcs, and perl-CPAN

Perl Module Package to install Notes
Algorithm::Diff perl-Algorithm-Diff  
Archive::Tar perl-Archive-Tar *First shipped in perl 5.9.3
Authen::SASL perl-Authen-SASL  
CGI perl-CGI  
CGI::Session perl-CGI-Session  
Crypt::PasswdMD5 perl-Crypt-PasswdMD5  
Digest::SHA perl-Digest-SHA *First shipped in perl 5.9.3
Email::Address perl-Email-Address  
Email::MIME perl-Email-MIME  
Encode perl-Encode  
Error perl-Error  
File::Copy::Recursive perl-File-Copy-Recursive  
HTML::Parser perl-HTML-Parser  
HTML::Tree perl-HTML-Tree  
IO::Socket::IP perl-IO-Socket-IP First shipped perl 5.19.8
IO::Socket::SSL perl-IO-Socket-SSL  
JSON perl-JSON  
Locale::Language perl-Locale-Codes  
Locale::Maketext perl-Locale-Maketext  
Locale::Maketext::Lexicon perl-Locale-Maketext-Lexicon Optional, needed for internationalization **
Locale::Msgfmt perl-Locale-Msgfmt Optional, needed for internationalization **
LWP perl-libwww-perl  
LWP::Protocol::https perl-LWP-Protocol-https  
URI perl-URI  
version perl-version Must be version 0.77 or newer, included with perl 5.10.1 and newer.

To install the above packages on CentOS
Note, Locale::Maketext::Lexicon and Locale::Msgfmt are not available on Centos. Install using CPAN if Internationalization is required.

First add the appropriate perl module repository, and then install the packages.
yum install -y epel-release
yum install perl-Algorithm-Diff perl-Archive-Tar perl-Authen-SASL perl-CGI perl-CGI-Session perl-Crypt-PasswdMD5 perl-Digest-SHA perl-Email-Address perl-Email-MIME perl-Encode perl-Error perl-File-Copy-Recursive perl-HTML-Parser perl-HTML-Tree perl-IO-Socket-IP perl-IO-Socket-SSL perl-JSON perl-Locale-Codes perl-Locale-Maketext perl-Locale-Maketext-Lexicon perl-Locale-Msgfmt perl-libwww-perl perl-LWP-Protocol-https perl-URI perl-version

To install the above packages on SuSE
First add the appropriate SuSE perl-modules repository, and then install the packages. Note: Not all listed packages will install on SuSE, but all dependences are resolved.
zypper ar -f -n perl-modules http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_13.1 perl-modules
zypper install perl-Algorithm-Diff perl-Archive-Tar perl-Authen-SASL perl-CGI perl-CGI-Session perl-Crypt-PasswdMD5 perl-Digest-SHA perl-Email-Address perl-Email-MIME perl-Encode perl-Error perl-File-Copy-Recursive perl-HTML-Parser perl-HTML-Tree perl-IO-Socket-IP perl-IO-Socket-SSL perl-JSON perl-Locale-Codes perl-Locale-Maketext perl-Locale-Maketext-Lexicon perl-Locale-Msgfmt perl-libwww-perl perl-LWP-Protocol-https perl-URI perl-version

Optional dependencies

Install as needed.

Perl Module Package to install Notes
mod_perl2 mod_perl Required if using Apache2 and mod_perl
Apache2::Request perl-libapreq2 Required if using Apache 2 and mod_perl
DBI perl-DBI Used for the Foswiki Page cache
DBD::mysql perl-DBD-mysql Used for MySQL based Page Cache
DBD::Pg perl-DBD-Pg Used for PostgreSQL based Page Cache
DBD::SQLite perl-DBD-SQLite Used for SQLite based Page Cache
FCGI perl-FCGI Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager perl-FCGI-ProcManager Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME perl-Crypt-SMIME Optional, used for S/MIME email signing
(Not available in default repositories)
Crypt::X509 perl-Crypt-X509 Optional, used for S/MIME email signing
Convert::PEM perl-Convert-PEM Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:
  • RedHat, Fedora, CentOS Mandriva: chown -R apache:apache /path/to/foswiki=
  • Suse: chown -R wwwrun:www /path/to/foswiki

Gentoo (ebuild) based distributions

Minimum requirements

Install www-servers/apache, dev-vcs/rcs, and dev-lang/perl

Perl Module Package to install Notes
Algorithm::Diff dev-perl/Algorithm-Diff  
Archive::Tar perl-Archive-Tar *First shipped in perl 5.9.3
Authen::SASL dev-perl/Authen-SASL Optional, needed for authenticated SMTP
CGI dev-perl/CGI  
CGI::Session dev-perl/CGI-Session  
Crypt::PasswdMD5 dev-perl/Crypt-PasswdMD5  
Digest::SHA   Included with perl
Email::Address dev-perl/Email-Address  
Email::MIME dev-perl/Email-MIME  
Error dev-perl/Error  
Encode   Included with perl
File::Copy::Recursive dev-perl/File-Copy-Recursive  
HTML::Parser dev-perl/HTML-Parser  
HTML::Tree dev-perl/HTML-Tree  
IO::Socket::IP   Ebuild not avaiable. Install with g-cpan if IPv6 is needed.
IO::Socket::SSL dev-perl/IO-Socket-SSL Optional, support encrypted email connection: STARTTLS or SSL
JSON dev-perl/JSON  
Locale::Maketext   Included with perl
Locale::Maketext::Lexicon dev-perl/Locale-Maketext-Lexicon Optional, needed for internationalization
Locale::Msgfmt dev-perl/Locale-Msgfmt Optional, needed for internationalization
LWP dev-perl/libwww-perl  
LWP::Protocol::https dev-perl/LWP-Protocol-https  
URI dev-perl/URI  
version   Must be version 0.77 or newer, included with perl 5.10.1 and newer.
To install the above packages on Gentoo

emerge dev-perl/Algorithm-Diff perl-Archive-Tar dev-perl/Authen-SASL dev-perl/CGI dev-perl/CGI-Session dev-perl/Crypt-PasswdMD5 dev-perl/Email-Address dev-perl/Email-MIME dev-perl/Error dev-perl/File-Copy-Recursive dev-perl/HTML-Parser dev-perl/HTML-Tree dev-perl/IO-Socket-SSL dev-perl/JSON dev-perl/Locale-Maketext-Lexicon dev-perl/Locale-Msgfmt dev-perl/libwww-perl dev-perl/LWP-Protocol-https dev-perl/URI

Optional dependencies

Install as needed.

Perl Module Package to install Notes
mod_perl2 www-apache/mod_perl Required if using Apache 2 and mod_perl
Apache2::Request libapache2-request-perl Required if using Apache 2 and mod_perl
DBI dev-perl/DBI Optional - Used for the Foswiki Page cache
DBD::mysql dev-perl/DBD-mysql Optional - Used for MySQL based Page Cache
DBD::Pg dev-perl/DBD-Pg Optional - Used for PostgreSQL based Page Cache
DBD::SQLite dev-perl/DBD-SQLite Optional - Used for SQLite based Page Cache
FCGI dev-perl/FCGI Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager dev-perl/FCGI-ProcManager Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME dev-perl/Crypt-SMIME Optional, used for S/MIME email signing
Crypt::X509 dev-perl/Crypt-X509 Optional, used for S/MIME email signing
Convert::PEM dev-perl/convert-pem Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:
  • chown -R apache:apache /var/www/path-to-foswiki

FreeBSD (pkg) based distributions

Minimum requirements

Install apache24, rcs, and perl5

Perl Module Package to install Notes
Algorithm::Diff p5-Algorithm-Diff  
Archive::Tar p5-Archive-Tar  
Authen::SASL p5-Authen-SASL  
CGI p5-CGI  
CGI::Session p5-CGI-Session  
Crypt::PasswdMD5 p5-Crypt-PasswdMD5  
Digest::SHA p5-Digest-SHA *First shipped in perl 5.9.3
Email::Address p5-Email-Address  
Email::MIME p5-Email-MIME  
Encode p5-Encode  
Error p5-Error  
File::Copy::Recursive p5-File-Copy-Recursive  
HTML::Parser p5-HTML-Parser  
HTML::Tree p5-HTML-Tree  
IO::Socket::IP p5-IO-Socket-IP First shipped perl 5.19.8
IO::Socket::SSL p5-IO-Socket-SSL  
JSON p5-JSON  
Locale::Maketext p5-Locale-Maketext  
Locale::Maketext::Lexicon p5-Locale-Maketext-Lexicon Optional, needed for internationalization
Locale::Msgfmt p5-Locale-Msgfmt Optional, needed for internationalization
LWP p5-libwww  
LWP::Protocol::https p5-LWP-Protocol-https  
URI p5-URI  
version p5-version Must be version 0.77 or newer, included with perl 5.10.1 and newer.

To install the above packages on FreeBSD

pkg install p5-Algorithm-Diff p5-Archive-Tar p5-Authen-SASL p5-CGI p5-CGI-Session p5-Crypt-PasswdMD5 p5-Digest-SHA p5-Email-Address p5-Email-MIME p5-Encode p5-Error p5-File-Copy-Recursive p5-HTML-Parser p5-HTML-Tree p5-IO-Socket-IP p5-IO-Socket-SSL p5-JSON p5-Locale-Maketext p5-Locale-Maketext-Lexicon p5-Locale-Msgfmt p5-libwww p5-LWP-Protocol-https p5-URI p5-version

After expanding the Foswiki archive, change the ownership of the files:
  • chown -R www:wwwadmin /var/www/path-to-foswiki

Optional dependencies

Install as needed.

Perl Module Package to install Notes
mod_perl2 ap24-mod_perl2 Required if using Apache 2 and mod_perl
Apache2::Request libapreq2 Required if using Apache 2 and mod_perl
BSD-Resource p5-BSD-Resource Optional - used for FCGI process handler resource limits
DBI p5-DBI Optional - Used for the Foswiki Page cache
DBD::mysql p5-DBD-mysql Optional - Used for MySQL based Page Cache
DBD::Pg p5-DBD-Pg Optional - Used for PostgreSQL based Page Cache
DBD::SQLite p5-DBD-SQLite Optional - Used for SQLite based Page Cache
FCGI p5-FCGI Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager p5-FCGI-ProcManager Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME p5-Crypt-SMIME Optional, used for S/MIME email signing
Crypt::X509 p5-Crypt-X509 Optional, used for S/MIME email signing
Convert::PEM p5-Convert-PEM Optional, used for S/MIME email signing

Installation with CPAN

Perl dependencies can also be installed on most systems using cpanm, aka App::cpanminus. On most unix* systems, cpanminus can bootstrap itself using curl or wget. If run as root, the modules will be installed in the System perl. Otherwise they are installed into the users local environment.

Perl Module Notes
Algorithm::Diff  
Archive::Tar *First shipped in perl 5.9.3
Authen::SASL Optional, needed for authenticated SMTP
CGI  
CGI::Session  
Crypt::PasswdMD5  
Digest::SHA Included with perl
Error  
Email::Address  
Email::MIME  
Encode  
File::Copy::Recursive  
HTML::Parser  
HTML::Tree  
IO::Socket::IP  
IO::Socket::SSL Optional, support encrypted email connection: STARTTLS or SSL
JSON  
Locale::Maketext  
Locale::Maketext::Lexicon Optional, needed for internationalization
Locale::Msgfmt Optional, needed for internationalization
LWP  
LWP::Protocol::https  
URI  
version Must be version 0.77 or newer, included with perl 5.10.1 and newer.

To install the above packages with cpanm
Note: We do not recommend installing CPAN modules with cpanminus as root. See below for information on using a private module library with cpanminus.
curl -L http://cpanmin.us | perl - App::cpanminus (optional - install cpanminus if not available )
cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 Digest::SHA Error Email::Address Email::MIME Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext Locale::Maketext::Lexicon Locale::Msgfmt LWP LWP::Protocol::https URI version

Optional dependencies

Install as needed.

Perl Module Package to install Notes
Apache2::Request Required if using Apache 2 and mod_perl
DBI   Optional - Used for the Foswiki Page cache
DBD::mysql   Optional - Used for MySQL based Page Cache
DBD::Pg   Optional - Used for PostgreSQL based Page Cache
DBD::SQLite   Optional - Used for SQLite based Page Cache
FCGI   Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager   Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME   Optional, used for S/MIME email signing
Crypt::X509   Optional, used for S/MIME email signing
Convert::PEM   Optional, used for S/MIME email signing
Locale::Language Optional, Locale::Language will be removed from the Perl core distribution in 5.28.

Installation using cpanminus

See Foswiki:Support.HowToInstallCpanModules for more information.

If you want to install the dependendencies into a specified location, add the "-l" option to cpanm, and add the lib path to bin/LocalLib.cfg. The dependencies will be installed under the specified location, in the lib/perl5 subdirectory. Example: User "foswiki" logs in and installs the libraries locally under the foswikideps directory:
cpanm -l foswikideps Algorithm::Diff Archive::Tar ...   (install libraries into =/home/foswiki/foswikideps=)

/path/to/foswiki/bin/LocalLib.txt is then edited, and the commented line is modified:
# @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', );
@localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );

Foswiki will now run using the libraries installed by cpanm.

Client Requirements

The standard installation has relatively low browser requirements:

  • XHTML 1.0 Transitional compliant
  • Cookies, if persistent sessions are required
  • Javascript, is required for configure, edit save and upload functionality. Foswiki is viewable without javascript.

CSS and Javascript are used in most skins. Some skins will require more recent releases of browsers. The default (Pattern) skin is tested on IE 6+, Safari, Chrome and Firefox.

You can easily select a balance of browser capability versus look and feel. Try the installed skins at System.SkinBrowser 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:
  • 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. You can create this directory elsewhere and configure the bin/setlib.cfg file.
    Foswiki dir: What it is: Where to copy: Example:
    foswiki start-up pages root Foswiki dir /home/smith/public_html/foswiki/
    foswiki/bin CGI bin CGI-enabled dir /home/smith/public_html/foswiki/bin
    foswiki/lib library files same level as bin /home/smith/public_html/foswiki/lib
    foswiki/locale language files dir secure from public access /home/smith/public_html/foswiki/locale
    foswiki/pub public files htdoc enabled dir /home/smith/public_html/foswiki/pub
    foswiki/data topic data dir secure from public access /home/smith/public_html/foswiki/data
    foswiki/templates web templates dir secure from public access /home/smith/public_html/foswiki/templates
    foswiki/tools Foswiki utlilities dir secure from public access /home/smith/public_html/foswiki/tools
    foswiki/working Temporary and internal files dir secure from public access /home/smith/public_html/foswiki/working

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:
  • Copy the file lib/Foswiki.spec to lib/LocalSite.cfg
  • Remove the # in front of the following settings, and ensure that they are set to the correct values: Note: The settings must not reference other $Foswiki::cfg variables.
       $Foswiki::cfg{DefaultUrlHost}
       $Foswiki::cfg{ScriptUrlPath}
       $Foswiki::cfg{ScriptDir}
       $Foswiki::cfg{PubUrlPath}
       $Foswiki::cfg{PubDir}
       $Foswiki::cfg{DataDir}
       $Foswiki::cfg{ToolsDir}
       $Foswiki::cfg{TemplateDir}
       $Foswiki::cfg{LocalesDir}
       $Foswiki::cfg{WorkingDir}
       $Foswiki::cfg{OS}

  • Make sure the following settings are defined:
       $Foswiki::cfg{LoginManager}
       $Foswiki::cfg{WebMasterEmail}
       $Foswiki::cfg{SMTP}{MAILHOST}
       $Foswiki::cfg{SMTP}{SENDERHOST}

  • Remove the line containing __END__ and everything following it.


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

TWiki is a registered trademark of Peter Thoeny.

This topic: System > Category > AdminDocumentationCategory > InstallationGuidePart1
Topic revision: 01 Oct 2011, ProjectContributor