TWiki Installation Guide

Installation instructions for the TWiki 4.1 production release.

If you are upgrading from a previous version of TWiki, you probably want to read TWikiUpgradeGuide instead.

TWiki should be fine with any web server and OS that meet the system requirements. 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)

Hint: TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.

Basic Installation

1. Download the TWiki distribution from http://TWiki.org/download.html.
2. Make a directory for the installation and unpack the distribution in it.
3. Make sure the user that runs CGI scripts on your system can read and write all files in the distribution.
   Detailed instructions on file permissions are beyond the scope of this guide, but in general:
   • During installation and configuration, the CGI user needs to be able to read and write everything in the distribution,
   • 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.
   • Everybody else should be denied access to everything, always.
4. Make sure Perl 5 and the Perl CGI library are installed on your system.
   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.
   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 (Step 6).
5. Create the file /twiki/bin/LocalLib.cfg.
   There is a template for this file in /twiki/bin/LocalLib.cfg.txt.
   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.
   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.
6. Configure the webserver so you can execute the bin/configure script from your browser.
   • 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.
7. Run the configure script from your browser, and resolve any errors or warnings it tells you about.

Next Steps

• 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)
  • It is recommended to copy any settings or variables that you want to customize from TWiki.TWikiPreferences and paste them into Main.TWikiPreferences. This will protect your local customizations from being overwritten in later upgrades. See notes at top of TWiki.TWikiPreferences for more information.
• Customize user home pages - read and change NewUserTemplate.
• Enable authentication - read TWikiUserAuthentication.
• Clear admin notes - some pages are meant to be customized after choice of authentication - check and update these topics (remove notice):
  • ChangePassword
  • ResetPassword
  • ChangeEmailAddress
  • TWikiRegistration fields can be customzied to the needs of your organization
  • TWikiAdminGroup
• Enable e-mail notification - read TWikiSiteTools#WebNotify to get WebChangesAlerts.
• Automate update of site statistics - read TWikiSiteTools#WebStatistics
• Automate removal of expired sessions and lease files - read TWikiScripts#tick_twiki_pl.
• Enable internationalization if needed - read TWiki:TWiki/InstallationWithI18N (supplemental documentation on TWiki.org)
• 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.
• Review known issues - visit TWiki:Codev.KnownIssuesOfTWiki04x01 and fix issues that apply to you.

Troubleshooting

• 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.
• TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
• If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

Related Topics: AdminDocumentationCategory, TWiki:TWiki.InstallingTWiki