Windows Install CookbookIntroductionThis cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline.
Summary - See WindowsInstallSummary for a concise summary of the whole cookbook.
Recent updates
ScopeThis document covers installation of the TWiki 01-Sep-2004 production release (TWiki:Codev/TWikiRelease01Sep2004) in the following environment - if you want to use a different environment, feel free to use this as a guideline only.
Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate users created by the current TWiki user registration script (due to a feature being removed in 2.0, see TWiki:Support.FailedAuthenticationWithApache2OnWinNT). Similarly, Perl 5.8 may introduce issues due to its Unicode features and has caused problems due to a bug in CGI.pm. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki at present. For more information, see TWiki:Codev.IssuesWithApache2dot0 and TWiki:Codev.IssuesWithPerl5dot8.
AlternativesThe following Windows operating systems have been tested following the instructions given here:
mod_perl, you may want to try TWiki:Codev.WindowsModPerlInstallCookbook.
Checking versionsIf you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed:$ : Cygwin DLL version is the number in 1.3.x format $ uname -r $ less c:/your-apache-dir/Announcement $ perl -v $ rcs -VIf you have an older version of any component, do yourself a favour and upgrade it as part of the install process. Pre-requisites and upgradesYou will need to have local administrator rights and be comfortable with Windows administration. This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!Text editingEditing Cygwin files should be done with an editor that can handle Unix file format (see the Cygwin binary mode section below). The installation process suggests:
The Unix/Windows EnvironmentIt's a little known fact that you can use pathnames such asc:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Windows "DOS" command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.
The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.
The Cygwin environmentTWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support thec:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.
When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.
The Apache environmentApache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts. If you need to use spaces in file names (not recommended), put double quotes around the file name in thehttpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.
The Perl environmentOnce Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, includingls, egrep, and the RCS tools that it (typically) launches with the bash shell.
If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.
Installing ComponentsEnough background, let's get on with the installation.TWiki (part 1)Head to http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.ApacheSteps 1 and 2 can be shortcut by opening the self-installing executable on the Apache website that installs Apache 1.3.x. The painful details below are mainly helpful when detecting where things are going wrong..... 1. Download Apache
apache -k stop.
Cygwin, Unix tools, Perl and RCS4. Install Cygwin Head to http://cygwin.com, and click the Install or update now! link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.
Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.
$ mkdir /twiki /c c:/twiki $ mount -b -s c:/twiki /twiki $ mount -b -s c:/ /c $ mount -b -c /cygdrive $ mount Device Directory Type Flags C:\cygwin\bin /usr/bin system binmode C:\cygwin\lib /usr/lib system binmode C:\cygwin / system binmode c:\twiki /twiki system binmode c: /c system binmode
.profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.
TWiki (part 2)7. Download TWiki Download the latest TWiki release from http://twiki.org/ and save it in thec:/twiki directory.
8. Install TWiki
Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:
$ cd /twiki $ unzip TWiki20011201.zip Configuring componentsNow that all the components are installed, you need to configure them.Configuring ApacheThe setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.
c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows environment settings.
# Change this to point to the Apache administrator (e.g. you) ServerAdmin you@yourdomain.com # Replaces DocumentRoot "C:/apache/htdocs" DocumentRoot "C:/twiki" # Replaces <Directory "C:/apache/htdocs"> <Directory "C:/twiki">
# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory "C:/twiki/bin/">
# RD: Changed 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>
2. Configure Apache (part 2)
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.
#
# Document types
#
<IfModule mod_mime.c>
# TWiki setup - avoid renaming scripts
AddHandler cgi-script .
...
Configuring TWiki3. Configure TWiki Edit the TWiki config file,c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:
# variables that need to be changed when installing on a new server: # ================================================================== # http://your.domain.com/twiki : link of TWiki icon in upper left corner : $wikiHomeUrl = "http://yourdomain.com/bin/view"; # Host of TWiki URL : (Example "http://myhost.com:123") $defaultUrlHost = "http://yourdomain.com"; # /twiki/bin : cgi-bin path of TWiki URL: $scriptUrlPath = "/bin"; # /twiki/pub : Public data path of TWiki URL (root of attachments) : $pubUrlPath = "/pub"; # NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using # TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:. # Public data directory, must match $pubUrlPath : $pubDir = "/twiki/pub"; # Template directory : $templateDir = "/twiki/templates"; # Data (topic files) root directory : $dataDir = "/twiki/data"; .... # Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) : # (Note: PATH environment variable is not changed if set to "") # On Windows, $safeEnvPath needs only one component, the directory where RCS is installed # - used by 'rcsdiff' to run 'co' program, so PATH must be correct. # Unix/Linux setting: # $safeEnvPath = "/bin:/usr/bin"; # Using Cygwin perl, so can use Unix-like paths, with ':' as separator. # Note that /usr/bin and /bin are identical due to default /usr/bin mount # in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator # meaning that 'c' is interpreted as a pathname, giving Perl taint error. $safeEnvPath = "/bin"; # If using ActiveState perl, use Windows paths instead # $safeEnvPath = "c:/cygwin/bin"; ... # RCS directory (find out by 'which rcs') : $rcsDir = "c:/cygwin/bin"; ... # Unix egrep command : $egrepCmd = "/bin/grep -E"; # Unix fgrep command : $fgrepCmd = "/bin/grep -F";For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section.
# NOTE: When using ActiveState Perl, you must specify # a full Windows-style pathname, using '\\' for backslashes, # for the ls, egrep and fgrep commands, because Cygwin's shell # is not used - forward slashes are OK in Windows everywhere # except in the cmd.exe shell. Drive letters are OK - e.g. # 'c:\\foo\\ls' will work. When using Cygwin perl, just # use the default '/bin/ls' type settings. # # Unix ls command : $lsCmd = "c:\\cygwin\\bin\\ls"; # Unix egrep command : $egrepCmd = "c:\\cygwin\\bin\\grep"; # Unix fgrep command : $fgrepCmd = "c:\\cygwin\\bin\\grep"; Editing the CGI scripts4. Editing the Shebang lines Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI scripts. This is required so the Apache server knows what interpreter (perl) to use with the scripts.
$ cd /twiki/bin $ ls attach geturl oops rdiff save testenv viewfile changes installpasswd passwd register search upload edit mailnotify preview rename statistics view $ mkdir .backup $ cp * .backup $ head -1 view #!/usr/bin/perl -wT $ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z] $ head -1 view #!c:/cygwin/bin/perl -wT $ ls attach geturl oops rdiff save testenv viewfile~ attach~ geturl~ oops~ rdiff~ save~ testenv~ view~ changes installpasswd passwd register search upload changes~ installpasswd~ passwd~ register~ search~ upload~ edit mailnotify preview rename statistics view edit~ mailnotify~ preview~ rename~ statistics~ viewfileIf for some reason the edit goes wrong, just type cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.
Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!
5. Minor changes to TWiki scripts
TWiki Dec 2001 release only - fixed in Feb 2003 release
If using the Dec 2001 release, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).
return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));
Perl module installation6. Installing required Perl modules Some additional Perl modules are needed, above and beyond the standard modules installed with Cygwin. Fortunately, there is an automated tool that makes it easy to do this - it's calledcpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them.
Note: if you are unable to get cpan working in your environment, don't panic; you can still install the modules manually. In this case, follow the instructions in CPAN: The Hard Way.
First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.
$ export TEMP=/c/temp $ cpanLots of questions about configuration and preferences - just hit Enter until you get to the questions about mirror sites, but answer the questions about FTP proxies etc if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files, some quite large, as part of this setup process, so be patient... NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls:
$ export FTP_PASSIVE=1If this works, add this line to your ~/.profile file for future use.
Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):
... (28) Turkey (29) Ukraine (30) United Kingdom Select your country (or several nearby countries) [] 30 (1) ftp://cpan.teleglobe.net/pub/CPAN (2) ftp://ftp.clockerz.net/pub/CPAN/ (3) ftp://ftp.demon.co.uk/pub/CPAN/ (4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/ (5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ (6) ftp://ftp.plig.org/pub/CPAN/ (7) ftp://mirror.uklinux.net/pub/CPAN/ (8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ (9) ftp://usit.shef.ac.uk/pub/packages/CPAN/ Select as many URLs as you like, put them on one line, separated by blanks [] 4 7 8 Enter another URL or RETURN to quit: [] New set of picks: ftp://ftp.flirble.org/pub/languages/perl/CPAN/ ftp://mirror.uklinux.net/pub/CPAN/ ftp://sunsite.doc.ic.ac.uk/packages/CPAN/Eventually, you'll get to the cpan installer's shell prompt, where you need to install a few modules - the tool will do all the work for you.
cpan shell -- CPAN exploration and modules installation (v1.59_54) cpan> install Net::SMTP May already be installed - if it is, try 'force install', since it's useful to be able to set firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question about whether you want to configure this package. cpan> install Digest::SHA1 Lots of output about how CPAN finds, builds and installs the module - watch for any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make'). cpan> install MIME::Base64 May already be installed. CPAN: The Hard WayIf you find thatcpan doesn't work for you, perhaps because you are behind an uncooperative corporate firewall, you may have to fall back on installing modules manually. In this case, you need to read the CPAN INSTALL page and visit the CPAN search site to search for each module you require. Usually installation simply involves downloading the module distribution into a temporary directory and unpacking it (a .tar.gz or .tgz file is unpacked using tar zxvf file). Then do the following:
$ perl Makefile.PL $ make $ make test $ make installThe make test step should not be skipped - for example, one known problem is with the Digest::SHA1 module on Windows NT, which does not pass its tests and does not work. This causes problems with password encoding. In this event you can use another encoding scheme or switch to unencoded passwords. There may be other problems on the various Windows configurations, and you can save yourself a lot of time.
Re-locking RCS files7. Re-locking files First, some testing: in your browser, 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.
rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:
$ cd /twiki/data $ : Make a backup of all files $ tar czvf all-files.tar.gz */* $ : Test edit a single file to check your typing $ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v $ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~ 5c5 < system:1.2; strict; --- > nobody:1.2; strict; $ : Now edit all the RCS files at once - use cursor-up to recall previous command $ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v $ : Check for any remaining files not edited $ grep 'strict;$' */*,v | grep -v system $ : Clean up - type this very carefully $ rm */*~~~
Email setup8. Email setup for notification and registration You need to set theSMTPMAILHOST in TWikiPreferences to an SMTP email host that is reachable and currently working. Otherwise you may get a confusing message from TWiki (fixed in TWiki:Codev.TWikiRelease01Feb2003) when registering new users or running mailnotify (for WebNotify), along the lines of:
Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.There are other settings to be made in TWikiPreferences, e.g. the WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.
Testing your TWiki installationIt is important to test your TWiki installation before you release it to other users or put any significant data into it. Here are the main things to test:
TroubleshootingIf anything doesn't work, go back and check the configuration of the Apachehttpd.conf file, and TWiki.cfg. 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.
See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).
If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.
PermissionsTWiki:Codev.CygWin has several models for how it does security:
Next StepsSee the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to usec:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.
Improved authenticationYou may want to investigate TWiki:Codev.WindowsInstallModNTLM, which describes how to add an Apache module so that TWiki:Codev.InternetExplorer users are automatically authenticated based on their Windows domain login - this avoids TWiki:Codev.GettingTheUsernameWrong and TWiki:Codev.ForgettingPasswords, which are usually very common among TWiki users. As of the TWiki:Codev.TWikiRelease01Sep2004, there is built in support for several apache based authentication modes. The TWikiInstallationGuide has step-by-step instructions.Improved performanceSee TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache'smod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.
Format of filenamesIn your TWiki on Windows installation, it's worth remembering that:
CreditsMaterial in this cookbook is heavily based on the enormous number of contributions in TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to TWiki:Codev.TWikiOnWindowsArchive to get an idea! People who've tested or reviewed this document and provided valuable feedback include: -- TWiki:Main.BernardFarrell-- TWiki:Main.BerndSchiffer -- TWiki:Main.ChrisKeith -- TWiki:Main.CrawfordCurrie -- TWiki:Main.DavideBaroncelli -- TWiki:Main.DavidLeBlanc -- TWiki:Main.JerryWard -- TWiki:Main.MartinWittmann -- TWiki:Main.MaryDeMarco -- TWiki:Main.MattWilkie -- TWiki:Main.MikeBytnar -- TWiki:Trash.PeterThoeny -- TWiki:Main.RossC -- TWiki:Main.TorbenGB -- TWiki:Main.VictorGoh -- TWiki:Main.WolframJahn  Comments welcome at TWiki:Codev.WindowsInstallCookbookComments
| |||||||||||||||||||
