TWiki using IndigoPerl on Windows

NOTE: See also TWikiOnWindows for other ways to install TWiki on Windows.

Note2: IndigoPerlCookbookTWiki5x1 has updated Steps for TWiki5.1.1

Here's how to install TWiki on on a Windows machine using IndigoPerl. It has been used successfully on:

Windows XP SP2 (Home and Pro)

Windows 2003

Windows 2000

Windows Vista

This process took a Nerd about 15 minutes. So, if you're a normal user, give yourself a couple of hours, not including downloads.

Note: This cookbook describes an installation intended for use as a personal TWiki. As such it doesn't pays much attention to security; the install tacitly assumes that file permissions are not really an issue (if they are an issue for you, and you work out all the details, please update this guide accordingly).

This topic is a TWikiApplication. Enter your required paths, and hit "Rewrite the instructions using these paths" to tailor the instructions for your system.

I want to install IndigoPerl in this directory:

I want to install TWiki in this directory:

Notes on DOS paths:

• For some configurations, you may need to replace the normal Windows back-slash ("\") with a UNIX-style forward-slash ("/"). So keep alert!
• In many places, you will need to use DOS file paths rather than Windows long file names. Remove spaces from all paths!
  • Example: For the Windows path c:\Program Files\IndioPerl , use c:\PROGRA~1\Indigo~1 .

This procedure has three main steps:

1. Installing IndigoPerl
2. Installing TWiki
3. Installing GNUWin32 grep

Step 1: Installing IndigoPerl

1. Create a directory called D:\indigoperl
2. Download, unpack and install IndigoPerl to this directory, and restart Windows.
   • You must disable any running webservers (IIS) and close Skype during installation for Apache to install correctly.
3. When your machine restarts, click Start, click Control Panel, then click System.
4. In the Systems Properties dialog, click the Advanced tab, then click Environment Variables.
5. In the System Variables group, look for the variable labeled "Path" and make sure that it includes D:\indigoperl\perl\bin; in the variable listing. The IndigoPerl setup application should have added this line for you.
   1. If it was not added to your Path variable: Select "Path" then click Edit. At the beginning of the Variable Value box, type D:\indigoperl\perl\bin; and click OK.
      
   2. Click OK, then click OK again.

CHECKPOINT You need to make sure that IndigoPerl is installed and running. Click Start, click Run, then type cmd (or command) and click OK. At the command prompt, type perl -v and press Enter. If perl runs and produces a sensible looking version number, then IndigoPerl is installed properly. Here's what you should see:

Step 2: Installing TWiki

DEVELOPERS AND BLEEDING-EDGE TESTERS (MAD PEOPLE) ONLY Installing a subversion branch, using Tortoise SVN. Only attempt this if you are already comfortable with Windows, with Perl, with TWiki, with Subversion, with Apache, with Life.

1. Download and install Tortoise SVN
2. Create a folder D:\twiki
3. Use tortoise SVN to checkout a branch e.g. http://svn.twiki.org/svn/twiki/trunk in that directory
4. Open a DOS box. cd D:\twiki perl pseudo-install.pl default

ALL OTHER USERS (SANE PEOPLE) Installing a release package

1. Create a folder D:\twiki . To do this, click Start, click Run, then type mkdir D:\twiki and click OK.
2. Download the latest TWiki installation package.
3. Unzip the TWiki package into the D:\twiki directory.

Editing the Configuration Files

If you are impatient and confident, click on the links to view worked examples of httpd.conf and twiki.conf where TWiki is installed at c:\progra~1\twiki and IndigoPerl is installed at c:\progra~1\indigoperl. These examples worked on Windows XP Pro SP2. Otherwise:

1. Open D:\indigoperl\apache\conf\httpd.conf in Notepad, Notepad++ or your favorite text editor.
2. Add the following line to the end of the file:
   include "D:\twiki\twiki.conf"
   • Some installers have found that they had to replace back-slashes ("\") with UNIX-style forward-slashes ("/") and use DOS paths for this change to work! So, C:\Program Files\MyTWiki Install would be written c:/progra~1/mytwik~1 .
3. Save the file.
4. Open D:\twiki\twiki_httpd_conf in Notepad or your text editor.
5. Find and replace all instances of /home/httpd/twiki to D:\twiki .
   • Some installers have found that they had to replace back-slashes ("\") with UNIX-style forward-slashes ("/") and use DOS paths for this change to work! So, C:\Program Files\TWiki would be written c:/progra~1/twiki .
   • Make sure that you keep the trailing slash on your Alias and ScriptAlias paths e.g. Alias /twiki/ "D:\twiki/"
6. Unless you have installed PHP and want to use it, comment out the line that says php_admin_flag engine off.
7. Temporarily comment out the line that says Require user JohnDoe.
   • This line normally restricts who can run the configure program. Once you have TWiki configured properly, and you have created your own user account, you can put the configure script back under authentication.
8. If you plan to authenticate users, then replace AuthUserFile /var/www/twiki/data/.htpasswd with a local file path e.g. AuthUserFile c:/twiki/data/htpasswd
9. Save the file as D:\twiki\twiki.conf .
10. Restart the Apache service.
    • If you have problems, it might help to compare your twiki.conf with this known working example from WinXP
11. Click Start then click Run. Type "cmd" (or "command") and click OK to open a DOS prompt.
12. Type cd D:\twiki\bin and press Enter. Make sure this directory and all files within it are writable (not read-only). If not, the following script will fail.
13. Type perl ../tools/rewriteshbang.pl and press Enter.
14. When prompted Enter path to the interpreter, type D:\indigoperl\perl\bin\perl.exe and press Enter. Then press Enter again to accept the path.
    • You will see that several files have been modified.
      
    • Error Message Permission denied at ../tools/rewriteshbang.pl line 71 . Most likely, you did not have the path to the interpreter exactly correct. Please check it and try again.
    • If running Windows 2003:_ Make sure that your account can write to all of the files in the D:\twiki\bin directory. If they are not writable by you, the error Permission denied at ../tools/rewriteshbang.pl line 71 will appear.
15. At the command prompt, type ipm install Algorithm::Diff and press Enter. The module will be installed.
16. At the command prompt, type ipm install CGI::Session and press Enter. The module will be installed.
17. At the command prompt, type ipm install Error and press Enter. The module will be installed.
    • If ipm cannot install the modules: Make sure that you are not behind a web proxy or that your HTTP_PROXY Environment Variable is correct. If you are behind a proxy server: The HTTP_PROXY environment variable must be correctly set before running ipm. To do this, click Start, click Control Panels, then click System. Click the Advanced Tab, click Environment Variables. In the System Variables group, click New. In Variable Name type HTTP_PROXY and in Variable Value type "http://proxy-address:port" . Click OK, click OK, and click OK again. You may need to restart Windows for this change to take effect.
    • You may need additional modules. See Getting More Modules.
18. Configure TWiki by opening your browser and going to http://localhost/twiki/bin/configure
    • If you get an error when running configure: Double check your httpd.conf settings against the description above
    • If applicable, check your permissions. The web server user has to be able to read all the files in D:\twiki\bin
    • If configure is complaining about not being able to find LocalSite.cfg, then don't worry if this is the first time you have run it. Just follow the steps.
    • If configure is still complaining about not being able to write LocalSite.cfg, then:
      • Check your permissions (if applicable)
      • Check that the LocalLib.cfg file has the correct path to the TWiki lib dir ( %TWIKIDIR/lib)
19. Click Store Settings in the configure interface. In the {StoreImpl} dropdown list, select RcsLite and click Next (at the bottom of the page). This will save your settings.
    
    • RcsLite is a pure-Perl implementation of RCS. If you are able to get RCS installed and working from the command-line, you can change the {StoreImpl} setting to use RcsWrap instead. RcsWrap is faster than RcsLite, but is otherwise identical (they use the same file formats). We recommend you stick to RcsLite unless you have a pressing need for RcsWrap (and the expertise to install it).
    • You will be prompted for a password, or to create a new one. This password is only used to protect configure, and is not the same as your TWiki user password.

      CHECKPOINT You should now be able to visit http://localhost/twiki/bin/view/Sandbox/DoIWork, create the topic and save it. The files D:\twiki\data\Sandbox\DoIWork.txt and D:\twiki\data\Sandbox\DoIWork.txt,v should now exist.

Installing GnuWin32 grep

The command-line grep program is necessary for the search function to work properly. grep is very familiar to UNIX users, where it is used for searching for strings in files.

1. Download GnuWin32 'grep'
2. Install GnuWin32 grep. We highly recommend installing it to c:\Program Files\GnuWin32
3. Edit the Path variable to include the bin subdirectory.
   • To do this, click Start, click Control Panel, then click System. In the Systems Properties dialog, click the Advanced tab, then click Environment Variables. In the System Variables group, select Path and click Edit. At the start of the Variable Value box, type c:\progra~1\GnuWin32\bin; and click OK. Click OK, then click OK again.

   • CHECKPOINT At a command prompt run grep -V to check that the installation succeeded. To do this, click Start then click Run. Type cmd (or command) and click OK. At the command prompt, type grep -V and press Enter.

4. You must now configure TWiki to use your grep. Open your web browser and go to http://localhost/twiki/bin/configure
5. Open the Store Settings section.
6. Set {EgrepCmd} to c:\progra~1\GnuWin32\bin\grep.exe -E %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F%
7. Set {FgrepCmd} to c:\progra~1\GnuWin32\bin\grep.exe -F %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F%

CHECKPOINT Go to http://localhost/twiki/bin/view/TWiki/SiteChanges. This forces TWiki to search for all recent changes to your installation. If it works, you have configured TWiki successfully for grep!

Getting More Modules

You may need additional modules. (for example if you have an odd Windows 2000 setup). The easiest way to get more modules is to use IndigoPerl's package manager.

1. Click Start, click All Programs, click IndigoPerl, then click Perl Console.
   • The Perl Console will open in a web browser.
2. Click GUI Package Manager at the top of the sidebar.
3. Select the modules that you would like to install and click Install.

Notes:

• If you would like to get user authentication to work on your personal TWiki installation, it is necessary to create a {SessionsDir} ( \TMP is usual) directory somewhere on your disk and enter it in configure in the {Security setup} section.

If you have setup a TWiki using this installation procedure and found it easy to follow please tag it as easy_install.

Contributors: CrawfordCurrie, SamHasler, RalfLimmer, BrankoBange, PengfeiChen, AdamCarr, ForrestChristian, TorHovland, JanPerticai, KenLockhart, EnriqueCadalso, BrandonTeoh, TroyChard

Discussion

I refactored fixes suggested by JanPerticai, KenLockhart, EnriqueCadalso and BrandonTeoh back into the procedure.

-- CrawfordCurrie - 21 Aug 2007

to register a new user you must install perl module Authen::SASL, as it is used in sending confirmation e-mail by Net::SMTP->auth. Without it, registration fails! (tested on WinXP SP2)

-- GennadyMetan - 30 Nov 2007

I had to make a small change to twiki/lib/TWiki/Sandbox.pm to get edits to work. The change was to stop prepending / to the filename returned from normalizeFileName (e.g., return @result; instead of return join '/', @result;)

Also, I found it necessary to use forward slashes in the apache config file (twiki.conf)

-- ArnsheaClayton - 16 Apr 2008

while installing Algorithm and CGI modules, i found the command is case-sensitive.

-- MajidHussain - 24 Jul 2008

Instead of "ipm install Algorithm::Diff" (which kept failing with errors), I used "ipm install Algorithm-Diff-1.1902" and this installed with no errors. Also: C:\>ipm install CGI-Session-4.20 instead of CGI::Session (correct me if I'm wrong though, still a noob at this stuff). Also, the httpd.conf link above is broken. I ended up using the section from the Indigoampp install at: http://www.indigostar.com/indigoampp.php

# BEGIN MOD_PERL CONFIG
LoadModule perl_module C:/indigoampp/perl-5.12.1/bin/mod_perl.so
ScriptAlias /perl-bin/ "C:/indigoampp/apache-2.2.15/perl-bin/"

<Directory "C:/indigoampp/apache-2.2.15/htdocs">
  <IfModule mod_perl.c>
    # Files directive is only valid in Directory section
    <Files ~ "\.(pl|cgi)$">
      SetHandler perl-script
      PerlHandler ModPerl::Registry
      Options ExecCGI allow from all
      PerlSendHeader On
    </Files>
  </IfModule>
</Directory>
# END MOD_PERL CONFIG 

-- TroyChard - 2012-04-16

(sorry about lost CrLfs in above comment)

-- TroyChard - 2012-04-16

Thanks Troy for the feedback. I fixed the formatting.

-- PeterThoeny - 2012-04-16

Wow, very nice facelift of this page! Thank you TroyChard!

-- PeterThoeny - 2012-04-18

Hi Peter, thanks, but I had to roll it back... I was still having some issues with setlib.cfg. If I do get it working, I'll definitely come back and restore/revise the steps

-- TroyChard - 2012-04-22

I decided to create a new page called IndigoPerlCookbookTWiki5x1 for this topic. Not sure if that was the right thing to do, but it seems like there's still useful info on this page too.

btw, this was the breakthrough line in twiki.conf to fix setlib.cfg problems PerlSwitches -T -IC:\www\twiki\bin -IC:\www\twiki\lib

-- TroyChard - 2012-04-27