1 rizwank 1.1 %META:TOPICINFO{author="PeterThoeny" date="1092610965" format="1.0" version="1.1"}%
  2             %META:TOPICPARENT{name="WindowsInstallCookbook"}%
  3             ---+!! Nutshell Summary of Windows Install Cookbook
  4             
  5             This summary of WindowsInstallCookbook is for you if:
  6             	* You've already installed TWiki on Windows before and want a quick refresher of the important points.
  7             	* 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.
  8             
  9             Table of Content:
 10             %TOC%
 11             
 12             ---++ The Essentials
 13             
 14             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.
 15             
 16             TWiki also requires the RCS revision control system but is more picky about which flavour (this guide uses RCS-cygwin).
 17             
 18             Head to http://twiki.org/ and download the latest release.
 19             
 20             ---++ Download, Install & Test Apache-Win32
 21             http://www.apache.org/dyn/closer.cgi  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.
 22 rizwank 1.1 
 23             ---++ Download, Install & Test Cygwin
 24             http://cygwin.com, 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.
 25             	* 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_ ).
 26             	* 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=
 27             
 28             Set the =HOME= environment variable to =c:\cygwin\home\administrator= through the Control Panel, System applet.
 29             
 30             Fire up Cygwin and verify the version numbers are correct. RCS: 5.7, Perl: 5.6.1.
 31             
 32             Configure cygwin for binary mode __omitting this step leads to a partially working system that corrupts RCS files__. 
 33             	* Configure: =mount -b -s c:/twiki /twiki && mount -b -s c:/ /c && mount -b -c /cygdrive && mount=
 34             	* Test: =cd /twiki && echo hi >t && cat -v t= ;the output should be ==hi== _anything else indicates a problem._
 35             
 36             ---++ Configure Apache
 37             
 38             Edit =c:/apache/conf/httpd.conf= and adapt to local environment as necessary. Change
 39             	* <nop>DocumentRoot from "C:/apache/htdocs" to "C:/twiki"
 40             	* &lt;Directory "C:/apache/htdocs"> to &lt;Directory "C:/twiki">
 41             	* Add:
 42             <verbatim>
 43 rizwank 1.1 <Directory  "C:/twiki/bin/">
 44             	 # Changing default None to All in next line, to enable .htaccess
 45             	 AllowOverride All
 46             	 Allow From All
 47             	 Options  ExecCGI
 48             	 SetHandler cgi-script
 49             </Directory>
 50             
 51             # Environment setup required to run Apache as service or as a
 52             # standalone process.
 53             <IfModule mod_env.c>
 54             	# Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
 55             	# timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT 
 56             	# during non-daylight-savings time (use '-5' for timezones in advance of GMT).
 57             	SetEnv TZ GMT0BST
 58             	SetEnv RCSINIT -x,v/
 59             	# Adjust TEMP and TMP for your server and create directories if necessary
 60             	SetEnv TEMP c:/temp
 61             	SetEnv TMP c:/temp
 62             	SetEnv LOGNAME system
 63             	SetEnv HOME c:/twiki
 64 rizwank 1.1 </IfModule>
 65             </verbatim>
 66             
 67             Add an !AddHandler line to the ==&lt;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.
 68             <verbatim>
 69             #
 70             # Document types
 71             #
 72             <IfModule mod_mime.c>
 73             	 # TWiki setup - avoid renaming scripts
 74             	 AddHandler cgi-script .
 75             </IfModule>
 76             </verbatim>
 77             
 78             ---++ Install TWiki
 79             
 80             Download the latest TWiki release and save it in the c:/twiki directory. Unzip in place.
 81             
 82             ---+++ Configure TWiki
 83             
 84             Edit =c:/twiki/lib/TWiki.cfg= 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,):
 85 rizwank 1.1 <verbatim>
 86             $wikiHomeUrl		= "http://yourdomain.com/bin/view";
 87             $defaultUrlHost	= "http://yourdomain.com";
 88             $scriptUrlPath	 = "/bin";
 89             $pubUrlPath		 = "/pub";
 90             $pubDir			  = "/twiki/pub";
 91             $templateDir		= "/twiki/templates";
 92             $dataDir			 = "/twiki/data";
 93             $safeEnvPath		= "/bin";
 94             $rcsDir			  = "c:/cygwin/bin";
 95             $egrepCmd			= "/bin/grep -E";
 96             $fgrepCmd			= "/bin/grep -F";
 97             </verbatim>
 98             
 99             ---+++ Edit the CGI Scripts
100             
101             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_  =#!c:/cygwin/bin/perl -wT= . Example script to do this ([[WindowsInstallCookbook#Editing_the_CGI_scripts][explanation]]):
102             	* =$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]=
103             
104             ---+++ Perl module installation
105             
106 rizwank 1.1 From the Cygwin shell, type =export TEMP=/c/temp= (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= 
107             
108             ---+++ Re-lock RCS files
109             
110             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.
111             	* backup all the twiki data files: <code>cd /twiki/data && tar czvf all-files.tar.gz */*</code>
112             	* Edit all the RCS files at once: <code>perl -pi~~~ -e 'NR &lt;= 10 && s/nobody:/system:/' <nop>*/*,v </code>
113             
114             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.
115             
116             After a few days of everything working well come back and delete the files which end with ~~~.
117             
118             ---+++ Email Setup
119             
120             Set the =SMTPMAILHOST= variable in TWiki.TWikiPreferences to an SMTP email host that is reachable and currently working. In the same place, you also want to change =WIKIWEBMASTER= and =SMTPSENDERHOST=.
121             
122             ---++ Testing your TWiki Installation
123             
124             	* testenv - use http://yourdomain.com/bin/testenv and check for warnings
125             	* Page viewing (view script) - click around a few pages and make sure the links are OK
126             	* RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page
127 rizwank 1.1 	* 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.
128             		* 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.
129             		* Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
130             	* Edit a page - check revision increased and set to current date/time
131             	* 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
132             	* Check the Apache error_log file to see if there are any RCS errors so far
133             	* Index - tests whether ls and grep are working
134             	* Search - more tests for whether ls and grep are working
135             	* Attachments - tests access to /twiki/pub directory.
136             
137             		* 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.
138             	* Check the Apache error_log file again
139             
140             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.
141