InstallationGuide < TWiki

%STARTINCLUDE%
---+ 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. 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 =%SYSTEMWEB%.InstallationGuide= (the <nop>InstallationGuide topic in the %SYSTEMWEB% 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.

%TOC%

---++ System Requirements

Please see the section "[[#SystemRequirements][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.

<!-- to be included once the supplemental document is available
*If you are upgrading from an old TWiki version such as Cairo (TWiki 3)*, refer to Foswiki:Support.UpgradingFromOlderTWikiReleases to ensure a safe upgrade without accidentally overwriting your site customizations and data.
-->

Verify that your server meets the [[#SystemRequirements][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).

#StandardInstallation
---++ Basic installation: getting Foswiki up and running

To install Foswiki, complete the following steps:

   1 *Download* and *unpack* the Foswiki distribution.
   1 *Set the file and directory permissions* for the installation.
   1 *Configure* the *locations of the Perl executable* and the *Foswiki modules*.
   1 *Configure the web server*.
   1 *Configure Foswiki*.
   1 *Enable authentication of users* (if desired).
   1 *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 "[[#UploadingFoswikiDistribution][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.
   * *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.

---+++ Configure the locations of the Perl executable and the Foswiki modules

*Make sure the Foswiki scripts can be executed by the web server.* The default location of Perl is =/usr/bin/perl=. *If it's somewhere else*, change the path to Perl in the first line of each script (you may have to give yourself write permission first) in the =bin= and =tools= directories. You can use the =tools/rewriteshbang.pl= script to do this; for example:<verbatim>
   cd /path/to/foswiki/bin
   /path/to/perl ../tools/rewriteshbang.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 rewriteshbang.pl
</verbatim>

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 "[[#ConfigureFoswiki][Configure Foswiki]]"), set the =ScriptSuffix= option to the special extension.

*Create the file Local<nop>Lib.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 <nop>Local<nop>Lib.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 [[http://cpan.perl.org/][CPAN]] modules, but can't update the main Perl installation files on the server, you can set =$CPANBASE= to point to your personal [[http://cpan.perl.org/][CPAN]] install. Don't forget that the web server user has to be able to read those files as well.

---+++ Configure the web server

First choose the best configuration method for your web server. With Apache, there are two ways to configure it: a config file included from httpd.conf or .htaccess files. 
   * *Apache config file:* The recommended method is using a config file. With a config file you can put the entire Foswiki configuration in ONE file (typically named =foswiki.conf=). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file is included from the main Apache config file http.conf. Most distributions have a directory from which any file that ends with =.conf= gets included when you restart Apache (Example !RedHat/Fedora/Centos: =/etc/httpd/conf.d= ). If you use a virtual host setup in Apache you should include the =foswiki.conf= file from inside the desired virtual host config in your Apache configuration.
   * *.htaccess files:* This 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 =<noautolink>ScriptAlias<noautolink>= directive for the =bin= subdirectory, or an =Alias= directive with =SetHandler cgi-script= and =Options Exec<nop>CGI= 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 and in the =bin= directory, there are sample =.htaccess= files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments.<sticky>
   | *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= | =.htaccess= in all other subdirectories below =foswiki= |</sticky>
   * 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.
   * 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.

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

#ProtectConfigure
*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:
   * Change to the =foswiki/data= directory.
   * Issue the command =htpasswd -c .htpasswd &lt;username&gt;=, where &lt;username&gt; 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.

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 &lt;username&gt;= directive to restrict access to the =configure= script. Ensure the user specified in the directive matches the &lt;username&gt; 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 "[[#DefineAdminUser][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.

#ConfigureFoswiki
---+++ Configure Foswiki

*Run the =configure= script* from your browser: enter =http://yourdomain/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 "[[#DefineAdminUser][Define the administrator user(s)]]"). Note the configuration password is separate from any web server security you have set up for the =configure= web page (see "[[#ProtectConfigure][Protect the configure script]]").
   * Continue configuring Foswiki. Resolve any errors or warnings highlighted on the configure page.
   * If your web server can be accessed by more than one domain name make sure to add the additional alternative URLs to ={PermittedRedirectHostUrls}=
   * Setup the _Mail and Proxies_ section. The ={WebMasterEmail}= and ={SMTP}{MAILHOST}= settings must be defined so Foswiki can send registration emails. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set ={SMTP}{Username}= and ={SMTP}{Password}=. If you do not want to enable sending registration emails or want to enable it later you can uncheck ={EnableEmail}=.
     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}=.

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

#AuthenticationOfUsers
---+++ Enable authentication of users

By enabling authentication, you can control access to your site and track the activity of your users. *This is particularly important for sites that are publicly accessible on the web.*  You are strongly encouraged to read [[%SYSTEMWEB%.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 =%SYSTEMWEB%.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

With Template Login enabled, when Foswiki needs to authenticate the user, it will redirect to a login web page. A list of all users is shown in the =<noautolink>%USERSWEB%.WikiUsers</noautolink>= topic.

To setup Template Login, perform the following steps:

   1 *Configure Template Login.* Under the =Security Settings= pane of the =configure= page:
      1 Select =Foswiki::LoginManager::TemplateLogin= for ={LoginManager}=.
      1 Select =Foswiki::Users::HtPasswdUser= for ={PasswordManager}=.
      1 Select =Foswiki::Users::TopicUserMapping= for ={UserMappingManager}=.
      1 Save your settings.
   1 *Verify that registration works.* Register yourself using the =[[%SYSTEMWEB%.UserRegistration]]= topic in your Foswiki installation. Note if you are viewing this page via the =INSTALL.html= file, then you can access the user registration page by entering =<noautolink>%SYSTEMWEB%.UserRegistration</noautolink>= into the "Jump" text box at the top right of any Foswiki page in your installation.<br /> Check that the password manager recognizes the new user by verifying that a new line is added to the =foswiki/data/.htpassswd= file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on =foswiki/data= or =foswiki/data/.htpasswd= may not be set to allow the web server user to modify the file.
   1 *Check that authentication works.* Edit a topic by clicking on the =Edit= link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.

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

---++++ Apache Login authentication

With Apache Login enabled, when Foswiki needs to authenticate the user, the standard HTTP authentication mechanism is used: the browser itself will prompt for a user name and password.

*Note:* Apache Login is required for Apache-based login methods such as mod_ldap.

To setup Apache Login, perform the following steps:

   1 *Configure Apache Login.* Under the =Security Settings= pane of the =configure= page:
      1 Select =Foswiki::LoginManager::ApacheLogin= for ={LoginManager}=.
      1 Select =Foswiki::Users::HtPasswdUser= for ={PasswordManager}=.
      1 Select =Foswiki::Users::TopicUserMapping= for ={UserMappingManager}=.
      1 Save your settings.
      1 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:<sticky><verbatim>
      <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*">
      require valid-user
      </FilesMatch></verbatim></sticky>
      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.
   1 *Verify that registration works.* Register yourself using the =[[%SYSTEMWEB%.UserRegistration]]= topic in your Foswiki installation. Note if you are viewing this page via the =INSTALL.html= file, then you can access the user registration page by entering =<noautolink>%SYSTEMWEB%.UserRegistration</noautolink>= into the "Jump" text box at the top right of any Foswiki page in your installation.<br /> Check that the password manager recognizes the new user by verifying that a new line is added to the =foswiki/data/.htpassswd= file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on =foswiki/data= or =foswiki/data/.htpasswd= may not be set to allow the web server user to modify the file.
   1 *Check that authentication works.* Edit a topic by clicking on the =Edit= link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.
   
#SearchAlgorithm
---+++ Choose search algorithm based on your platform

Under Store Settings 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). The safe setting for Windows is Foswiki::Store::SearchAlgorithms::PurePerl. 

#DefineAdminUser
---+++ Define the administrator user(s)

Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. After installing Foswiki, you should register a user that you will use to administer Foswiki. To make this user an administrator, add the WikiName for the user to the =AdminGroup=, defined in the =[[%USERSWEB%.AdminGroup]]= topic in your Foswiki installation.

To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering =%SYSTEMWEB%.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 =[[%USERSWEB%.AdminGroup]]= topic and select the "internal admin login" link. Login using the password you set on the =configure= page.
   * After logging as the internal admin, edit the =%USERSWEB%.AdminGroup= topic. Follow the instructions on the page carefully and add your WikiName to the group.
   * Test that you have been added successfully: On the =[[%USERSWEB%.AdminGroup]]= page, select the "Logout link" and logout from being the internal admin. Select the "Edit" link for the =[[%USERSWEB%.AdminGroup]]= page. If you successfully added yourself as an admin user, you should see the edit page.

Once the =AdminGroup= is no longer empty, then any member of the group can add subsequent members &mdash; 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 Foswiki:System.AccessControl 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/foswiki/bin/view= and start using your Foswiki 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 Foswiki:System.ManagingWebs for more information on Wiki webs and how to create one.

---++ Beyond the basic installation

Once you have Foswiki installed and running, you can perform one or more of the following steps to tailor your installation to your needs. Many of the references in this section refer to topics within your Foswiki installation. For example, =[[%SYSTEMWEB%.Skins]]= refers to the =Skins= topic in your %SYSTEMWEB% web. To go directly to a topic, enter the full topic name, such as =%SYSTEMWEB%.Skins=, into the "Jump" text box at the top right of any Foswiki page.

To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering =%SYSTEMWEB%.InstallationGuide= into the "Jump" text box. By doing this instead of using the =INSTALL.html= file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.

All of the Foswiki documentation can also be found online in the [[Foswiki:System.WebHome][Foswiki documentation section]] (the "System" web) of the Foswiki web site.

Note the =configure= page mentioned in this section is accessed by visiting =http://yourdomain/foswiki/bin/configure= your web browser.

---+++ Site configuration and maintenance

#SetPreferences 
---++++ Set Foswiki Preferences

Preferences for customizing many aspects of Foswiki are set by editing =%LOCALSITEPREFS%=. If a given preference is not set in =%LOCALSITEPREFS%=, then a default value is picked up from =[[%SYSTEMWEB%.DefaultPreferences]]=, if present, or, for extensions, from the extension topics.

To simplify your upgrades, do not modify =%SYSTEMWEB%.DefaultPreferences=. Instead, copy any settings you want to change from =%SYSTEMWEB%.DefaultPreferences= to =%LOCALSITEPREFS%=.

To see the available preferences that can be set, look through =[[%SYSTEMWEB%.DefaultPreferences]]=.

If, for some reason, you wish to pick up default preferences from a different topic, you can set the location in the =Miscellaneous settings= pane of the =configure= page, in the ={SitePrefsTopicName}= setting (visible when Expert mode is enabled). It is recommended that you leave this setting to its default value, =<nop>Default<nop>Preferences=.

---++++ Select the desired security level

Foswiki has a many security features that can be enabled/disabled and adjusted to suit your needs.

In many cases enabling a security feature prevents other features. It is a balance that the administrator has to choose depending on the purpose of the Foswiki installation (confidential vs public knowledge), the type of installation (intranet vs internet), and your type of business.

A new administrator is encouraged to read Foswiki:Support.SecurityFeatures which gives a walkthrough of the different security aspects and how to set the appropriate configuration settings. Note that that some security settings are only visible in configure in "expert mode" which you enter by clicking the "Yes, I've read all the documentation" button at the top of the configure screen.

---++++ Enable Email Notification

Each web has an automatic email notification service that sends you an email with links to all of the topics modified since the last alert. To enable this service:
   1 Confirm the Mail and Proxies settings on the =configure= page.
   1 Setup a cron job (or equivalent) to call the =tools/mailnotify= script, as described in the [[%SYSTEMWEB%.MailerContrib]] topic.

---++++ Automate removal of expired sessions and lease files

By default Foswiki cleans out expired session and lease files each time any topic is viewed, but this has a performance cost. Instead you may wish to schedule a cron job (or equivalent) to run the =tools/tick_foswiki.pl= script, and set a negative value on the =configure= page for ={Sessions}{ExpireAfter}=. For more details, read [[%SYSTEMWEB%.CommandAndCGIScripts#tick_foswiki_pl]].

---++++ Enable !WebStatistics

You can manually or automatically generate a listing of the most popular pages for each web, based on number of visits. For information on setting up this feature, see the [[%SYSTEMWEB%.SiteTools]] topic.

---++++ Enable Localisation

Foswiki supports displaying national (non-ASCII) characters, and using different languages for its basic interface elements. To configure localisation, modify the =Localisation= section of the =configure= page. For more information, see Foswiki:Support.InternationalizationSupplement.

---+++ Customizing your site

---++++ Customize pages for managing personal information

If you are not using Foswiki to manage your users' passwords or email addresses, or would just like to enhance the default pages, then modify the following topics accordingly with information appropriate for your site:

   * =[[%SYSTEMWEB%.ChangePassword]]=
   * =[[%SYSTEMWEB%.ResetPassword]]=
   * =[[%SYSTEMWEB%.ChangeEmailAddress]]=

#TailorUsersTopic
---++++ Customize the user topic for new users

When a new user registers on your Foswiki site, a topic with a name corresponding to the user's !WikiName is created in the %USERSWEB% web: this topic is the user's user topic. The user topic is based on the =[[%USERSWEB%.NewUserTemplate]]= topic; if it is not present, then =[[%SYSTEMWEB%.NewUserTemplate]]= (and its associated =[[%SYSTEMWEB%.UserForm]]=) is used as a default. If you want to customize the user topic for your users, copy =%SYSTEMWEB%.NewUserTemplate= to =[[%USERSWEB%.NewUserTemplate]]=, and =%SYSTEMWEB%.UserForm= to =[[%USERSWEB%.UserForm]]=, and make your changes to =[[%USERSWEB%.NewUserTemplate]]= and =[[%USERSWEB%.UserForm]]=. (See Foswiki:System.ManagingTopics#CopyTopic for instructions on copying a topic.)

You can edit these topics to suit your needs, such as the following:
   * Customize the user topic for your site.
   * Add an =ALLOWTOPICCHANGE= preference setting to =[[%USERSWEB%.NewUserTemplate]]= so only the user can edit their own user topic. In particular, on a public Foswiki site, restricting edit access will avoid vandalism and spam.
   * Add and remove fields defined in the =[[%USERSWEB%.UserForm]]=.

If you added or removed fields from the user form you may also need to tailor =[[%USERSWEB%.UserRegistration]]= to match (copy over the contents from [[%SYSTEMWEB%.UserRegistration]] to =%USERSWEB%.UserRegistration= when creating it).

#CustomizeAppearance
---++++ Customize the appearance of your Foswiki site

The real power of Foswiki lies in its flexibility to be customized to meet your needs. To change the look of the default skin, !PatternSkin, please refer to [[%SYSTEMWEB%.PatternSkin]] and [[%SYSTEMWEB%.PatternSkinCustomization]].

At the [[http://foswiki.org/][Foswiki website]] you can find more resources. A good place to start exploring is the Foswiki:Support.AdministratorsCookBook which offers tips and tricks for customizing your Foswiki site. Many of these are best done before any content has been added to your site, so immediately after installation is a good time to consider the possibilities.

---+++++ Left, Top and Bottom Bars with !PatternSkin

The top bar and bottom bar are common across all webs.

To customize the top bar, copy =[[%SYSTEMWEB%.WebTopBarExample]]= to =[[%SYSTEMWEB%.WebTopBar]]=, and make your desired changes to =%SYSTEMWEB%.WebTopBar=.

To customize the bottom bar, copy =[[%SYSTEMWEB%.WebBottomBarExample]]= to =[[%SYSTEMWEB%.WebBottomBar]]=, and make your desired changes to =%SYSTEMWEB%.WebBottomBar=.

The side bar can be customized on a per web basis. To customize the side bar, copy the =WebLeftBarExample= topic in the given web to =WebLeftBar=, and make your desired changes to =WebLeftBar=. If you would like to move the side bar to the right of the page, see [[%SYSTEMWEB%.PatternSkin]] for more details.

---+++++ Copyright, License and Classification Statements

At the bottom of each topic, there is a copyright statement that is set in the =WEBCOPYRIGHT= preference. Its default is the following: =Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.=

If your Foswiki site is used in an environment without public access you should replace this with your normal copyright notice. You should also consider adding a security classification (e.g., For Internal Use Only) so people do not have to add this manually to every new topic.

If your Foswiki site is publicly accessible, you need to decide which copyright and license you wish to apply to all contributions. For open source applications, licenses such as <a href="http://www.gnu.org/licenses/fdl.html">the GNU Free Documentation License</a>, <a href="http://www.freebsd.org/copyright/freebsd-doc-license.html">FreeBSD Documentation License</a>, and one of the various <a href="http://creativecommons.org/licenses/">Creative Commons licenses</a> are possible licenses to consider. Remember that once people have started contributing, you cannot retroactively change the license (unless it has a provision for this).

To change the copyright statement, perform the following steps:

   * Copy the =WEBCOPYRIGHT= preference setting from =[[%SYSTEMWEB%.DefaultPreferences]]= to =%LOCALSITEPREFS%=. Change the value to your desired text. This value will be your new default across all webs.
   * You can create a unique message for a specific web by setting the =WEBCOPYRIGHT= preference in the =WebPreferences= topic for the given web. For example, you could add a confidential classification to a web that has restricted access.
   * The =WEBCOPYRIGHT= preference setting in =[[%SYSTEMWEB%.WebPreferences]]= covers the documentation that comes with Foswiki, and should not be changed.

---++++ WYSIWYG vs Raw Edit

In Foswiki, the WYSIWYG editor is used by default in edit mode. An _Edit Raw_ link is available for those who prefer to edit the raw topic text.

If you prefer to use the raw text editor by default and have a separate WYSIWYG button, as in TWiki 4.1, then you can modify the templates that define the edit screen as described in Foswiki:Support.FaqHowToMakeRawEditDefault.

---+++ Installing extensions

Foswiki:Extensions is an extensive library of [[plugins]] for Foswiki that enhance functionality in a huge number of ways. A few plugins are pre-installed in the Foswiki distribution.

In the _Extensions_ section of the =configure= page, you can select the _Find More Extensions_ button to download and install additional plugins from the foswiki.org website. If you are behind a firewall or your server has no access to the Internet, you can also install plugins manually. Installation instructions for each plugin are located in its corresponding topic on http://foswiki.org/. Additional documentation on Foswiki plugins can be found at Foswiki:Support.PluginsSupplement.

Plugins are activated in the _Plugins_ section of the =configure= page. In addition, some plugins are also configured in this section.

---+++ TWiki Compatibility

Foswiki is 100% backwards compatible with TWiki<sup>&reg;</sup> 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.

---++ Troubleshooting

Re-run the =configure= script and make sure you have resolved all errors and are satisfied that you understand any warnings.

Failing that, consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.

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

#SystemRequirements
---++ 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 <a href="http://www.gnu.org/software/rcs/rcs.html" rel="nofollow" target="_top">RCS (Revision Control System)</a>, a GNU Free Software package. It should be able to run on any server platform that meets the following requirements.

| *Resource* | *Required Server Environment* |
| Perl | 5.8.4 or higher is recommended. Foswiki will run in perl 5.6.1 but only with Wysiwyg editor disabled. Wysiwyg requires Unicode support which is provided by perl 5.8.1 onwards. |
| RCS | 5.7 or higher (including GNU =diff=) <br /> 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. <br /> Install within the PATH if not included with RCS (check version with =diff -v=) <br /> 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 | &bull; Unix: =cron= <br />&bull; Windows: =cron= equivalents <!-- SMELL: Macintosh version? --> |
| Web server | Apache is well supported; for information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms. |

---+++ Required CPAN modules

Most of the <a href="http://cpan.perl.org/" rel="nofollow" target="_top">CPAN</a> libraries listed below are part of a standard Perl installation. See Foswiki:Support.HowToInstallCpanModules for detailed information on how to install any !CPAN libraries not present in your installation.

The following Perl !CPAN modules are used by Foswiki:

| *Module* | *Preferred version* |
| Algorithm::Diff (included with Foswiki) | |
| CGI | Versions 2.89 and 3.37 must be avoided. Most version from 3.15 and onwards should work. |
| CGI::Carp | &gt;=1.26 |
| CGI::Session | &gt;=4.30 (included with Foswiki) Versions 4.20 and before have Foswikitask:Item1306 |
| Config | &gt;=0 |
| Cwd | &gt;=3.05 |
| Data::Dumper | &gt;=2.121 |
| Error (included) | |
| File::Copy | &gt;=2.06 |
| File::Find | &gt;=1.05 |
| File::Spec | &gt;=3.05 |
| !FileHandle | &gt;=2.01 |
| IO::File | &gt;=1.10 |
| Text::Diff (included with Foswiki) | |
| Time::Local | &gt;=1.11 |

You can check version numbers from the command line (replace "ModuleName" with the name of the module):

<pre>perl -le 'use ModuleName; print "ModuleName"->VERSION' </pre>

---+++ Optional !CPAN modules

The following Perl modules may be used by Foswiki. See Foswiki:Support.HowToInstallCpanModules for detailed information on how to install !CPAN libraries.

| *Module* | *Preferred version* | *Description* |
| Archive::Tar | | May be required by the Extensions Installer in configure if command line tar or unzip is not available |
| CGI::Cookie | &gt;=1.24 | Used for session support |
| Digest::base | | |
| Digest::SHA1 | | |
| Jcode | | Used for !I18N support with perl 5.6 |
| Locale::Maketext::Lexicon | &gt;=0 | Used for !I18N support |
| Net::SMTP | &gt;=2.29 | Used for sending mail |
| Unicode::Map | | Used for !I18N support with perl 5.6 |
| Unicode::Map8 | | Used for !I18N support with perl 5.6 |
| Unicode::MapUTF8 | | Used for !I18N support with perl 5.6 |
| Unicode::String | | Used for !I18N support with perl 5.6 |
| URI | | Used for configure |

Most of these modules will probably already be present in your installation. You can check version numbers with the =configure= script, or if you're still trying to get to that point, check from the command line (replace "ModuleName" with the name of the module):

<pre>perl -e 'use ModuleName; print $ModuleName::VERSION."\n"' </pre>

#ClientRequirements
---+++ Client requirements

Browser clients must support the following capabilities:

   * HTML 3.2
   * Cookie support enabled, if persistent sessions are required

Most skins also require CSS and Javascript support. There is a low-fat skin ([[System.PlainSkin][Plain]]) that minimises these requirements. Some skins require newer browser version. The default skin ([[System.PatternSkin][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.

#UploadingFoswikiDistribution
---++ 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.<sticky>
   | *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= |</sticky>

#ConfiguringFoswikiManually
---++ 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:<sticky><verbatim>
   $Foswiki::cfg{DefaultUrlHost}
   $Foswiki::cfg{ScriptUrlPath}
   $Foswiki::cfg{PubUrlPath}
   $Foswiki::cfg{PubDir}
   $Foswiki::cfg{TemplateDir}
   $Foswiki::cfg{DataDir}
   $Foswiki::cfg{LocalesDir}
   $Foswiki::cfg{OS}</verbatim></sticky>
   * Make sure the following settings are defined:<sticky><verbatim>
   $Foswiki::cfg{LoginManager}
   $Foswiki::cfg{WebMasterEmail}
   $Foswiki::cfg{SMTP}{MAILHOST}
   $Foswiki::cfg{SMTP}{SENDERHOST}</verbatim></sticky>
%STOPINCLUDE%

---
 *Related Topics:* AdminDocumentationCategory, Foswiki:Support.SupplementalDocuments

TWiki is a registered trademark of Peter Thoeny.
This topic: TWiki > CategoryCategory > AdminDocumentationCategory > InstallationGuide
Topic revision: r1 - 2009-09-12 - 01:19:12 - ProjectContributor
Copyright &© by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding STALklubben? Send feedback