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:
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
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
, 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
environment variable to
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
mount -b -s c:/twiki /twiki && mount -b -s c:/ /c && mount -b -c /cygdrive && mount
cd /twiki && echo hi >t && cat -v t ;the output should be
hi anything else indicates a problem.
and adapt to local environment as necessary. Change
- DocumentRoot from "C:/apache/htdocs" to "C:/twiki"
- <Directory "C:/apache/htdocs"> to <Directory "C:/twiki">
# Changing default None to All in next line, to enable .htaccess
Allow From All
# Environment setup required to run Apache as service or as a
# standalone process.
# 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
Add an AddHandler line to the
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
# TWiki setup - avoid renaming scripts
AddHandler cgi-script .
Download the latest TWiki release and save it in the c:/twiki directory. Unzip in place.
and adapt to local environment. Pay attention to the section "# variables that need to be changed when installing on a new server:". Example values (assumes cygwin-perl is being used. ActiveState users need a different syntax. Read the real cookbook for details,):
$wikiHomeUrl = "http://yourdomain.com/bin/view";
$defaultUrlHost = "http://yourdomain.com";
$scriptUrlPath = "/bin";
$pubUrlPath = "/pub";
$pubDir = "/twiki/pub";
$templateDir = "/twiki/templates";
$dataDir = "/twiki/data";
$safeEnvPath = "/bin";
$rcsDir = "c:/cygwin/bin";
$egrepCmd = "/bin/grep -E";
$fgrepCmd = "/bin/grep -F";
Edit the CGI Scripts
You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt). Change
#!/usr/bin/perl -wT to
. Example script to do this (explanation
$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]
Perl module installation
From the Cygwin shell, type
(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
Re-lock RCS files
Go to http://yourdomain.com/bin/testenv
- this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.
- backup all the twiki data files:
cd /twiki/data && tar czvf all-files.tar.gz */*
- Edit all the RCS files at once:
perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/' */*,v
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 ~~~.
variable in TWikiPreferences
to an SMTP email host that is reachable and currently working. In the same place, you also want to change
Testing your TWiki Installation
- testenv - use http://yourdomain.com/bin/testenv and check for warnings
- 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 TWiki.cfg. Have a look at the Apache error log,
,and the TWiki error log,
,and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into
.There is also a
file that contains less serious messages.