This is a supplement to TWiki:TWiki.TWikiInstallationGuide; see also: MacOSXInstallNotes

---

[What follows is a rough sketch based on my notes from the last couple of deployments. I have another under way during which I'll flesh this out some more. -- ToddJonker]

TWiki works very well on Mac OS X version 10.1.x, although some earlier releases had an Apache CGI problem that causes sporadic breakage.

• It is necessary to install the Developer Tools, either from CD or from Apple's Developer web site. This provides the RCS executables.

• I recommend installing TWiki at the path /Library/WebServer/twiki
  • A clean alternative I prefer is to create an unprivileged ordinary user named twiki and put the twiki files in ~twiki/Sites/ -- DickFurnas - 05 Jan 2004
    • ~twiki provides a natural holding pen for various TWiki related downloads For example, I unzipped the twiki distribution into ~twiki/Virgin/ to serve as a reference copy against which to run diff to compare with the live install. The command diff -r Sites Virgin gives you the works. -- DickFurnas - 05 Jan 2004
    • Most TWiki maintenence which cannot be done from the web interface can be done as the twiki user. -- DickFurnas - 05 Jan 2004
    • Apache Configuration can be done as described in my notes below in a way that avoids being clobbered by Apple system updates. -- DickFurnas - 05 Jan 2004

• Remember that the Apache server runs as user www, so all of the file-permissions must be set accordingly.

Upgrading Perl

MacOS X 10.2 (Jaguar) and earler ship Perl 5.6, and you'll need to upgrade Perl manually. This is not for the faint of heart! Here's what I just did on a fresh Jaguar installation. I have not yet tested TWiki thoroughly on this machine, but I wanted to document what I did before I lose track of the details.

• I remember wrangling with this but do not remember the details. The bottom line is that on my installation,
  perl --version still reports
  This is perl, v5.6.0 built for darwin
  -- DickFurnas - 05 Jan 2004

Since the steps below will replace the standard Jaguar Perl software with a newer version, it is strongly recommended that you backup your system before doing this. Otherwise you may need to reinstall the OS if things get screwed up.

If you don't want to replace the System Perl

Another way to do this is to install a more modern perl via Fink or DarwinPorts. That way you will keep the system perl intact and have a separate one in the /sw/ (Fink) or the /opt/ (DarwinPorts? ) directories. But if you do that, you'll need to run the "rewriteshbang.pl" script to change the scripts so that they call, for instance /opt/local/bin/perl instead of /usr/bin/perl.

-- JohnHorner - 03 Apr 2006

Note that Apple has supplied an article with similar intent: Installing Perl 5.8 on Jaguar, but it involves command-line compilation which may or may not be easier than the CPAN steps below.

This installation takes place using the Terminal. You will need to use an administrative account to do it. The text in bold below indicate what you type.

$ sudo perl -MCPAN -eshell

This starts the interactive CPAN shell. You will need to enter your password to authenticate as an administrator, which is necessary to install the new files. If you have not used CPAN before, you'll have to answer some basic setup questions. In most cases the defaults should be fine.

    [...]

You have no /Users/todd/.cpan/sources/MIRRORED.BY
  I'm trying to fetch one

  Please, install Net::FTP as soon as possible. CPAN.pm installs it for you
  if you just type
      install Bundle::libnet

   [...]

cpan shell -- CPAN exploration and modules installation (v1.52)
ReadLine support available (try ``install Bundle::CPAN'')

Now it is time to install the latest release of Perl proper. Unfortunately, two tests fail on Jaguar (they are documented issues), so you need to force the installation despite the errors.

cpan> force install J/JH/JHI/perl-5.8.0.tar.gz

LOTS of questions here! I just accepted the default for everything, since perl seems to know alot about darwin already. The only things I changed were to cause the default perl installation to be replaced with the new one. The relevant questions are:

Installation prefix to use? (~name ok) [/usr/local] /usr

Pathname where the private library files will reside? (~name ok)
[/Library/Perl] /System/Library/Perl

The last question you'll be asked is:

Run make depend now? [y] 

Respond in the positive and go to lunch. The compile takes a long time. Eventually it will finish. Type q to quit, then restart the CPAN shell.

cpan> install Bundle::libnet

This installs Net::FTP and some other things.

Since the CPAN code itself is out of date, it's probably wise to update it while you're here:

cpan> install Bundle::CPAN

This causes a bunch of things to be installed. I don't know if this is really necessary, but I don't think it will hurt anything.

That should be all you need. Note that I am not a Perl Guru so there may be better ways to do this.

Apache configuration

The webserver configuration file is at /etc/httpd/httpd.conf, which you need to edit as root. [modifying /etc/httpd/httpd.conf invites it being clobbered by Apple system updates. Apple's httpd.conf includes files in /etc/httpd/users/ see my further notes below for details. -- DickFurnas - 05 Jan 2004] Here is my current configuration, which makes TWiki visible via a URL like http://foobar.com/wiki/view

    ScriptAlias /wiki/ "/Library/WebServer/twiki/bin/"
    <Directory "/Library/WebServer/twiki/bin">
        AllowOverride All
        Options ExecCGI
        Allow from all
    </Directory>

    Alias /wikifiles/ "/Library/WebServer/twiki/pub/"
    <Directory "/Library/WebServer/twiki/pub">
        AllowOverride None
        Options None
        Allow from all
    </Directory>

    <Directory "/Library/WebServer/twiki/data">
        Deny from all
    </Directory>
    <Directory "/Library/WebServer/twiki/templates">
        Deny from all
    </Directory>

[ I had to replace part of the line:
ScriptAlias /wiki/ "/Library/WebServer/twiki/bin/"
to say: ScriptAlias /twiki/bin/ "/Library/WebServer/twiki/bin/"
in case this helps anyone else. — GeorgeHarnish - 05 Jan 2004]

[ Apple's httpd.conf includes files found in /private/etc/httpd/users/ which simplifies configuration in a way that will not be clobbered when Apple makes updates to the system files.

I created a file /private/etc/httpd/users/twiki.conf which contains:

Listen 11235
NameVirtualHost *:11235
<VirtualHost *:11235>
ServerName twiki.ref2.net
DocumentRoot "/Users/twiki/Sites"
</VirtualHost>

ScriptAlias /twiki/bin/ "/Users/twiki/Sites/bin/"
<VirtualHost *>
  DocumentRoot  "/Users/twiki/Sites"
  ServerName twiki.ref2.net
</VirtualHost>
 Alias /twiki "/Users/twiki/Sites"
 <Directory "/Users/twiki/Sites/bin">
    Options +ExecCGI
    SetHandler cgi-script
    AllowOverride All
    Allow from all
 </Directory>
 <Directory "/Users/twiki/Sites/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/Users/twiki/Sites/data">
    deny from all
 </Directory>
 <Directory "/Users/twiki/Sites/templates">
    deny from all
 </Directory>

Note: the configuration above, also provides for access on port 11235 in addition to the usual port 80 . My TWiki installation is used both internally and externally to a LAN and did not want to interfere with external use of port 80 through a firewall. -- DickFurnas - 05 Jan 2004]

TWiki configuration

Beyond the normal configuration in lib/TWiki.cfg, you'll need to make the following changes:

#                   Unix egrep command :
$egrepCmd         = "/usr/bin/egrep";
#                   Unix fgrep command :
$fgrepCmd         = "/usr/bin/fgrep";

Fixing the RCS user

Due to some security features in MacOSX (and some other OSes too), you also need to make slight modifications to TWiki's RCS support to ensure that the revision-control files are accessed under the correct user name.

In first section of lib/TWiki.cfg, add:

#                   User name of the web server (for RCS)
$serverUID        = "www";

In lib/TWiki.pm,

• at the end of the use vars qw block, add: $serverUID
• in initialize, before # Make %ENV safer for CGI (around line 156) add these two lines:

    $ENV{'USER'} = $TWiki::serverUID;
    $ENV{'LOGNAME'} = $TWiki::serverUID;

See RcsNonStrictLocking for more details and history of this issue. As of 19 August 2002, this fix hasn't been integrated with the code base.

what does this fix? is this patch still needed and relvant, or have other rcs fixes negated the need? or, is this something that should be brought into the main code?

-- WillNorris - 21 Aug 2004

Issues

• The BeijingRelease I tried, TWiki20020803beta, adds a new requirement for the Perl module MIME::Base64 which apparently isn't shipped with 10.1.5. I haven't yet tried installing it myself. (Reported as bug: MimeBase64NowRequired)

• There are still lurking RCS issues documented at RcsNonStrictLocking and RCSConfigurationOnMacOSX. It would be nice to fix this in BeijingRelease.

• Perhaps one can avoid installing the Developer's Tools (needed for RCS) by using RCSLite, but I haven't tried it.

• Some people are seeing newline problems: MacOSXLineFeeds

-- ToddJonker - 20 Aug 2002

Regarding Perl and related upgrades on Mac OS X: Server Logistics (http://www.serverlogistics.com/downloads-jag.php) conveniently package a number of binaries in installers, for easy upgrades. They have versions for Jaguar (OS 10.2) of such things as perl 5.8.0, apache 2.0.40, mod_perl 1.99_05, php 4.2.3, tomcat 4.1.10, mysql 3.23.52, and postgresql 7.2.2. They also have a subset of these compiled for Puma (OS 10.1) (see http://www.serverlogistics.com/downloads-osx.php)

-- JohnClark - 29 Sep 2002

You can try using Perl 5.8.0 and Apache 2.0 for TWiki, but Perl 5.8.0 may not be ready for prime time (wait for 5.8.1, or preferably use 5.6.1), and Apache 2.0 will require some TWiki patches. However, I've not tried 5.8.0, it may be fine for TWiki.

-- RichardDonkin - 30 Sep 2002

If you can do generic patches, following PatchGuidelines, that support MacOS X without breaking other platforms (i.e. using suitable OS detection, which is already in the TWiki code (CVSget:lib/TWiki.cfg)), it might be possible to get this support into BeijingRelease.

-- RichardDonkin - 07 Jan 2003