<<O>>  Difference Topic TWikiDocumentation (r1.46 - 15 Aug 2004 - PeterThoeny?)

TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

>
>
document.ondblclick=dblclick; -->

Changed:
<
<
This page contains all documentation topics as one long, complete reference sheet.
>
>
This page contains all documentation topics as one long, complete reference sheet.

Doubleclick anywhere to return to the top of the page.

TOC: No TOC in "TWiki.TWikiDocumentation"

Line: 22 to 25

TWiki Installation Guide

Installation instructions for the TWiki 01-Sep-2004 production release.

If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues.

These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Official documentation for platforms other than Linux is somewhat limited, so please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

Standard Installation

Download the TWiki 01-Sep-2004 distribution in Unix ZIP format from http://TWiki.org/download.html. Please review the AdminSkillsAssumptions before you install TWiki.

Step 1: Create & Configure the Directories

ALERT! NOTE: If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.

  • Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file httpd.conf (typcially located in /etc/httpd/) with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    ALERT! NOTE: The ScriptAlias must come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
  • The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.

Example httpd.conf entries:
 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki/"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twiki/templates">
    deny from all
 </Directory>

  • Restart Apache by service httpd restart (or as appropriate to your flavor of UNIX or Linux).
  • Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
    • Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/
    • Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
    • Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.

Aletrnative Step 1: Create & Configure the Directories for Non-Root Accounts

To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:

  • Download and unzip TWiki on your local PC
  • Using the table below, create a directory structure on your host server
  • Upload the TWiki files by FTP (transfer as text except for the image files in pub)
TWiki dir: What it is: Where to copy: Example:
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates

Note: Don't worry if you are not able to put the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the /twiki/bin/setlib.cfg file (done in Step 3)

Step 2: Set File Permissions

  • Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
    • IMPORTANT:
      • On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Rename all twiki/bin scripts if necessary.
      • Alternatively, you might try creating a file twiki/bin/.htaccess that contains the single line SetHandler cgi-script, which tells Apache to treat all files in this directory as CGI scripts.
  • Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
  • 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.
  • HELP This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
    • replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
      • TIP 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, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
    • 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 nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
    • Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
    • Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
    • HELP The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. You have two options to change ownership of the RCS lock user:
      • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
      • Alternatively, run this in your shell:
        cd twiki/data
        find . -name *,v -exec perl -pi~ -e '$. <= 10 && s/nobody:/www-data:/ ' {} \;
        This will create *,v~ backup files which you should remove after verification:
        find . -name *,v~ -exec rm -f {} \;

Step 3: Edit the Configuration Files

  • Edit the file /twiki/bin/setlib.cfg
    • Set $twikiLibPath to the absolute file path of your /twiki/lib as seen by the web server.
    • ALERT! Attention: Do not leave it as a relative "../lib" path or Plugins might fail to initialize properly
    • You can also edit $localPerlLibPath if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
    • ALERT! Attention: If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the setlib.cfg file.
  • Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
    • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
    • RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
      • Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
        • Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
      • Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
  • Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
  • Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

Step 4: Internationalisation Setup (Optional)

By default, TWiki is configured to support US ASCII letters (no accents) in WikiWords, and ISO-8859-1 (Western European) characters in page contents. If that's OK for you, skip this step.

If your Wiki will be used by non-English speakers, TWiki can be configured for Internationalisation ('I' followed by 18 letters, then 'N', or I18N). Specifically, TWiki will support suitable accented characters in WikiWords (as well as languages such as Japanese or Chinese in which WikiWords do not apply), and will support virtually any character set in the contents of pages. NOTE: TWiki does not currently support UTF-8, so you are advised not to use this - however, improved UTF-8 support is under development, see TWiki:Codev/ProposedUTF8SupportForI18N.

To configure internationalisation suppport:

  1. Edit the TWiki.cfg file's Internationalisation section to set the $useLocale parameter to 1. TWiki will now use the I18N parameters set in the rest of this section.
  2. Type the Unix/Linux command locale -a to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. pl_PL.ISO-8859-2 for Poland. Consult your system administrator if you are not sure which locale to use.
  3. In TWiki.cfg, set the $siteLocale parameter to your chosen locale, e.g. pl_PL.ISO-8859-2 for Poland.
  4. Check your setup using testenv (download the latest testenv from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for I18N setup, and in particular checks that your locale can be used successfully.
  5. (For upgrade of TWiki I18N sites only:) If you were using TWiki:Codev.TWikiRelease01Feb2003 support for I18N, and are using Internet Explorer or Opera, you should re-configure your browser so that it sends URLs encoded with UTF-8 (supported since TWiki:Codev.TWikiRelease01Sep2004). If you are doing a new installation of TWiki, you can ignore this step - no browser reconfiguration is needed for TWiki Release 01-Sep-2004).
    • Internet Explorer 5.0 or higher: in Tools | Options | Advanced, check 'always send URLs as UTF-8', then close all IE windows and restart IE.
    • Opera 6.x or higher: in Preferences | Network | International Web Addresses, check 'encode all addresses with UTF-8'.
    • NOTE: This does not mean that TWiki supports UTF-8 as a site character set.
  6. Try out your TWiki by creating pages in the Sandbox web that use international characters in WikiWords and checking that searching, WebIndex, Ref-By and other features are working OK.

Trouble with I18N?

If international characters in WikiWords do not seem to work, and you are on Perl 5.6 or higher, you may need to set the TWiki.cfg parameter $localeRegexes to 0 - this disables some features but enables TWiki to work even if your system has locales that do not work. Then, set the $upperNational and $lowerNational parameters to the valid upper and lower case accented letters for your locale.

  • NOTE: You will need to do the above workaround for Windows based servers (whether using Cygwin or ActiveState Perl), since Perl locales are not working on Windows as of Feb 2004.

If international characters in WikiWords aren't working, and you are on Perl 5.005 with working locales, keep $useLocale set to 1 and set $localeRegexes to 0, then set $upperNational and $lowerNational - if testenv generates the lists of characters for you, your locales are working so there is no need to set $localeRegexes to 0 in this case. See the comments in TWiki.cfg for more information.

Step 5: Configure Site-Wide Email Preferences

  • Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
    • WIKIWEBMASTER should be set to the email address of the TWiki administrator
    • SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
    • SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
  • You may want to set up other TWikiPreferences later on.
  • To enable the WebChangesAlerts (email notifications) you need to read about cron in the topic TWikiSiteTools.

Step 6: Finish Up from Your Browser

  • Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
    • TIP Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
  • Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
  • Enable email notification of topic changes - TWikiSiteTools has more.
  • Edit the WebNotify topic in all webs and add the users you want to notify.
  • Add the TWiki:Main/PoweredByTWikiLogo to your Main.WebHome topic.
  • You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard installation of TWiki. Read on for server-level customization options.

Additional Server-Level Options

With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.

Enabling Authentication of Users

  • If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. The comment at the top of the file explains what need to be done, basically replace !FILE_path_to_TWiki! and !URL_path_to_TWiki! with paths specific to your installation. For the details of how this file works, consult the HTTP server documentation (for Apache server: [1], [2]).
      • ALERT! NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
      • HELP The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
        • This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
      • ALERT! NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
    2. TWiki now supports several Password file format/encoding methods for Apache. Once you know what method is used by your Appache server, you can configure TWiki to create compatible .htpasswd entries by editing the $htpasswdFormatFamily, $htpasswdEncoding and $htpasswdFilename in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5
    3. Copy the TWikiRegistrationPub topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
  • Customization:
    • You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
    • You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
  • Register yourself in the TWikiRegistration topic.
    • ALERT! NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
  • Create a new topic to check if authentication works.
  • Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
  • Edit the TWikiPreferences topic in the TWiki:TWiki web to set access privileges.
  • Edit the WebPreferences topic in each web, if necessary: set access priviliges.

WYSIWYG Editor

At this time, TWiki does not ship with an "what you see is what you get" editor. TWiki:Codev/IntegrateHtmlAreaEditor describes how to integrate an HTML editor.

ALERT! NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!)

TWiki File System Info

See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2004 distribution.

-- TWiki:Main/PeterThoeny - 29 Aug 2004
-- TWiki:Main/MikeMannix - 16 May 2002


Added:
>
>

Windows Install Cookbook

Introduction

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

-- RichardDonkin? - 24 Feb 2002

Summary

NEW - See WindowsInstallSummary for a concise summary of the whole cookbook.

Recent updates

  • 28 Jun 2004 - updated to reflect experiences installing beta20040507 on Windows NT
  • 2 Jun 2003 - updated to include setting HOME since this is not always picked up by Cygwin
  • 30 Apr 2003 - New issue with Perl 5.8 found, added warning not to use Perl 5.8
  • 02 Mar 2003 - updated to restrict register script edits to Dec 2001 release
  • 30 Nov 2002 - added binutils to list of Cygwin packages, and added warning not to use Apache 2.0
  • 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
  • 12 Nov 2002 - setting SMTPMAILHOST for user registration and notification
  • Older changes are in TWiki:TWiki.WindowsInstallCookbookHistory

Scope

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.

Component Name, version Comment
Operating System Windows 2000 Should also work for Windows NT
Web Server Apache 1.3.27 Windows-specific security holes fixed in this build
(check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet)
Unix tools Cygwin 1.3.9 Simplest way to get a whole set of required tools
Perl Cygwin perl-5.6.1-2 Comes with Cygwin, don't use Perl 5.8.0 yet
RCS Cygwin rcs-5.7-2 Comes with Cygwin, includes a file corruption bugfix

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

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

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

Alternatives

The following Windows operating systems have been tested following the instructions given here:

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

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

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

For improved performance on Windows through using mod_perl, you may want to try TWiki:Codev.WindowsModPerlInstallCookbook.

Checking versions

If you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed:

   $ : Cygwin DLL version is the number in 1.3.x format
   $ uname -r
   $ less c:/your-apache-dir/Announcement
   $ perl -v
   $ rcs -V

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.
  • vi, a more sophisticated editor that should be familiar to most UNIX users
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 download.com and Simtel.

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

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

1. Download Apache

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

  • 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 you can choose to run Apache as a service or as a normal program - see the Apache docs for details.

3. Test Apache

  • If necessary, start apache, by selecting 'Start' from the 'Start->Programs->Apache...->Control Apache Server' menu.
  • Point your browser at http://yourdomain.com/ to see the Apache intro page.

Congratulations, you now have a working web server!

To restart Apache after changing its config, type:

  • apache -k restart for standalone Apache process running in another window
  • 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 cygwin-icon.gif 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. Make sure you select the following packages - in recent Cygwin setups you will have to select Perl 5.6.1 explicitly:
    • bash
    • binutils
    • diffutils
    • gcc
    • grep
    • gzip
    • make
    • nano (or vim if you prefer the vi editor)
    • 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 (optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
    • 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. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
    • NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
  • Let the installer create the shortcuts suggested
  • 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.
    • 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.
    • 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.6.1
  • Type grep home /etc/passwd - you should see some output.

The Cygwin User Guide is well worth reading for some background on how Cygwin works.

6. Configure Cygwin for binary mode

  • 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').
  • Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'):
   $ mkdir /twiki /c c:/twiki
   $ mount -b -s c:/twiki /twiki
   $ mount -b -s c:/ /c
   $ mount -b -c /cygdrive
   $ mount
   Device              Directory           Type         Flags
   C:\cygwin\bin       /usr/bin            system       binmode
   C:\cygwin\lib       /usr/lib            system       binmode
   C:\cygwin           /                   system       binmode
   c:\twiki            /twiki              system       binmode
   c:                  /c                  system       binmode
  • 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' under Flags
    • 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 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 TWiki20011201.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
  • Edit the following lines, some of which already exist in the file:

# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com

# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"

# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">

  • Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup

# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory  "C:/twiki/bin/">
    # RD: Changed None to All in next line, to enable .htaccess
    AllowOverride All
    Allow From All
    Options  ExecCGI
    SetHandler cgi-script
</Directory>

# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
   # Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
   # timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT 
   # during non-daylight-savings time (use '-5' for timezones in advance of GMT).
   SetEnv TZ GMT0BST
   SetEnv RCSINIT -x,v/
   # Adjust TEMP and TMP for your server and create directories if necessary
   SetEnv TEMP c:/temp
   SetEnv TMP c:/temp
   SetEnv LOGNAME system
   SetEnv HOME c:/twiki
</IfModule>

2. Configure Apache (part 2)

Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.

  • Note the trailing '.' on the AddHandler line.
#
# Document types
#
<IfModule mod_mime.c>
    # TWiki setup - avoid renaming scripts
    AddHandler cgi-script .
...

Configuring TWiki

3. Configure TWiki

Edit the TWiki config file, c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:

  • 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: 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).

# variables that need to be changed when installing on a new server:
# ==================================================================
#                   http://your.domain.com/twiki : link of TWiki icon in upper left corner :
$wikiHomeUrl      = "http://yourdomain.com/bin/view";
#                   Host of TWiki URL :    (Example "http://myhost.com:123")
$defaultUrlHost   = "http://yourdomain.com";
#                   /twiki/bin : cgi-bin path of TWiki URL:
$scriptUrlPath    = "/bin";
#                   /twiki/pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath       = "/pub";

# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.

#                   Public data directory, must match $pubUrlPath :
$pubDir           = "/twiki/pub";
#                   Template directory :
$templateDir      = "/twiki/templates";
#                   Data (topic files) root directory :
$dataDir          = "/twiki/data";

....

#                   Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
#                   (Note: PATH environment variable is not changed if set to "")

# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.

# Unix/Linux setting:
# $safeEnvPath      = "/bin:/usr/bin";

# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin.  Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath      = "/bin";

# If using ActiveState perl, use Windows paths instead
# $safeEnvPath      = "c:/cygwin/bin";

...

#                   RCS directory (find out by 'which rcs') :
$rcsDir           = "c:/cygwin/bin";

...

#                   Unix egrep command :
$egrepCmd         = "/bin/grep -E";
#                   Unix fgrep command :
$fgrepCmd         = "/bin/grep -F";

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.

#                   NOTE: When using ActiveState Perl, you must specify
#                   a full Windows-style pathname, using '\\' for backslashes,
#                   for the ls, egrep and fgrep commands, because Cygwin's shell
#                   is not used - forward slashes are OK in Windows everywhere
#                   except in the cmd.exe shell. Drive letters are OK - e.g.
#                   'c:\\foo\\ls' will work.  When using Cygwin perl, just
#                   use the default '/bin/ls' type settings.
#
#                   Unix ls command :
$lsCmd            = "c:\\cygwin\\bin\\ls";
#                   Unix egrep command :
$egrepCmd         = "c:\\cygwin\\bin\\grep";
#                   Unix fgrep command :
$fgrepCmd         = "c:\\cygwin\\bin\\grep";

Editing the CGI scripts

4. Editing the Shebang lines

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.

  • You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
  • Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
  • Type the Perl line very carefully
    • 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.

$ cd /twiki/bin

$ ls
attach   geturl         oops     rdiff     save        testenv  viewfile
changes  installpasswd  passwd   register  search      upload
edit     mailnotify     preview  rename    statistics  view

$ mkdir .backup 
$ cp * .backup

$ head -1 view
#!/usr/bin/perl -wT

$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]

$ head -1 view
#!c:/cygwin/bin/perl -wT

$ ls
attach    geturl          oops      rdiff      save         testenv   viewfile~
attach~   geturl~         oops~     rdiff~     save~        testenv~  view~
changes   installpasswd   passwd    register   search       upload
changes~  installpasswd~  passwd~   register~  search~      upload~
edit      mailnotify      preview   rename     statistics   view
edit~     mailnotify~     preview~  rename~    statistics~  viewfile

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

5. Minor changes to TWiki scripts

TWiki Dec 2001 release only - fixed in Feb 2003 release

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 PFE editor).

  • Edit the register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):

         return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));

Perl module installation

6. Installing required Perl modules

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.

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

First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.

$ export TEMP=/c/temp
$ cpan
Lots of questions about configuration and preferences - just hit Enter until you get to the questions about mirror sites, but answer the questions about FTP proxies etc if you are behind a proxy-based firewall. 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 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:

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

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

...
(28) Turkey
(29) Ukraine
(30) United Kingdom

Select your country (or several nearby countries) [] 30

(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8

Enter another URL or RETURN to quit: []
New set of picks:
  ftp://ftp.flirble.org/pub/languages/perl/CPAN/
  ftp://mirror.uklinux.net/pub/CPAN/
  ftp://sunsite.doc.ic.ac.uk/packages/CPAN/

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.

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

cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTP
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
Lots of output about how CPAN finds, builds and installs the module - watch for 
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64
May already be installed.

CPAN: The Hard Way

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 CPAN INSTALL page and visit the 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 file). Then do 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.

Re-locking RCS files

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

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

$ cd /twiki/data

$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*

$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v

$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
<       system:1.2; strict;
---
>       nobody:1.2; strict;

$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v

$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system

$ : Clean up - type this very carefully 
$ rm */*~~~

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

Email setup

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

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

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

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

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.

Permissions

TWiki:Codev.CygWin has several models for how it does security:

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

Next Steps

See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to use c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.

Improved authentication

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.

As of the TWiki:Codev.TWikiRelease01Sep2004, there is built in support for several apache based authentication modes. The TWikiInstallationGuide has step-by-step instructions.

Improved performance

See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.

Format of filenames

In your TWiki on Windows installation, it's worth remembering that:

  • 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
  • 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
  • All other lines in the Perl scripts use Unix format paths, e.g. /twiki (using Cygwin Perl as per this cookbook)
  • 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
  • RCS always uses Unix format paths, e.g. /twiki

Credits

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!

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

-- TWiki:Main.BernardFarrell
-- TWiki:Main.BerndSchiffer
-- TWiki:Main.ChrisKeith
-- TWiki:Main.CrawfordCurrie
-- TWiki:Main.DavideBaroncelli
-- TWiki:Main.DavidLeBlanc
-- TWiki:Main.JerryWard
-- TWiki:Main.MartinWittmann
-- TWiki:Main.MaryDeMarco
-- TWiki:Main.MattWilkie
-- TWiki:Main.MikeBytnar
-- TWiki:Main.PeterThoeny
-- TWiki:Main.RossC
-- TWiki:Main.TorbenGB
-- TWiki:Main.VictorGoh
-- TWiki:Main.WolframJahn


ALERT! Comments welcome at TWiki:Codev.WindowsInstallCookbookComments



TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004

Overview

This guide describes how to upgrade from TWiki 01-Feb-2003 to TWiki 01-Sep-2004. This is a major new release. You can chose between an automated upgrade using a script or a manual update.

Upgrade Requirements

  • Please review the AdminSkillsAssumptions before you upgrade TWiki
  • To upgrade from a 01-Feb-2003 standard installation to the latest 01-Sep-2004 TWiki Production Release, follow the instructions below
  • NOTE: To upgrade from a pre-01-Feb-2003 TWiki, start with TWikiUpgradeTo01Feb2003
  • To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline

Major Changes Compared to TWiki 01-Feb-2003

  • Automatic upgrade script, and easier first-time installation
  • Attractive new skins, using a standard set of CSS classes, and a TWikiSkinBrowser to help you choose
  • New easier-to-use save options
  • Many improvements to SEARCH
  • Improved support for internationalisation
  • Better topic management screens
  • More pre-installed Plugins: CommentPlugin, EditTablePlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin
  • Improved Plugins API and more Plugin callbacks
  • Better support for different authentication methods
  • Many user interface and usability improvements
  • And many more enhancements, see the complete change log at TWikiHistory

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing TWiki installation because it leaves that untouched.

If you would prefer to do things manually than trust a beta script, skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution.

It will:

  • Create a new TWiki installation, placing the files from the distribution there as appropriate
  • Where possible, merge the changes you've made in your existing topics into the new twiki
  • Where not possible, it will tell you, and you can inspect those differences manually
  • Create new configuration files for the new TWiki based on your existing configuation information
  • Set the permissions in the new TWiki so that it should work straight away
  • Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
  • Tell you what else you need to do

To perform the upgrade, you need to:

  • Check first if there is a newer UpgradeTwiki script available, see TWiki:Codev.UpgradeTwiki
  • Create a new directory for your new installation: Let's call this distro/
  • Put the distribution zip file in distro/
  • Unzip it
  • Choose a directory for the new installation. I will call this new_twiki. This directory must not already exist.
  • Change directory to distro/ and run:
    ./UpgradeTwiki <full path to new_twiki>

Assuming all goes well, UpgradeTwiki will give you the final instructions.

There are a few points worth noting:

  • UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with
  • UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
    • Clearly you need to point it to a location where there is enough space
    • If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed
  • UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation
  • If you have done tricky stuff with $OS in your existing TWiki.cfg file, then you will need to manually examine the new TWiki.cfg file and possibly put your tricky changes in there manually

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

  1. Back up and prepare:
    • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib
    • Create a temporary directory and unpack the ZIP file there
  2. Update files in TWiki root:
    • Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones
  3. Update template files:
    • Overwrite all template files in $TWIKIROOT/templates with the new ones
      • If you have customized your templates, make sure to merge those changes back to the new files
    • If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files
    • Change to view templates and skins:
      • Add %BROADCASTMESSAGE% somewhere on the top of the rendered HTML page (see the new view.tmpl for reference)
    • Changes to edit templates and skins:
      • Change the form action from preview to save:
        <form name="main" action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post">
      • Change the topic action to the following:
        %TMPL:DEF{"topicaction"}%
        <input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" />
        <input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" />
        <input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" />
        <input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" />
        <input type="submit" class="twikiSubmit" name="action" value="Save" id="save" />%TMPL:END%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, rename the scrips to include the required extension, e.g. .cgi
    • Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
    • Edit your existing $TWIKIROOT/bin/.htaccess file to include a directive for the new rdiffauth script:
      <Files "rdiffauth">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
      • Certain hosted environments require a 755 (do so if you get a "Premature end of script headers" messages in the Apache error log)
    • For Windows hosts, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook
  5. Update library files:
    • Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one
    • Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server"
    • Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one
    • Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
    • Pay attention to the file and directory permissions, the library files should not be executable but the directory files should be, e.g. chmod 664 `find -type f $TWIKIROOT/lib` (for files) and chmod 775 `find -type d $TWIKIROOT/lib` (for directories)
  6. Update data files:
    • Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody. In case not:
      • The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, for example www-data
      • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
      • Alternatively, execute the shell script commands described in TWikiInstallationGuide#StepTwo
    • In the temporary twiki/data/TWiki directory where you unzipped the installation package:
      • Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebPreferences.*, WebStatistics.* and all WebTopic* files
    • Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
    • Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones
    • Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt. Notable changes are:
      • New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
      • New ATTACHFILESIZELIMIT setting for maximum size of FileAttachments in KB, 0 for no limit
      • New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory
    • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user
  7. Adapt the other webs (all other than TWiki and _default):
    • Add WebLeftBar topic. See WebLeftBarExample for a clean example, and WebLeftBarCookbook for more information. (WebLeftBar is used by the PatternSkin skin)
    • Add WebSearchAdvanced topic, which has this one line:
      %INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%
    • Consider changing WebPreferences settings:
      • New NOAUTOLINK setting to prevent automatic linking of WikiWords and acronyms
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  8. Update pub files:
    • Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory
    • Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user
    • Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory
  9. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address any potential problems
    • Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users
    • Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.

Known Issues

-- TWiki:Main.PeterThoeny - 29 Aug 2004


 <<O>>  Difference Topic TWikiDocumentation (r1.42 - 16 Jan 2003 - PeterThoeny?)

Changed:
<
<
TWiki Reference Manual (01-Dec-2001)
>
>
TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

This page contains all documentation topics as one long, complete reference sheet.
Doubleclick anywhere to return to the top of the page.

 <<O>>  Difference Topic TWikiDocumentation (r1.39 - 03 Dec 2001 - MikeMannix?)