TWiki/TWikiInstallationGuide.mdwn

   1 <div>
   2   <ul>
   3     <li><a href="#TWiki Installation Guide"> TWiki Installation Guide</a><ul>
   4         <li><a href="#Basic Installation"> Basic Installation</a></li>
   5         <li><a href="#Next Steps"> Next Steps</a></li>
   6         <li><a href="#Troubleshooting"> Troubleshooting</a></li>
   7       </ul>
   8     </li>
   9   </ul>
  10 </div>
  11
  12 # <a name="TWiki Installation Guide"></a> TWiki Installation Guide
  13
  14 _Installation instructions for the TWiki 4.1 production release._
  15
  16 If you are upgrading from a previous version of TWiki, you probably want to read [[TWikiUpgradeGuide]] instead.
  17
  18 TWiki should be fine with any web server and OS that meet the [[system requirements|Main/TWikiSystemRequirements]]. The following installation instructions are written for experienced system administrators; please review the [[AdminSkillsAssumptions]] before you install TWiki. If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
  19
  20 **_%H% Hint:_** TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
  21
  22 <a name="StandardInstallation"></a>
  23
  24 ## <a name="Basic Installation"></a> Basic Installation
  25
  26 1. **Download** the TWiki distribution from <http://TWiki.org/download.html>.
  27 2. **Make a directory** for the installation and **unpack the distribution** in it.
  28 3. **Make sure** the user that runs CGI scripts on your system can read and write all files in the distribution. %BR% Detailed instructions on file permissions are beyond the scope of this guide, but in general:
  29   - During installation and configuration, the CGI user needs to be able to read and write _everything_ in the distribution,
  30   - Once installation and configuration is complete, the CGI user needs write access to everything under the `data` and `pub` directories and to `lib/LocalSite.cfg`. _Everything else_ should be read-only.
  31   - Everybody else should be denied access to everything, always.
  32 4. **Make sure** Perl 5 and the Perl CGI library are installed on your system. %BR% 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 in the `twiki/bin` directory. %BR% %H% Some systems require a special extension on perl scripts (e.g. `.cgi` or `.pl`). If necessary, rename all files in `twiki/bin` (i.e. rename `view` to `view.pl` etc). If you do this, make sure you set the `ScriptSuffix` option in [configure](http://www.dementia.org/twiki/configure) (Step 6).
  33 5. **Create the file** `/twiki/bin/LocalLib.cfg`. %BR% There is a template for this file in `/twiki/bin/LocalLib.cfg.txt`. %BR% The file must contain a setting for `$twikiLibPath`, which must point to the absolute file path of your `twiki/lib` e.g. `/home/httpd/twiki/lib`. %BR% %H% If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set `$CPANBASE` to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
  34 6. **Configure the webserver** so you can execute the `bin/configure` script from your browser.
  35   - Explicit instructions for doing this are beyond the scope of this document, though there is a lot of advice on TWiki.org covering different configurations of webserver. To help you out, there's an example Apache `httpd.conf` file in `twiki_httpd_conf.txt` at the root of the package. This file also contains advice on securing your installation. Additionally, see TWiki:TWiki.ApacheConfigGenerator. There's also a script called `tools/rewriteshebang.pl` to help you in fixing up the shebang lines in your CGI scripts.
  36 7. Run the `configure` script from your browser, and resolve any errors or warnings it tells you about.
  37
  38 You now have a basic, unauthenticated installation running. At this point you can just point your Web browser at `http://yourdomain.com/twiki/bin/view` and start TWiki-ing away!
  39
  40 <a name="AuthenticationOfUsers"></a>
  41
  42 ## <a name="Next Steps"></a> Next Steps
  43
  44 Once you have your TWiki running, you can move on to customise it for your users.
  45
  46 - **Review [[TWikiPreferences]] settings** - read through it and set any additional settings you think you might need (you can click the 'Edit' button near the top to edit the settings in place)
  47   - %I% It is recommended to **copy** any settings or variables that you want to customize from [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] and **paste** them into [[Main.TWikiPreferences|Main/TWikiPreferences]]. This will protect your local customizations from being overwritten in later upgrades. See notes at top of [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] for more information.
  48 - **Customize user home pages** - read and change [[NewUserTemplate]].
  49 - **Enable authentication** - read [[TWikiUserAuthentication]].
  50 - **Clear admin notes** - some pages are meant to be customized after choice of authentication - check and update these topics (remove notice):
  51   - [[ChangePassword]]
  52   - [[ResetPassword]]
  53   - [[ChangeEmailAddress]]
  54   - [[TWikiRegistration]] fields can be customzied to the needs of your organization
  55   - [[TWikiAdminGroup]]
  56 - **Enable e-mail notification** - read [[TWikiSiteTools#WebNotify]] to get [[WebChangesAlerts]].
  57 - **Automate update of site statistics** - read [[TWikiSiteTools#WebStatistics]]
  58 - **Automate removal of expired sessions and lease files** - read [[TWikiScripts#tick_twiki_pl]].
  59 - **Enable internationalization** if needed - read TWiki:TWiki/InstallationWithI18N (supplemental documentation on TWiki.org)
  60 - **Install Plugins** if needed - TWiki:Plugins is an extensive library of Plugins for TWiki, that enhance functionality in a huge number of ways. A few Plugins are pre-installed in the TWiki distribution. Installation instructions are included in Plugins you download from TWiki:Plugins.PluginPackage on TWiki.org.
  61 - **Review known issues** - visit TWiki:Codev.KnownIssuesOfTWiki04x01 and fix issues that apply to you.
  62
  63 ## <a name="Troubleshooting"></a> Troubleshooting
  64
  65 - The first step is to re-run the `configure` script and make sure you have resolved all errors, and are happy that you understand any warnings.
  66 - TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
  67 - If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
  68
  69 **_Related Topics:_** [[AdminDocumentationCategory]], TWiki:TWiki.InstallingTWiki