Installation Guide

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.

Getting your Foswiki up and running should take less than 5 minutes to complete. If you are upgrading, please see the upgrade guide.

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

Before Installing Foswiki

This guide assumes the person installing Foswiki has a basic knowledge of server administration on the system on which Foswiki is to be installed, as described at Foswiki:System.AdminSkillsAssumptions.

Please see the 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.

5-Minute Install

Here's the quick version of the instructions, for those that are already comfortable with performing such installations. More detailed instructions follow.

1. Download and unpack the latest version of Foswiki.
2. Configure Apache using the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation.
3. Complete the install by browsing to /bin/configure in your web browser and follow the instructions.

That's it! You Foswiki should now be installed. Browse to /bin/view and start editing!

Detailed Instructions

Step 1: 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".

Step 2: Set the file and directory permissions for the installation

NOTE: You can skip this step if you are on Windows.

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.

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

Step 3: 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
/path/to/perl -I ../lib rewriteshebang.pl

or for Windows users:

cd C:\path\to\foswiki\tools
C:\path\to\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.

Step 4: 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. 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 ). Otherwise, you can include the Foswiki apache config file from the main Apache config file.
• .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.
  • The Foswiki:Support.ApacheConfigGenerator tool will generate the appropriate settings;
  • the foswiki_httpd_conf.txt file also has examples of configuring Apache appropriately.
• 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.

Step 5: 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.

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

Step 6: 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)").

  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}.

  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}.

    Warning: Can't find topic Sandbox.UserAuthentication

SMTP authentication requires additional perl modules including Authen::SASL and MIMI::Base64,

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

Step 7: 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

Warning: Can't find topic Sandbox.UserAuthentication

Apache Login authentication

Warning: Can't find topic Sandbox.UserAuthentication

Step 8: 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.

Step 9: 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 is accessed 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 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 you have logged in as the internal admin, view the Main.AdminGroup topic. Follow the instructions on the page to add users to the Main.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 set up your Foswiki installation! At this point you can start creating and editing pages. See 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

If you are having problems with your installation, try the following:

• Run the configure script and ensure you have resolved all errors and are satisfied that you understand any warnings.
• Consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
• Ask for help on IRC (irc.freenode.net, channel #foswiki). There are often a number of people waiting to help.
• Ask a question in the Foswiki:Support web

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

TWiki Compatibility

Foswiki is 100% backwards compatible with TWiki^® markup up to and including TWiki 4.2.4. Existing TWiki webs, topics and attachments can be used with Foswiki without requiring any changes.

To support a seamless upgrade from TWiki, Foswiki ships with a plugin called TWikiCompatibilityPlugin. This plugin enables most TWiki extensions to work with Foswiki, without modifications. 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 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 extensions for Foswiki.

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

TWiki is a registered trademark of Peter Thoeny.