1 rizwank 1.1 %META:TOPICINFO{author="PeterThoeny" date="1095486403" format="1.0" version="1.7"}%
2 %TOC%
3 %STARTINCLUDE%
4 ---# Windows Install Cookbook
5
6 ---++ Introduction
7
8 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.
9
10 * __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 over a year now - it is quite accurate and should get you started if you follow the instructions. Please provide feedback in TWiki:Codev.WindowsInstallCookbookComments.
11 * __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.
12
13 -- Main.RichardDonkin - 24 Feb 2002
14
15 ---++ Summary
16
17 %N% - See *[[WindowsInstallSummary]]* for a concise summary of the whole cookbook.
18
19 ---++ Recent updates
20
21 * 28 Jun 2004 - updated to reflect experiences installing beta20040507 on Windows NT
22 rizwank 1.1 * 2 Jun 2003 - updated to include setting =HOME= since this is not always picked up by Cygwin
23 * 30 Apr 2003 - New issue with Perl 5.8 found, added warning not to use Perl 5.8
24 * 02 Mar 2003 - updated to restrict =register= script edits to Dec 2001 release
25 * 30 Nov 2002 - added =binutils= to list of Cygwin packages, and added warning not to use Apache 2.0
26 * 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
27 * 12 Nov 2002 - setting =SMTPMAILHOST= for user registration and notification
28 * Older changes are in TWiki:TWiki.WindowsInstallCookbookHistory
29
30 ---++ Scope
31
32 This 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.
33
34 | *Component* | *Name, version* | *Comment* |
35 | Operating System | Windows 2000 | Should also work for Windows NT |
36 | Web Server | Apache 1.3.27 | Windows-specific security holes fixed in this build <br />(check latest version at http://httpd.apache.org, but *don't* use Apache 2.0 yet) |
37 | Unix tools | Cygwin 1.3.9 | Simplest way to get a whole set of required tools |
38 | Perl| Cygwin perl-5.6.1-2 | Comes with Cygwin, *don't* use Perl 5.8.0 yet |
39 | RCS | Cygwin rcs-5.7-2 | Comes with Cygwin, includes a file corruption bugfix |
40
41 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.
42
43 rizwank 1.1 More recent minor versions should be OK, but they can introduce bugs.
44
45 %N% 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.
46
47 ---+++ Alternatives
48 The following Windows operating systems have been tested following the instructions given here:
49 * Windows NT, 98 and ME all work fine with minor tweaks
50 * Windows XP works in theory, but see the Apache site for details of XP-related bugs, and other packages' sites for any peculiarities of XP. Please report any XP installations on TWiki:Codev.TWikiOnWindowsKnownConfigurations, and comment at TWiki:Codev.WindowsInstallCookbookComments.
51
52 There are doubtless other combinations of components that may work - in particular:
53 * 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.
54 * 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.
55
56 Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.
57
58 For improved performance on Windows through using =mod_perl=, you may want to try TWiki:Codev.WindowsModPerlInstallCookbook.
59
60 ---++ Checking versions
61
62 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:
63
64 rizwank 1.1 <pre>
65 $ <i>: Cygwin DLL version is the number in 1.3.x format</i>
66 $ uname -r
67 $ less c:/<i>your-apache-dir</i>/Announcement
68 $ perl -v
69 $ rcs -V
70 </pre>
71
72 If you have an older version of any component, do yourself a favour and *upgrade it* as part of the install process.
73
74 ---++ Pre-requisites and upgrades
75 You will need to have local administrator rights and be comfortable with Windows administration.
76
77 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!
78 #TextEditing
79 ---+++ Text editing
80 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:
81 * =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.
82 * =vi=, a more sophisticated editor that should be familiar to most UNIX users
83 These both non-GUI editors, but if you prefer to use a GUI editor you should install PFE, a freeware editor that supports Unix format files. PFE is available on [[http://download.cnet.com/downloads/0-4003619-100-904159.html?tag=st.dl.10001-103-1.lst-7-1.904159][download.com]] and [[http://www.simtel.net/pub/dl/11983.shtml][Simtel]].
84
85 rizwank 1.1 Another good TWiki:Codev.OpenSource editor is <nop>SciTE (aka <nop>WSciTE), available at http://www.scintilla.org/SciTE.html.
86
87 ---++ The Unix/Windows Environment
88
89 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.
90
91 The reason this matters is that =='\'== is a special character to Perl and other tools, so it's much easier to use =='/'== everywhere.
92
93 ---+++ The Cygwin environment
94
95 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.
96
97 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.
98
99 ---+++ The Apache environment
100
101 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.
102
103 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.
104
105 ---+++ The Perl environment
106 rizwank 1.1
107 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.
108
109 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.
110
111 ---++ Installing Components
112
113 Enough background, let's get on with the installation.
114
115 ---+++ TWiki (part 1)
116
117 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.
118
119 ---+++ Apache
120 _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....._
121
122 *1. Download Apache*
123 * Check at http://httpd.apache.org/ for any security announcements
124 * Check the latest 1.3.x version number on [[http://www.apache.org/dist/httpd/Announcement.html][this page]]
125 * Find a local mirror using http://www.apache.org/dyn/closer.cgi - choose httpd, then binaries, then win32
126 * The file to download is ==apache_1.3.X-win32-x86-no_src.msi== where 'X' is 20 or higher
127 rizwank 1.1 * Note that this is a Microsoft Installer format file (.MSI)
128
129 * __NOTE__: If you are using Windows NT, download the .MSI installer (==instmsi.exe==) from the [[http://httpd.apache.org/dist/httpd/binaries/win32/][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.
130 * __NOTE__: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed
131
132 *2. Install Apache*
133 * Double-click the .MSI file to run the installer
134 * 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._
135 * On Windows NT/2000 you can choose to run Apache as a service or as a normal program - see the Apache docs for details.
136 * __NOTE__: Needs a bit more detail here... See the excellent documents about [[http://httpd.apache.org/docs/windows.html][Installing Apache on Windows]] and [[http://httpd.apache.org/docs/win_service.html][Running Apache as a Windows NT/2000 service]].
137
138 *3. Test Apache*
139 * If necessary, start apache, by selecting 'Start' from the 'Start->Programs->Apache...->Control Apache Server' menu.
140 * Point your browser at http://yourdomain.com/ to see the Apache intro page.
141
142 Congratulations, you now have a working web server!
143
144 To restart Apache after changing its config, type:
145
146 * =apache -k restart= for standalone Apache process running in another window
147 * =apache -k restart -n apache= for Apache running as a Win2000 service (-n gives name of service)
148 rizwank 1.1
149 Another useful command is =apache -k stop=.
150
151 ---+++ Cygwin, Unix tools, Perl and RCS
152
153 *4. Install Cygwin*
154
155 Head to http://cygwin.com, and click the <img src="%ATTACHURLPATH%/cygwin-icon.gif" alt="cygwin-icon.gif" width="21" height="21" /> __Install or update now!__ link. Save the =setup.exe= in a directory, e.g. =c:\download\cygwin-dist=.
156
157 Now run the Cygwin =setup.exe= file - this will also install Perl and RCS in one fell swoop.
158 * Choose Internet install
159 * 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')
160 * Select =c:\download\cygwin-dist= as the local package directory, and suitable proxy settings, then pick a local mirror site
161 * In the package list screen, hit the *View* button until you get an alphabetical list that says *Full* to the right of the button.
162 * Leave the radio button on *Curr* (Current)
163 * The Current column shows what's installed on your system (if anything)
164 * 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. Make sure you select the following packages - _in recent Cygwin setups you will have to select Perl 5.6.1 explicitly_:
165 * =bash=
166 * =binutils=
167 * =diffutils=
168 * =gcc=
169 rizwank 1.1 * =grep=
170 * =gzip=
171 * =make=
172 * =nano= (or =vim= if you prefer the vi editor)
173 * =ncftp=
174 * =pcre=
175 * =perl= (5.6.1-2 or higher, but *not* 5.8.0)
176 * =rcs= (5.7-2 or higher)
177 * =tar=
178 * =textutils=
179 * =unzip=
180 * =w32api=
181 * =wget= (optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
182 * 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 [[http://cygwin.com/faq/faq.html#SEC32][Cygwin FAQ entry]] and upgrade =libncurses5=.
183 * Hit Next to do the installation.
184 * __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.
185 * __NOTE__: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
186 * Let the installer create the shortcuts suggested
187 * You can always come back and re-run the installer again later if you missed anything.
188
189 Environment setup:
190 rizwank 1.1
191 * Set the =HOME= environment variable to =c:\cygwin\home\YOURUSER=, where =YOURUSER= is your userid, e.g. =jsmith= or =administrator=.
192 * 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.
193 * Windows 98 and ME - add to AUTOEXEC.BAT and reboot
194 * 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.)
195 * Create the =c:\cygwin\home\YOURUSER= directory
196
197 *5. Test Cygwin*
198 * Launch the desktop icon - this runs the =bash= shell, which has command line editing features
199 * Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command
200 * 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!
201 * Type =rcs -V= - you should see the RCS version, 5.7
202 * Type =perl -v= - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
203 * Type =grep home /etc/passwd= - you should see some output.
204
205 The [[http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html][Cygwin User Guide]] is well worth reading for some background on how Cygwin works.
206
207 *6. Configure Cygwin for binary mode*
208 * __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').
209 * This has been a great time sink, causing numerous subtle problems - see TWiki:Codev.CookbookLineEndingProblems
210 * Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'):
211 rizwank 1.1 <pre>
212 $ <b>mkdir /twiki /c c:/twiki</b>
213 $ <b>mount -b -s c:/twiki /twiki</b>
214 $ <b>mount -b -s c:/ /c</b>
215 $ <b>mount -b -c /cygdrive</b>
216 $ <b>mount</b>
217 Device Directory Type Flags
218 C:\cygwin\bin /usr/bin system binmode
219 C:\cygwin\lib /usr/lib system binmode
220 C:\cygwin / system binmode
221 c:\twiki /twiki system binmode
222 c: /c system binmode
223 </pre>
224 * 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=).
225 * It is *very important* that all lines in the output of =mount= say 'binmode' under Flags
226 * 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.
227 * You can now refer to files using Unix paths, e.g. =/twiki/bin/view= or =/c/apache/Announcement= - see the [[http://www.cygwin.com/cygwin-ug-net/using.html][Cygwin documentation]] for more details on this.
228 * Now test this, still using the Cygwin shell:
229 * Type ==cd /twiki==
230 * Type ==echo hi >t==
231 * Type ==cat -v t== - you should see ==hi== as the output
232 rizwank 1.1 * If you see filename errors, your *mounts did not work* for some reason - check your typing
233 * If you see ==hi^M== as output, *your /twiki directory is not in binary mode*
234 * Clean up by doing =rm t=
235
236 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 [[http://cygwin.com/cygwin-ug-net/using-textbinary.html][User Guide section]] and this [[http://cygwin.com/faq/faq.html#SEC54][FAQ entry]].
237
238 ---+++ TWiki (part 2)
239
240 *7. Download TWiki*
241
242 Download the latest TWiki release from http://twiki.org/ and save it in the =c:/twiki= directory.
243
244 *8. Install TWiki*
245
246 Unzip the ZIP file under =c:/twiki= using [[http://www.winzip.com/][<nop>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:
247 <pre>
248 $ <b>cd /twiki</b>
249 $ <b>unzip TWiki20011201.zip</b>
250 </pre>
251
252 ---++ Configuring components
253 rizwank 1.1
254 Now that all the components are installed, you need to configure them.
255
256 ---+++ Configuring Apache
257
258 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 <nop>ScriptAlias commands that are left commented out in this configuration.
259
260 * __NOTE__: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.
261
262 *1. Configure Apache (part 1)*
263
264 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.
265 * Note the trailing '/' characters in various places - they are important!
266
267 * Create the =c:\temp= directory, by typing =mkdir c:\temp= in a DOS command line window
268 * Edit the following lines, some of which already exist in the file:
269
270 <verbatim>
271 # Change this to point to the Apache administrator (e.g. you)
272 ServerAdmin you@yourdomain.com
273
274 rizwank 1.1 # Replaces DocumentRoot "C:/apache/htdocs"
275 DocumentRoot "C:/twiki"
276
277 # Replaces <Directory "C:/apache/htdocs">
278 <Directory "C:/twiki">
279
280 </verbatim>
281
282 * Add the following lines - the Alias and <nop>ScriptAlias lines can be omitted in this setup
283
284 <verbatim>
285 # Alias /twiki/ "C:/twiki/"
286 # ScriptAlias /twiki/bin/ "C:/twiki/bin/"
287 <Directory "C:/twiki/bin/">
288 # RD: Changed None to All in next line, to enable .htaccess
289 AllowOverride All
290 Allow From All
291 Options ExecCGI
292 SetHandler cgi-script
293 </Directory>
294
295 rizwank 1.1 # Environment setup required to run Apache as service or as a
296 # standalone process.
297 <IfModule mod_env.c>
298 # Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
299 # timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT
300 # during non-daylight-savings time (use '-5' for timezones in advance of GMT).
301 SetEnv TZ GMT0BST
302 SetEnv RCSINIT -x,v/
303 # Adjust TEMP and TMP for your server and create directories if necessary
304 SetEnv TEMP c:/temp
305 SetEnv TMP c:/temp
306 SetEnv LOGNAME system
307 SetEnv HOME c:/twiki
308 </IfModule>
309 </verbatim>
310
311 *2. Configure Apache (part 2)*
312
313 Add an <nop>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.
314 * Note the trailing '.' on the <nop>AddHandler line.
315 <verbatim>
316 rizwank 1.1 #
317 # Document types
318 #
319 <IfModule mod_mime.c>
320 # TWiki setup - avoid renaming scripts
321 AddHandler cgi-script .
322 ...
323 </verbatim>
324
325 ---+++ Configuring TWiki
326
327 *3. Configure TWiki*
328
329 Edit the TWiki config file, =c:/twiki/lib/TWiki.cfg= (or in Cygwin terms, =/twiki/lib/TWiki.cfg=) as follows:
330
331 * __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...
332 * __NOTE__: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from =fgrep= and =egrep= to =grep=, requiring the settings for these commands to point directly to =grep= (with suitable flags to provide =fgrep= and =egrep= behaviour).
333
334 <pre>
335 # variables that need to be changed when installing on a new server:
336 # ==================================================================
337 rizwank 1.1 # %WIKIHOMEURL% : link of TWiki icon in upper left corner :
338 $wikiHomeUrl = <b>"http://yourdomain.com/bin/view"</b>;
339 # Host of TWiki URL : (Example "http://myhost.com:123")
340 $defaultUrlHost = <b>"http://yourdomain.com"</b>;
341 # %SCRIPTURLPATH% : cgi-bin path of TWiki URL:
342 $scriptUrlPath = <b>"/bin"</b>;
343 # %PUBURLPATH% : Public data path of TWiki URL (root of attachments) :
344 $pubUrlPath = <b>"/pub"</b>;
345
346 # NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
347 # TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.
348
349 # Public data directory, must match $pubUrlPath :
350 $pubDir = <b>"/twiki/pub"</b>;
351 # Template directory :
352 $templateDir = <b>"/twiki/templates"</b>;
353 # Data (topic files) root directory :
354 $dataDir = <b>"/twiki/data"</b>;
355
356 ....
357
358 rizwank 1.1 # Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
359 # (Note: PATH environment variable is not changed if set to "")
360
361 # On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
362 # - used by 'rcsdiff' to run 'co' program, so PATH must be correct.
363
364 # Unix/Linux setting:
365 # $safeEnvPath = "/bin:/usr/bin";
366
367 # Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
368 # Note that /usr/bin and /bin are identical due to default /usr/bin mount
369 # in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator
370 # meaning that 'c' is interpreted as a pathname, giving Perl taint error.
371 $safeEnvPath = <b>"/bin"</b>;
372
373 # If using ActiveState perl, use Windows paths instead
374 # $safeEnvPath = "c:/cygwin/bin";
375
376 ...
377
378 # RCS directory (find out by 'which rcs') :
379 rizwank 1.1 $rcsDir = <b>"c:/cygwin/bin"</b>;
380
381 ...
382
383 # Unix egrep command :
384 $egrepCmd = <b>"/bin/grep -E"</b>;
385 # Unix fgrep command :
386 $fgrepCmd = <b>"/bin/grep -F"</b>;
387 </pre>
388
389 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.
390
391 * For TWiki:Codev.ActiveState Perl, you need to make these additional edits further down the file - this is the only place where backslashes are needed. (See TWiki:Codev.CookbookActivePerlSetup for some extra Perl setup that should remove the need for these edits.)
392
393 <verbatim>
394 # NOTE: When using ActiveState Perl, you must specify
395 # a full Windows-style pathname, using '\\' for backslashes,
396 # for the ls, egrep and fgrep commands, because Cygwin's shell
397 # is not used - forward slashes are OK in Windows everywhere
398 # except in the cmd.exe shell. Drive letters are OK - e.g.
399 # 'c:\\foo\\ls' will work. When using Cygwin perl, just
400 rizwank 1.1 # use the default '/bin/ls' type settings.
401 #
402 # Unix ls command :
403 $lsCmd = "c:\\cygwin\\bin\\ls";
404 # Unix egrep command :
405 $egrepCmd = "c:\\cygwin\\bin\\grep";
406 # Unix fgrep command :
407 $fgrepCmd = "c:\\cygwin\\bin\\grep";
408 </verbatim>
409
410 ---++ Editing the CGI scripts
411
412 *4. Editing the Shebang lines*
413
414 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.
415 * 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)
416 * Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
417 * Type the Perl line *very carefully*
418 * If you do mis-type the ==perl== line, you can restore from the =.backup= directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.
419
420 <pre>
421 rizwank 1.1 $ <b>cd /twiki/bin</b>
422
423 $ ls
424 attach geturl oops rdiff save testenv viewfile
425 changes installpasswd passwd register search upload
426 edit mailnotify preview rename statistics view
427
428 $ <b>mkdir .backup </b>
429 $ <b>cp * .backup</b>
430
431 $ head -1 view
432 #!/usr/bin/perl -wT
433
434 $ <b>perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]</b>
435
436 $ <b>head -1 view</b>
437 #!c:/cygwin/bin/perl -wT
438
439 $ ls
440 attach geturl oops rdiff save testenv viewfile~
441 attach~ geturl~ oops~ rdiff~ save~ testenv~ view~
442 rizwank 1.1 changes installpasswd passwd register search upload
443 changes~ installpasswd~ passwd~ register~ search~ upload~
444 edit mailnotify preview rename statistics view
445 edit~ mailnotify~ preview~ rename~ statistics~ viewfile
446
447 </pre>
448
449 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.
450
451 Optional step: you can do ='rm <nop>*~'= 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!
452
453 *5. Minor changes to TWiki scripts*
454
455 __TWiki Dec 2001 release only - fixed in Feb 2003 release__
456
457 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 [[#Pre_requisites_and_upgrades][PFE editor]]).
458
459 * Edit the =register= script in =/twiki/bin= - change line 200 to read as follows (insert the ==MIME::Base64::== part):
460
461 <pre>
462 return $user . ':{SHA}' . <b>MIME::Base64::</b>encode_base64(Digest::SHA1::sha1($passwd));
463 rizwank 1.1 </pre>
464
465 * If you are using TWiki:Codev.ActiveState Perl, you also need to update =testenv=, see TWiki:Codev.CookbookActivePerlTestenv
466
467 ---+++ Perl module installation
468
469 *6. Installing required Perl modules*
470
471 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 called =cpan=, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them.
472
473 __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 [[#CPANTheHardWay][CPAN: The Hard Way]].
474
475 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.
476 <pre>
477 $ <b>export TEMP=/c/temp</b>
478 $ <b>cpan</b>
479 </pre>
480 <i>Lots of questions about configuration and preferences - just hit Enter until you
481 get to the questions about mirror sites, but answer the questions about FTP proxies etc
482 if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files,
483 some quite large, as part of this setup process, so be patient...</i>
484 rizwank 1.1
485 __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:
486 <pre>
487 $ <b>export FTP_PASSIVE=1</b>
488 </pre>
489 If this works, add this line to your =~/.profile= file for future use.
490
491 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):
492 <pre>
493 ...
494 (28) Turkey
495 (29) Ukraine
496 (30) United Kingdom
497
498 Select your country (or several nearby countries) [] 30
499
500 (1) ftp://cpan.teleglobe.net/pub/CPAN
501 (2) ftp://ftp.clockerz.net/pub/CPAN/
502 (3) ftp://ftp.demon.co.uk/pub/CPAN/
503 (4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
504 (5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
505 rizwank 1.1 (6) ftp://ftp.plig.org/pub/CPAN/
506 (7) ftp://mirror.uklinux.net/pub/CPAN/
507 (8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
508 (9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
509 Select as many URLs as you like,
510 put them on one line, separated by blanks [] 4 7 8
511
512 Enter another URL or RETURN to quit: []
513 New set of picks:
514 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
515 ftp://mirror.uklinux.net/pub/CPAN/
516 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
517
518 </pre>
519
520 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.
521 * __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).
522
523 <pre>
524 cpan shell -- CPAN exploration and modules installation (v1.59_54)
525 cpan> <b>install Net::SMTP</b>
526 rizwank 1.1 <i>May already be installed - if it is, try 'force install', since it's useful to be able to set
527 firewall and passive FTP configuration when using Net::FTP. <b>Make sure you answer 'Y' to the question
528 about whether you want to configure this package.</b></i>
529 cpan> <b>install Digest::SHA1</b>
530 <i>Lots of output about how CPAN finds, builds and installs the module - watch for
531 any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').</i>
532 cpan> <b>install MIME::Base64</b>
533 <i>May already be installed.</i>
534
535 </pre>
536
537 #CPANTheHardWay
538 ---++++ CPAN: The Hard Way
539 If you find that =cpan= 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 [[http://www.cpan.org/modules/INSTALL.html CPAN INSTALL page]] and visit the [[http://www.cpan.org/ 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 <i>file</i>=). Then do the following:
540 <verbatim>
541 $ perl Makefile.PL
542 $ make
543 $ make test
544 $ make install
545 </verbatim>
546 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.
547 rizwank 1.1
548 ---+++ Re-locking RCS files
549
550 *7. Re-locking files*
551
552 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.
553 * 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=.
554
555 This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.
556
557 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:
558 * __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...)
559
560 <pre>
561 $ <b>cd /twiki/data</b>
562
563 $ : Make a backup of all files
564 $ <b>tar czvf all-files.tar.gz */*</b>
565
566 $ : Test edit a single file to check your typing
567 $ <b>perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v</b>
568 rizwank 1.1
569 $ <b>diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~</b>
570 5c5
571 < system:1.2; strict<nop>;
572 ---
573 > nobody:1.2; strict<nop>;
574
575 $ : Now edit all the RCS files at once - use cursor-up to recall previous command
576 $ <b>perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v</b>
577
578 $ : Check for any remaining files not edited
579 $ <b>grep 'strict;$' */*,v | grep -v system</b>
580
581 $ : Clean up - type this <b>very carefully</b>
582 $ <b>rm */*~~~</b>
583 </pre>
584
585 * *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.
586
587 You have now re-locked all the RCS files and are almost ready to start using TWiki!
588
589 rizwank 1.1 ---+++ Email setup
590
591 *8. Email setup for notification and registration*
592
593 You need to set the =SMTPMAILHOST= in TWiki.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:
594
595 <pre>
596 Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.
597 </pre>
598
599 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.
600
601 ---++ Testing your TWiki installation
602
603 It is important to test your TWiki installation before you release it to other users or put any significant data into it.
604
605 Here are the main things to test:
606
607 * testenv - use =<nop>http://yourdomain.com/bin/testenv= and check for warnings
608 * If you are having installation trouble, download the latest =testenv= from TWiki:Codev/TWikiAlphaRelease and install it in =c:/twiki/bin=. (From TWiki.org, just click CVSget:bin/testenv to get this script)
609 * Page viewing (=view= script) - click around a few pages and make sure the links are OK
610 rizwank 1.1 * RCS diffs (=rdiff= script) - click on the Diffs link and on the '>' links at bottom of page
611 * 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).
612 * 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_.
613 * Try typing =tail -30 /c/apache/logs/error_log= to see last 30 errors from Apache
614 * Edit a page - check revision increased and set to current date/time
615 * 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
616 * Check the Apache =error_log= file to see if there are any RCS errors so far
617 * Index - tests whether =ls= and =grep= are working
618 * Search - more tests for whether =ls= and =grep= are working
619 * Attachments - tests access to =/twiki/pub= directory.
620 * 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.
621 * Check the Apache =error_log= file again
622
623 ---+++ Troubleshooting
624
625 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.
626
627 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).
628
629 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.
630
631 rizwank 1.1 ---+++ Permissions
632
633 TWiki:Codev.CygWin has several models for how it does security:
634
635 * 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.
636 * You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.
637
638 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.
639
640 ---++ Next Steps
641
642 See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the [[TWikiInstallationGuide#Enabling_Authentication_of_Users][section on basic authentication]] - remember to use =c:/twiki= type filenames (i.e. Windows format) since you are using Apache for Windows.
643
644 ---+++ Improved authentication
645
646 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.
647
648 As of the TWiki:Codev.TWikiRelease01Sep2004, there is built in support for several apache based authentication modes. The TWikiInstallationGuide has step-by-step instructions.
649
650 ---+++ Improved performance
651
652 rizwank 1.1 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.
653
654 ---++ Format of filenames
655
656 In your TWiki on Windows installation, it's worth remembering that:
657
658 * Apache configuration files (e.g. the ==.htaccess== file and ==c:/apache/conf/httpd.conf==) always use Windows format paths, with forward slashes, e.g. ==c:/twiki==
659 * The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g. ==c:/cygwin/bin/perl==
660 * All other lines in the Perl scripts use Unix format paths, e.g. ==/twiki== (using Cygwin Perl as per this cookbook)
661 * If you are using TWiki:Codev.ActivePerl, that will use Windows format paths, e.g. ==c:/twiki==
662 * 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
663 * RCS always uses Unix format paths, e.g. ==/twiki==
664
665 ---++ Credits
666
667 Material 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!
668
669 People who've tested or reviewed this document and provided valuable feedback include:
670
671 -- TWiki:Main.BernardFarrell %BR%
672 -- TWiki:Main.BerndSchiffer %BR%
673 rizwank 1.1 -- TWiki:Main.ChrisKeith %BR%
674 -- TWiki:Main.CrawfordCurrie %BR%
675 -- TWiki:Main.DavideBaroncelli %BR%
676 -- TWiki:Main.DavidLeBlanc %BR%
677 -- TWiki:Main.JerryWard %BR%
678 -- TWiki:Main.MartinWittmann %BR%
679 -- TWiki:Main.MaryDeMarco %BR%
680 -- TWiki:Main.MattWilkie %BR%
681 -- TWiki:Main.MikeBytnar %BR%
682 -- TWiki:Main.PeterThoeny %BR%
683 -- TWiki:Main.RossC %BR%
684 -- TWiki:Main.TorbenGB %BR%
685 -- TWiki:Main.VictorGoh %BR%
686 -- TWiki:Main.WolframJahn %BR%
687
688 ---
689 %X% Comments welcome at TWiki:Codev.WindowsInstallCookbookComments
690
691 %META:FILEATTACHMENT{name="cygwin-icon.gif" attr="h" comment="Cygwin icon" date="1092612100" path="C:\Data\Temp\cygwin-icon.gif" size="132" user="PeterThoeny" version="1.1"}%
|
Return to
WindowsInstallCookbook.txt
CVS log
Up to [RizwankCVS] / geekymedia_web / twiki / data / TWiki