Nutshell Summary of Windows Install Cookbook

This summary of WindowsInstallCookbook is for you if:

• You've already installed TWiki on Windows before and want a quick refresher of the important points.
• You've never installed TWiki on Windows before, but find the WindowsInstallCookbook too much to swallow right now. It is recommended you read through this summary to build a picture of the overall process, and then use the full cookbook as your guide as you actually do the install.

Table of Content:

The Essentials

TWiki will run on any combination of Operating System + Perl + Webserver. TWiki requires all three but doesn't care which three. Each permutation has its own quirks to deal with. Which combination is easiest depends on your personal background and experience. This guide covers only one possible configuration of many: Windows 2000/XP + Perl-Cygwin + Apache-Win32.

TWiki also requires the RCS revision control system but is more picky about which flavour (this guide uses RCS-cygwin).

Head to http://twiki.org/ and download the latest release.

Download, Install & Test Apache-Win32

http://www.apache.org/dyn/closer.cgi and download apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher. There are some issues with Apache 2, see TWiki:Codev.IssuesWithApache2dot0.

Download, Install & Test Cygwin

http://cygwin.com, and click the Install Cygwin Now link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist. Run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.

• Choose Internet Install ; make sure default text file type is unix.; If you have the bandwidth and the drive space it is easier just to install everything ( Install All ).
• The following packages are the minimal installation (~12mb): bash, binutils, diffutils, gcc, grep, gzip, make, nano, ncftp, pcre, perl (5.6.1-2 or higher, but not 5.8.0), rcs (5.7-2 or higher), tar, textutils, unzip, w32api, wget

Set the HOME environment variable to c:\cygwin\home\administrator through the Control Panel, System applet.

Fire up Cygwin and verify the version numbers are correct. RCS: 5.7, Perl: 5.6.1.

Configure cygwin for binary mode omitting this step leads to a partially working system that corrupts RCS files.

• Configure: mount -b -s c:/twiki /twiki && mount -b -s c:/ /c && mount -b -c /cygdrive && mount
• Test: cd /twiki && echo hi >t && cat -v t ;the output should be hi anything else indicates a problem.

Configure Apache

Edit c:/apache/conf/httpd.conf and adapt to local environment as necessary. Change

• DocumentRoot from "C:/apache/htdocs" to "C:/twiki"
• <Directory "C:/apache/htdocs"> to <Directory "C:/twiki">
• Add:

<Directory  "C:/twiki/bin/">
    # Changing default None to All in next line, to enable .htaccess
    AllowOverride All
    Allow From All
    Options  ExecCGI
    SetHandler cgi-script
</Directory>

# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
   # Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
   # timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT 
   # during non-daylight-savings time (use '-5' for timezones in advance of GMT).
   SetEnv TZ GMT0BST
   SetEnv RCSINIT -x,v/
   # Adjust TEMP and TMP for your server and create directories if necessary
   SetEnv TEMP c:/temp
   SetEnv TMP c:/temp
   SetEnv LOGNAME system
   SetEnv HOME c:/twiki
</IfModule>

Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation. Note the trailing '.' on the AddHandler line.

#
# Document types
#
<IfModule mod_mime.c>
    # TWiki setup - avoid renaming scripts
    AddHandler cgi-script .
</IfModule>

Install TWiki

Follow the TWikiInstallationGuide to install TWiki. The webserver should already be configured to run configure, but before you do so you will have to edit the "shebang" lines in the scripts in bin and change them all to

#!c:/cygwin/bin/perl -wT

Perl module installation

You may see errors that indicate you have to install additional Perl modules. From the Cygwin shell, type export TEMP=/c/temp (add it to ~/.profile), then fire up cpan (will ask a schwack configuration questions if it hasn't been run before) and install =Net::SMTP, Digest::SHA1, MIME::Base64

If something goes wrong: to restore your existing files from the backup, just type tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.

After a few days of everything working well come back and delete the files which end with ~~~.

Testing your TWiki Installation

• Page viewing (view script) - click around a few pages and make sure the links are OK
• RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page
• Edit a page, and register as a new user - tests page creation, use of register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences.
  • If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.
  • Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
• Edit a page - check revision increased and set to current date/time
• Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines
• Check the Apache error_log file to see if there are any RCS errors so far
• Index - tests whether ls and grep are working
• Search - more tests for whether ls and grep are working
• Attachments - tests access to /twiki/pub directory.

• • Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.
• Check the Apache error_log file again

If anything doesn't work, go back and check the configuration of the Apache httpd.conf file, and examine configure. Have a look at the Apache error log, c:/apache/logs/error_log ,and the TWiki error log, /twiki/data/log*.txt ,and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt .There is also a /twiki/data/warning.txt file that contains less serious messages.