Windows Install Cookbook

Introduction

-- RichardDonkin^? - 24 Feb 2002

Recent updates

• 30 Nov 2002 - added binutils to list of Cygwin packages, and added warning not to use Apache 2.0
• 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
• 12 Nov 2002 - setting SMTPMAILHOST for user registration and notification

Scope

Why this choice of packages? Because I've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated, with a recent TWiki-relevant bug fix in Feb 2002. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.

More recent minor versions should be OK, but they can introduce bugs.

Alternatives

There are doubtless other combinations of components that may work - in particular:

• TWiki:Codev.ActiveState Perl involves only minor changes to TWiki.cfg, and is probably a simpler choice if you need an easy way to install mod_perl (see TWiki:Codev.ModPerl). TWiki:Codev.ActiveState Perl can be substituted without too much hassle, and in fact the same TWiki.cfg can be used for both TWiki:Codev.ActiveState and Cygwin Perl.
• Using a different web server is certainly possible, but the setup required for each webserver varies greatly (see TWiki:Codev.TWikiOnWindows for pages about specific web servers). You may find it easiest to get a working system with Apache and then switch over to another web server.

Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.

Checking versions

If 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:

Pre-requisites and upgrades

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 editing

Another good TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at http://www.scintilla.org/SciTE.html.

The Unix/Windows Environment

The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.

The Perl environment

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.

Apache

1. Download Apache

• Check at http://httpd.apache.org/ for any security announcements
• Check the latest 1.3.x version number on this page
• Find a local mirror using http://www.apache.org/dyn/closer.cgi - choose httpd, then binaries, then win32
• The file to download is apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher

• NOTE: If you are using Windows NT, download the .MSI installer (instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.

2. Install Apache

• Double-click the .MSI file to run the installer
• Specify c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.

• • NOTE: Needs a bit more detail here... See the excellent documents about Installing Apache on Windows and Running Apache as a Windows NT/2000 service.

3. Test Apache

• Point your browser at http://yourdomain.com/ to see the Apache intro page.

Congratulations, you now have a working web server!

4. Install Cygwin

Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.

• Choose Internet install

• In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.
• Leave the radio button on Curr (Current)
  • The Current column shows what's installed on your system (if anything)

• • bash
  • binutils
  • diffutils

• • grep
  • gzip
  • make

• • ncftp
  • pcre

• • rcs (5.7-2 or higher)
  • tar
  • textutils

• • NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is gcc, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
  • NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
• Let the installer create the shortcuts suggested

5. Test Cygwin

• Launch the desktop icon - this runs the bash shell, which has command line editing features

7. Download TWiki

8. Install TWiki

1. Configure Apache (part 1)

• Note the trailing '/' characters in various places - they are important!

• Create the c:\temp directory, by typing mkdir c:\temp in a DOS command line window

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.

Configuring TWiki

4. Editing the Shebang lines

• 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)
• Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
• Type the Perl line very carefully

6. Installing required Perl modules

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
$ cpan

$ export FTP_PASSIVE=1

• NOTE: You will need to have previously installed the Cygwin make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer).

Re-locking RCS files

7. Re-locking files

8. Email setup for notification and registration

   Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.

• 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

• • 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

You 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.

Improved performance

See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_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.

People who've tested or reviewed this document and provided valuable feedback include: