Installation Guide

This guide describes the steps for installing Foswiki using Apache as the web server, on Linux.

Rather not install manually? Visit Foswiki:Download.OtherFoswikiInstallers for automated installers, and virtual machine images. These automate much of the installation process and may help some users get started more easily. For instructions using those packages, refer to the documentation provided there. Note that the installers are optimized for the target system, and do not necessarily follow the normal Foswiki directory structure documented below.

Upgrading? Please see the upgrade guide.

Need further information? Visit Foswiki:Support.SupplementalDocuments for additional notes on installing on different operating systems or shared web-hosting environments, performance tuning, security hardening and more.

Need help? Visit Foswiki:Support web or Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

Before you start

• This guide assumes the a basic knowledge of server administration on the system being used. For more information, see Foswiki:System.AdminSkillsAssumptions.
• Review the System Requirements (below) to make sure you have server prerequisites installed.
• Review the release notes.
• If you need to install any Perl libraries from CPAN, 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.
   • Install the generated file and restart Apache.
   • In shared hosting environment where you don't have access to Apache config files, see the instructions in step 4 below for configuring using .htaccess files.
3. Bootstrap your the install by browsing to the default view URL for your site in your web browser. Depending upon your Apache configuration, your view URL might look something like:
   • http://yoursite.com
   • http://yoursite.com/bin/view
   • http://yoursite.com/foswiki/bin/view
4. Follow the link in the Bootstrap banner of the returned page to the bin/configure tool, address any warnings and save your configuration.
5. Return from configure (button at top of page), and register your first user.

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

At some point, you will want to re-visit Configuring Foswiki to enable out-going emails, create administrators and properly secure your installation.

Detailed Instructions

Step 1: Download and unpack Foswiki

1. Go to your site's root directory as set by Apache (typically within the /var/www or /srv/www directory) or as set by your hosting company.
2. Download the Foswiki distribution from https://foswiki.org/Download
   • If you have shell access, you can download the distribution directly using using this command:

     wget  https://sourceforge.net/projects/foswiki/files/latest/download

   • If you do not have shell access to your web server host, see the section Uploading the Foswiki distribution to your web server host below.
3. Unpack the distribution file:
   • go to your web directory (usually /var/www) or in any directory you what to install Foswiki (designed after by /path/to/foswiki/)
   • Untar and gunzip the distribution using this command: (modify to match version number) tar -xzvf foswiki-VERSION.tgz 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).

Step 2: Confirm file and directory ownership and permissions

Note: Installers on shared hosting sites and Windows can skip to next step.

The general command in Linux distributions to set file ownership to the Apache system user is:

sudo chown -R {user}:{group} /path/to/foswik

The appropriate user/group ownership varies, depending upon the operating system and distribution:

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.

If for some reason the file permissions have been modified, the shell script tools/fix_file_permissions.sh can be used to repair the installation.

cd /path/to/foswiki
sh tools/fix_file_permissions.sh

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

Step 3: Configure location of the Perl executable

If you are running a Linux system with Perl found on the default path or are on a shared hosting site, then you can jump to this step. This step is required on Windows installations.

The easiest way to fix up the bin scripts is to run the tools/rewriteshebang.pl script:

cd /path/to/foswiki/tools
perl rewriteshebang.pl

or for Windows users:

cd C:\path\to\foswiki\tools
perl 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 you get an error about perl command not found, the you need to find where your perl command is installed and include that in your command. For example:

C:\path\to\perl rewriteshebang.pl

Step 4: Configure the web server

• See Foswiki:Support.ApacheConfigGenerator.
• This is the easiest and best way to generate a smooth-running and secure configuration file.
• After installing the config file as per your distribution's guidelines, remember to restart or reload Apache each time you edit the file to apply your changes.

• A sample config file called foswiki_httpd_conf.txt can be found in the root of the foswiki installation.
• This is provided in case you can not access the online configuration generator.
• Instructions are provided in the file for tailoring the configuration to you server.
• Be carefull! The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that mod_access_compat is enabled for backwards compatibility when using Apache 2.4
• As with Method 1, remember to restart or reload Apache each time you edit the file to apply your changes.

• Sample .htaccess files for the Foswiki root and each subdirectory are included in the root of your installation. Each file contains instructions on modifying it for your installation. For more information, see Foswiki:Support.SupplementalDocuments.

General points to keep in mind with any of the above Apache configuration approaches:

• For security purposes, it's important to check that web access is denied to all Foswiki subdirectories other than bin and pub. All three of the approaches described above (Foswiki:Support.ApacheConfigGenerator, the sample foswiki_httpd_conf.txt file included in the distribution, or .htaccess files) should provide for this but it should be confirmed by using web browser to confirm that direct access to the other directories is blocked.
• Also for security purposes, be sure to 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. Again, the three approaches described above all provide for this. However, different script execution mechanisms are disabled in different ways so refer see your web server configuration and documentation for more details.
• The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that mod_access_compat is enabled for backwards compatibility when using Apache 2.4, or use the Foswiki:Support.ApacheConfigGenerator config generator.
• New with Foswiki 2.0 The configure script no longer needs any special protection within the Apache configuration.

Step 5: Bootstrap your configuration

1. Using your web browser, enter the default "view" url for your site. Depending upon your Apache configuration, this might look something like:
   • http://yoursite.com/foswiki/bin/view
   • http://yoursite.com/bin/view
   • http://yoursite.com
     This will Bootstrap your configuration and help Foswiki determine whether or not you are using Short URLs. It also logs you in as a the admin user. Don't close your browser until you've completed the configuration process and registered your first user.
2. Follow the link to configure rendered in the Bootstrap banner. (Do not manually enter the bin/configure URL or Foswiki will not correctly detect the URL configuration).
3. Make any required changes, and save the settings.
   • This will create the initial configuration and end the bootstrap process.
   • Configuration items which may require further attention will be highlighted.
   • Save as soon as possible, especially if your site is exposed. Anyone accessing Foswiki before the configuration has been saved will be granted admin rights.

Step 6: Configure email

1. Select the Mail tab in left bar of confgiure and fill out the following parameters:
   • The {WebMasterEmail} should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links.

     If you are running on a *nix server with a configured local mail transport agent, you can try pressing the "

     

     auto-configure email" button. If auto-configure succeeds, proceed to the next step, to send a test email. If your server is a Windows server, if auto-configure failed, or you know a local transport agent is not available, continue with the SMTP e-mail configuration:

   • The {SMTP}{MAILHOST} should be set to your e-mail server hostame: ex: smtp.gmail.com
   • On most systems, you will also have to configure {SMTP}{Username} and {SMTP}{Password}. These are used so that Foswiki can sign into the e-mail server for purposes of sending e-mail.
   • Click the "auto-configure email" button. (This can run a long time as Foswiki probes all possible e-mail configurations) This will probe the mail server to discover it's configuration, and will finish the configuration. If all goes well, the settings will have been fine tuned for your e-mail server and e-mail is automatically enabled.
2. Once auto-configure completes, Click the "Send test email" button. located on the {WebMasterEmail} field This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
3. Click the Save button in the upper right corner of the configuration page.

Step 7: Check Authentication and Register Yourself

After completing initial installation, 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.

Step 8: Establish an Administrator user

The steps outlined below are recommended for initial configuration. You should complete this before closing the browser after the bootstrap process. Once you close the browser you will lose your temporary admin status. Later on, you can review the further notes below regarding about administrators and options to protect configure and consider one of the more restrictive options.

1. Go to Main.AdminGroup (Theses instructions will be there as well).
2. Scroll down to the "Administration" section and click on "Add Members" link.
   • If you do not see the Admistration section, then you don't have authorization to change this group. See InstallationGuide#InternalAdmin for instructions on establishing an internal admin user.
3. Enter your WikiName as defined when you registered yourself in Step 7.
4. Click the Add Member button
5. Return to the AdminGroup by clicking the group name on the confirmation page and look under "Members" to confirm you have been added.

Step 9. Save your configuration!

Congratulations! Your Foswiki Installation is Ready to Use!

Troubleshooting

• Review the System.PerlDependencyReport and sure all dependencies are correctly resolved.
• Run the configure script and ensure you have resolved all errors and are satisfied that you understand any warnings.
  • You can also access the dependency report from the command line:

    cd /path/to/foswiki
    perl tools/dependencies 

• 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

Supplemental Information For Installation

System Requirements

Server Requirements

cd /path/to/foswiki
perl tools/dependencies

Specific distribution details

Ubuntu and other Debian derived distributions

RedHat, SuSE, CentOS and other RPM based distributions

Gentoo (ebuild) based distributions

FreeBSD (pkg) based distributions

Installation with CPAN

cpanm -l foswikideps Algorithm::Diff Archive::Tar ...   (install libraries into =/home/foswiki/foswikideps=)

# @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', );
@localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );

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

Uploading the Foswiki distribution to your web server host

• 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

About Administrators

Instead of adding users to the AdminGroup, grant those candidate administrators ALLOWTOPICCHANGE rights on the AdminGroup. They can then use a button on the AdminGroup page to join or leave the group at will.

Options to Protect the Configure Script

• Option 1 Restrict configure to members of the AdminGroup:
  • This is the default configuration. You don't need to set anything special from within configure.
  • After you save your configuration, be sure to register a user and add them to the AdminGroup before you log out from the initial super admin login. Once you log out, you'll be blocked from any further configure access unless you can log in as a user in the AdminGroup. The default behaviour is that members of the AdminGroup have access to bin/configure

• Option 2 Restrict configure to a defined list of users:
  • Visit the "Security and Authentication" tab, "Access control" sub-tab.
  • Set {FeatureAccess}{Configure} to a list of WikiNames that will be allowed access to configure.
  • This setting overrides use of the AdminGroup, and these users do not have to be members of the AdminGroup.
  • If you want the admin super-user to also have access to configure, you need to include "BaseUserMapping_333" in that list.

• Option 3 Define a "super user" ID and allow it access to configure (This is not recommended)
  • Visit the "Security and Authentication" tab, "Passwords" tab. Enable "Expert" options. Set the {Password} field to a hashed ApacheMD5 encoded password.
  • See #InternalAdmin for more information.

Establishing an internal admin login (optional)

• Setting password from bin/configure interface: The password can be set in configure, in the "Security and Authentication" -> "Passwords" tab. Enter the password in plain text. It will be automatically hashed when saved, and cannot be recovered.
• Setting the password from the command line: The password can also be set via command line configuration tool, using the following command:

  tools/configure -save -set {Password}='adminpass'

• Manually setting admin user in LocalSite.cfg: Follow these steps: ( Caution: This procedure only works for plain ascii passwords, it does not handle international characters.)
  1. Generate the hashed password using the Apache htpasswd tool: (replacing {password} with your password)

     htpasswd -bn  admin {password}

  2. Copy the password hash that's generated. (The part after admin: ex: $apr1$Oc.PLq8V$wslABA3mWXfYT/wH0Hsom0)
  3. Search LocalSite.cfg for $Foswiki::cfg{Password}, Replace the existing line, or if not found, insert a new line in the file, as shown:

     $Foswiki::cfg{Password} = '{password hash}';

User Authentication Options

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

Template Login authentication

Enabling Template Login

By default, your Foswiki installation is probably already using TemplateLogin, HtPasswdUser and TopicUserMappingContrib as the default Login, Password and user mapping options.

1. Using configure, 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.
      

      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.

      

      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

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.

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

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

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.

Testing your authentication configuration:

1. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. 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.
   2. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
2. Create a new topic (in Sandbox web for example) to confirm that authentication works.
3. Add users to the Main.AdminGroup. Edit the Main.AdminGroup topic in the Main web to include users that should have administrator status. Read defining adminstrator user(s) for more information.
   

   This is a very important step, as users in this group can access all topics, independent of Foswiki access controls.

Configuring Foswiki manually (without using the configure page)

$ perl -CAS tools/configure -save

$ tools/configure -save

LocalSite.cfg load failed
AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/tools, Script name:
configure using FindBin
AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub
AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data
AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working
AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools
AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates
AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale
AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin
AUTOCONFIG: Unable to use PlainFileStore: ,v files were found in data or pub,
which indicates this installation is already configured for RCS e.g.
/var/www/foswiki/distro/core/data/WFWeb/WebChanges.txt,v
AUTOCONFIG: Store configured for RcsLite
AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking
AUTOCONFIG: Detected OS UNIX:  DetailedOS: linux
** Enter values for critical configuration items.
** type a new value or hit return to accept the value in brackets.

This is the root of all Foswiki URLs.
For example, =http://myhost.com:123=
(do not include the trailing slash.)

{DefaultUrlHost} (http://localhost): http://myhost.com

This is the 'cgi-bin' part of URLs used to access the Foswiki bin
directory. For example =/foswiki/bin=.
See [[https://foswiki.org/Support/ShorterUrlCookbook][ShorterUrlCookbook]]
for more information on setting up Foswiki to use shorter script URLs.

{ScriptUrlPath} (/foswiki/bin):

...

tools/configure -save -noprompt
tools/configure -save -set {DefaultUrlHost}='http://mysite.com'
tools/configure -save -set {ScriptUrlPath}='/bin'
tools/configure -save -set {ScriptUrlPaths}{view}=''
tools/configure -save -set {PubUrlPath}='/pub'
perl -CA tools/configure -save -set {Password}='ÄdmînPäss' 

tools/configure -save -set {WebMasterEmail}='user@email.com'
tools/configure -save -set {SMTP}{MAILHOST}='smtpserver.email.com'
tools/configure -save -set {SMTP}{Username}='userid'
tools/configure -save -set {SMTP}{Password}='password'
tools/configure -save -wizard AutoConfigureEmail -method autoconfigure

tools/configure -check -verbose

tools/configure -check {DataDir} -method validate_permissions

tools/configure -search Umask
tools/configure -getcfg {Store}

TWiki Compatibility