This is a SupplementalDocument
topic which is not
included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation
of this topic in the comments section below
! Use the Support
web for problems you are having using TWiki.
This is a HistoricalDocument
topic. It used to be distributed in an earlier TWiki release, but is no longer part of the official TWiki distribution. Post questions, error notes, and suggestions concerning the documentation
of this topic in the comments section below
! Use the Support
web for problems you are having using
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
Using Windows 2003 IIs instead of Apache
First, Apache is much easier, but if you are already running IIs and don't want to run two servers, here are some IIs configuration steps.
- Create a virtual directory with path Drive:\twiki
- Add .pl extension c:\cygwin\bin\perl.exe -wT "%s" %s in the Application Configuration form.
- Set the Execute permissions to Scripts only and check Scripts source access.
- Now right click the bin directory and make it a virtual directory as well. It should inherit the previous settings.
- Right click data, pub, and tmp and provide write access.
- Make sure NTFS permissions are set correctly.
- Web Service Extensions for CGI need to be allowed. Set All Unknown CGI Extensions to Allowed first to get everything working, then create an extension to be more specific (e.g. Add c:\cygwin\bin\perl.exe for the File Name).
- Change all scripts to include the .pl extension and also change the invoke line to cygwin as below.
- Now search and replace every setlib.cfg require command to include bin/ (e.g. require 'bin/setlib.cfg'). The reason for this step is that when invoking commands, IIs sets your current working directory to the top virtual directory instead of twiki/bin, so this was the only way I could get it to work. I did not have to do this with Apache.
- Change LocalLib.cfg to include an absolute path to lib (e.g. e:/twiki/lib)
- A mime type of .pl text/html was added, but I don't know if it is necessary.
- Run configure.pl and correct all errors.
What may not work.
- Trying to get Activestate and cygwin RCS to work. This requires additional Perl modifications.
Download, Install & Test Cygwin
|| The following is out of date. You can no longer download perl 5.6 for 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
), then fire up
(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.
-- Contributors: MattWilkie
Comments & Questions about this Supplemental Document Topic
fixed a minor formatting bug
- 21 Feb 2005
Hello...i'm trying to install twiki, but i can't do re-lock rcs files.. my user is projecto and files are locked to user nobody...i want to re-lock all rcs files but something is missing...help me!?
- 02 Aug 2005
This section here is for feedback on the documentation
. Please ask support questions in the Support
- 02 Aug 2005
Added a note at the top and in the cygwin section that you can no longer download perl 5.6 for cygwin. Although I understand that Dakar will run on 5.8.
- 20 Apr 2006
Added a section to help people trying to use IIs instead of Apache.
- 31 May 2007
- 31 May 2007
I met the same problem as MattWilkie
for re-lock rcs files. After I run all the command required for re-lock rcs files, the files is not changed at all.
- 01 Dec 2007
The instructions are very much out of date. For an easy to install TWiki on Windows see TWikiVMDebianStable
. For personal use see TWikiForWindowsPersonal
- 01 Dec 2007