SimpleInstallGuide

Simple Installation Guide

The following are installation instructions for the Foswiki 1.0.0 production release on an Apache web server on Linux.

This guide assumes you have a basic knowledge of server administration on the Linux system on which Foswiki is to be installed, you have root or sudo access and that Apache2, rcs and PHP4 are installed and working. If not this guide is not for you, please follow the instructions at Foswiki:System.InstallationGuide. If you are unsure of your knowledge please review Foswiki:System.AdminSkillsAssumptions. PHP is not required by Foswiki but is so common we make the assumption it is installed.

Visit Foswiki:Support.SupplementalDocuments for supplemental information for installing Foswiki or upgrading from TWiki, including notes on installing Foswiki on different platforms, environments and web hosting sites. A fuller more complex set of instructions are also available online by following links from Foswiki:Support.Foswiki01x00x00.

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

Please read these notes before you start!

1. You are expected to have read the instructions in full before you start.
2. If during the installation in any of the test fail please: follow the more comprehensive instructions from the link at the top of the page.
3. Foswiki does not allow spaces in the directory names. Especially on Windows make sure to use a directory path without spaces.
4. Do not chmod -R 770 foswiki, differing access rules are required for the differing files and directories. This is the most common mistake installers make.
5. Every time you copy or move a file check who owns it and its access rights. This is another very common mistake.

Basic Installation

1. Download the Foswiki distribution from http://foswiki.org/Download
2. Make a directory for the installation. In these instructions we will assume the directory is /var/www/foswiki. If your machine is set up to use /srv/www/ then use /srv/www/foswiki.
3. Unpack the distribution into the directory.
4. Setup access file and directory rights
   • The read, write and execute rights are set correctly as extracted from the tar file.
   • However you will need to chown -R www-data:www-data /path/to/foswiki, the apache user and group set to match your distribution.
5. Check the Perl installation. Ensure that Perl 5 and the Perl CGI library are installed on your system.
   • Run "which perl" and check perl is installed in /usr/bin/perl.
   • Run "perl -v" and check one of the perl 5 variants is installed.
6. Create the file LocalLib.cfg located as bin/LocalLib.cfg
   • There is a template for this file in bin/LocalLib.cfg.txt. Simply copy LocalLib.cfg.txt to LocalLib.cfg. Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt.
   • Edit LocalLib.cfg and set $foswikiLibPath to the absolute file path of your lib directory e.g. /var/www/foswiki/lib.
7. Go to the webpage Foswiki:Support.ApacheConfigGenerator and fill in the form to generate a safe and working config file for Foswiki on Apache. For now use these settings (you can redo this later when you want a differing set of settings):
   • Set the root of the installation i.e. /var/www/foswiki
   • Set the ip address range say 10.0.0 for a local IP range from 10.0.0.0 to 10.0.0.255 OR set a specific address like 192.168.53.23 (your address)
   • Set your linux user name say joebrown
   • Do not enable mod_perl (do this later once you are sure foswiki is working, if it stops working then mod_perl as not worked)
   • Don't enable short URLs (try this later requires apache2 to run mod_rewrite)
   • Set Template login manager
   • Prevent execution of PHP4/5
   • Block direct viewing of htm an html file attachments and block viewing of files in the Trash (Both for security reasons).
   • Finally return Apache 401 errors when authentication fails.
8. Copy and paste the resulting text into /etc/apache2/conf.d/foswiki.conf (/etc/httpd/conf.d/foswiki.conf on some distributions). At the bottom of the same page is another form to generate a mod_perl configuration (useful later).
9. Restart apache (/etc/init.d/apache restart works on my distribution) and test by pointing your browser at http://localhost/foswiki/ if you get the page "Welcome to FosWiki" apache has been reconfigured, if not check for apache errors on the restart or in the log files.
10. Run the configure script - click on the link "Configure Foswiki" (or enter http://yourdomain/foswiki/bin/configure into your browser address bar)
    • Note! The configure file must be set up in two stages; when you run it for the first time, you can only edit the section General Path Settings. Check these setting carefully, save these settings, and then return to configure to continue configuration. It will give you a very stern warnings which can be ignored while you are configuring Foswiki from the local network but must not be ignored if you can open it from the net. Test this once, Foswiki is working, and if it can your Apache configuration needs to be tightened to block the security hole!
    • Every time you update the config file you will be asked for a password, first time through you must enter it twice to register it. Please use a password you will not use anywhere else.
    • On the second pass resolve any errors or warnings it tells you about, ignore mail for the moment. Once all the errors have been resolved you have a working wiki, however you still cannot edit it and you cannot register users.
11. The set-up of Mail can be a problem; if your Linux machine is set-up with sendmail working correctly you should just be able to go to test below, this will mostly apply to genuine servers. If you don’t know your machine is set-up for sendmail it probably is not so continue with configure i.e. most desk-top machines. Most ISPs seem to use your email address and IP address to control access so the fields need to be set up as follows.
    • Enable Mail: Yes
    • WebMasterEmail: Your Full Email Address
    • WebMasterName: Your Name
    • MailProgram: leave setting as is
    • SMTP MailHost: the smtp address of your ISP, something like smpt.greennblue.co.uk
    • SMTP SenderHost: Your Full Email Address
    • SMTP Username: Your Full Email Address
    • SMTP Password: Your Password for the ISP
12. With this configuration hopefully you will be able to send emails regardless of your ISPs desire for authentication. Once working you can try adjustments as you desire but check every change has not broken the connection! Testing the email part of Foswiki is sadly not the easiest of tasks. The best solution I have found is to register a user which then sends an email. If this fails, you will know because of the error message, check the apache log files and the mail section of configure, to remove the partially registered user follow the instructions at http://foswiki.org/TWiki/ManageUsers, please remember not all steps may be needed but do check.
13. If your webserver can be accessed by more than one domain name make sure to add the additional alternative URLs to {PermittedRedirectHostUrls}

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 Foswiki-ing away! However, please remember the security is not high so any malicious person may be able to get access to you Foswiki unless you spend some time improving the configuration, in particularly use Linux to make configuration files read only.