NOTE: 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 TWiki.

NOTE: 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.

Windows Install Cookbook

For a very simple and virtually foolproof installation, with no TWiki or web server knowledge required, see DownloadTWikiVM.

For a very simple install process, suitable for most Windows users wanting a personal wiki, see IndigoPerlCookbook and TWiki04x02WindowsInstallationGuide (for a manual installation process). This is known to work well for TWiki-4.0.0 and later. Not quite as foolproof as DownloadTWikiVM, but requires less RAM.

Introduction

NOTE: This document is outdated, it has not been updated for TWiki 4.1. So check the official TWiki manuals at TWikiDocumentation first, as these have been updated for 4.1, or use one of the alternatives listed on top of this document. In particular, it is now essential to use absolute paths in setlib.cfg with TWiki 4.0, which was not the case for the Sep 2004 release. Also, testenv should not now be used - its replacement, configure, is even better as it also lets you configure TWiki without editing configuration files.

If you are reading this on your own copy of TWiki, please stop and get the latest version from TWiki:TWiki.WindowsInstallCookbook, as it may have useful improvements or fixes.

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

NOTE: This cookbook is not 100% complete (e.g. it doesn't cover authentication setup described by existing documentation), but it has been used successfully for several years - it is quite accurate and should get you started if you follow the instructions. Please provide feedback in TWiki:Codev.WindowsInstallCookbookComments.

NOTE: You will get the best results from following this cookbook exactly, using the same directories, etc - however, if you really do need to vary things, it should be fairly obvious what to do.

Scope

This document covers installation of the TWiki 02-Sep-2004 production release (TWiki:Codev/TWikiRelease02Sep2004) in the following environment - if you want to use a different environment, feel free to use this as a guideline only.

Simplest way to get a whole set of required tools - later versions should be fine

Perl

Cygwin perl-5.8.5-3

Comes with Cygwin, Perl 5.8 is now fine

RCS

Cygwin rcs-5.7-3

Comes with Cygwin

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. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time. If you ever need to install TWiki on Unix/Linux, you'll find this setup is very similar.

Using a different web server is certainly possible, but the setup required for each web server 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.

If you have an older version of any component, do yourself a favour and upgrade it as part of the install process.

Pre-requisites and upgrades

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

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

nano, a very simple text editor, installed optionally during Cygwin installation. Always launch nano with the -w command-line option to turn off wrapping of long lines.

vim, a more sophisticated vi compatible editor that should be familiar to most Unix users

These are both non-GUI editors, but if you prefer to use a GUI editor you can install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.

The Unix/Windows Environment

It's a little known fact that you can use pathnames such as c:/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 environment

TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the c:/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 environment

Apache 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 the httpd.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 environment

Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including ls, 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 Components

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

Apache

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

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.

NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed

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.

On Windows NT/2000/XP you can choose to run Apache as a service or as a normal program - see the Apache docs for details.

apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)

Another useful command is apache -k stop.

Cygwin, Unix tools, Perl and RCS

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

Choose Internet install

On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')

Select c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site

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)

For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown.

NOTE: Do not include lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.

Hit Next to do the installation.

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. A default installation of Cygwin 1.5.10, plus required packages, needs around 150 MB of free disk space - if you are tight on disk space or Internet bandwidth, de-select all but the mandatory packages, but if not, there is no harm in downloading more.

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

You can always come back and re-run the installer again later if you missed anything.

Environment setup:

Set the HOME environment variable to c:\cygwin\home\YOURUSER, where YOURUSER is your userid, e.g. jsmith or administrator.

On Windows NT, XP and 2000: Go into Control Panel, double-click the System icon, and select Advanced, then click Environment Variables. Under User Variables, click New.... Now type HOME (must be upper case) as the variable name, and c:\cygwin\home\YOURUSER as the value, and hit OK.

On Windows 98 and ME - add to AUTOEXEC.BAT and reboot

You can also set TEMP to c:\temp at this point, if you prefer this to editing the Cygwin ~/.profile file. (HOME can't be set in the ~/.profile file.)

Create the c:\cygwin\home\YOURUSER directory

5. Test Cygwin

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

Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command

TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name - bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!

Type rcs -V - you should see the RCS version, 5.7

Type perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.8.5-3 or higher

This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').

This configures /twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).

It is very important that all lines in the output of mount say '(binmode)' at the end of each line

If the lines for C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.

You can now refer to files using Unix paths, e.g. /twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.

Now test this, still using the Cygwin shell:

Type cd /twiki

Type echo hi >t

Type cat -v t - you should see hi as the output

If you see filename errors, your mounts did not work for some reason - check your typing

If you see hi^M as output, your /twiki directory is not in binary mode

Clean up by doing rm t

This setup is written to the Windows registry, so there's no need to put these commands into a .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 the c:/twiki directory.

8. Install TWiki

Unzip the downloaded 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 TWiki20040209.zip

Configuring components

Now that all the components are installed, you need to configure them.

Configuring Apache

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

NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.

1. Configure Apache (part 1)

Using a suitable text editor (see #TextEditing, above) edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows environment settings.

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

Configuring TWiki

NOTE: It should be possible to use c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...

NOTE: Current versions of Cygwin create 'symbolic links' from fgrep and egrep to grep, requiring the settings for these commands to point directly to grep as below (with suitable flags to provide fgrep and egrep behaviour).

If 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 -f *~' 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!

Perl module installation

7. Installing required Perl modules

* NOTE: Before you start this section, make sure you have installed the Cygwin make and gcc packages, which are used by the CPAN installer (gcc is required for modules that include C language code). Look in cygwin\bin for the files names make and gcc. If they are not there, install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist and selecting them in the same way you did the other Cygwin modules.

Some other Perl modules are needed, in addition to the standard modules that are installed with Cygwin. Fortunately, there is an automated tool called cpan that makes installing these modules easy to do. This tool goes to the Perl module archive site, http://www.cpan.org/, downloads each module that you request, and then builds and installs it.

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 Manual Way.

First, you need to install and configure the cpan tool. You only have to do this once. From the Cygwin shell, type the following:

$ export TEMP=/c/temp
$ cpan

Note: Putting the export TEMP=/c/temp command into ~/.profile in cygwin/etc is recommended to make this setting persistent. If you do not make it persistent, you have to type the command every time you want to use cpan. Without the TEMP variable, some modules may fail to install on Windows 2000 or XP and higher.

You will be asked many questions about configuration and preferences - just press Enter to accept the defaults until you get to the questions about mirror sites. If you are behind a proxy-based firewall, also answer the questions about FTP proxies. 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 file downloads by Net::FTP may appear to hang - just wait 5 or more minutes and the CPAN tool should eventually start using ncftpget, which is part of Cygwin and works behind a firewall. If this doesn't work and you are behind a typical NAT-based firewall, try typing the following at the Cygwin shell before running cpan - to force Net::FTP to use passive FTP, letting it get through such firewalls:

$ export FTP_PASSIVE=1

If this works, add this line, export FTP_PASSIVE=1 to your ~/.profile file for future use.

After some files have been downloaded, you will be asked to select your continent, your country, and then one or more mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):

Eventually, you will see the cpan installer's shell prompt, >cpan, which means you are now ready to install a few modules - the tool will do all the work for you.

cpan> install Net::SMTP

This 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

You will see text scrolling by on the screen as cpan finds, builds and installs the module. Watch for any errors, although it should work if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').

cpan> install MIME::Base64

This may already be installed.

After you have installed the Perl modules given above, you can exit the cpan prompt (with the quit command) and paste this URL into your browser:

http://yourdomain.com/bin/testenv

If the installation and configuration is correct, a page full of information about the Apache server, Perl and the wiki will open. Find the section called "Required Perl modules" and try to install each one with cpan to make sure they are all installed.

CPAN: The Manual Way

If you find that cpan doesn't work for you, perhaps because you are behind an uncooperative corporate firewall, you may have to install the modules manually. In this case, you need to read the CPAN INSTALL page and visit the CPAN search site to search for each module. Search for the name shown below, and download the module.

Net::SMTP
Digest::SHA1
MIME::Base64

Usually installation 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 type the following:

$ perl Makefile.PL
$ make
$ make test
$ make install

The 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 by running the tests.

Re-locking RCS files

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

If the testenv script 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, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.

This user named 'system' must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. Revisions cannot be tracked by RCS unless the Apache userid matches that of the RCS file locks.

If you don't want to preserve the revision history and old versions of the files that shipped with the Twiki, the easiest way to reset the locks is to use the Windows file manager to delete the locked RCS files. Open the /twiki/data directory and delete all files that end with ".txt,v~" (the revisions will have one or more "~" symbols in the name). All new revisions will be created with the correct user automatically owning the locks. The only flaw with this method is that the wiki pages will show the old revision numbers until you edit and save them.

You can re-lock files using 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:

NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)

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.

You have now re-locked all the RCS files and are almost ready to start using TWiki!

Edit Configuration Files and Set File Permissions

9. Edit Configuration Files

Note - you may need to change the permissions on the configuration files so that you can edit them. Do that in the most convenient way: we're going to set their permissions correctly for operation in a subsequent step, so don't worry about exactly what permissions you give them just for editing purposes.

Directories twiki/data, twiki/lib, twiki/templates and all their subdirectories should be configured in your Apache server so that they are *not* visible through URLs.

There is subdir-htaccess.txt under twiki installation directory. Copy it into the data, lib and templates subdirectories, naming it .htaccess to have Apache recognize it. Or you may edit the Apache http.conf file to set deny from all there (this is recommended by Apache.org)

Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly.

10. Set File Permissions

For the following configuration use the cygwin shell.

Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755). Use the chmod command (that is: chmod 755 directoryname ).

To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want (that is: chown newowner file and chgrp newgroup file ).

This Guide assumes user SYSTEM ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:

replace SYSTEM with another user if your web server executes scripts under a different name.

HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts ("LOGNAME: ..."), a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file.

replace user twiki with your own username

Set permissions manually.

Set the permission of all files below twiki/data so that they are writable by user SYSTEM. A simple way is to chmod them to -rw-rw-r-- (that is: chmod 664 filename ) and to chown them to SYSTEM.

Set the permission of the twiki/datadirectory and its subdirectories so that files in there are writable by user SYSTEM. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to SYSTEM.

Set the permission of the twiki/pubdirectory and all its subdirectories so that files in there are writable by user SYSTEM. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to SYSTEM.

Email setup

11. Email setup for notification and registration

You need to set the SMTPMAILHOST 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:

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 installation

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

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 it is unset it will not use Net::SMTP and will almost inevitably fail silently).

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

Troubleshooting

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

Permissions

By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e. #!/bin/something). This is what has been used for this cookbook.

You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.

I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the TWikiInstallationGuide's advice, some of which will apply to TWiki:Codev.CygWin, and log any issues in TWiki:Codev.WindowsInstallCookbookComments.

Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg