[[PageOutline(2-5,Contents,pullout)]]

= Installing Trac on Mac OS X

This page describes four different ways of installing Trac on Mac OS X: from source, by using Fink, pkgsrc and [http://trac.macports.org/ Macports].

== Installing from source

If you don't have Fink yet or don't want it, you can build everything yourself from the source tarballs by following the instructions in TracOnOsxNoFink.

== Installing With Fink

If you already have [http://fink.sf.net/ Fink], you may prefer to install Trac that way. But multiple people have noticed that SQLite currently won't install, unless you enable [http://fink.sourceforge.net/faq/usage-fink.php?phpLang=en#unstable unstable packages] in Fink; the same goes for the handy trac-py24 packages mentioned a little later on.

'''Note:''' this doesn't seem to be true as of Fink 0.8.1.

'''Note:''' installing with Fink 0.8.1 and Leopard you'll need to add unstable packages to be able to install trac-py24.

'''Note:''' the [http://fink.sourceforge.net/faq/usage-fink.php?phpLang=en#unstable unstable tree] in Fink is actually often advisable over stable since it includes more up-to-date packages.

'''Warning:''' If you wish to use Pysqlite2/SQLite3, you should either create your Trac project after installing pysqlite2-py24 or you will need to manually convert your Trac project database from SQLite2 to SQLite3. Trac tries to load Pysqlite2/SQLite3 in preference to Pysqlite/SQLite2. If your database is SQLite2 and you have Pysqlite2/SQLite3, you will get errors about your database being unknown or encrypted.
{{{#!sh
$ mv trac.db trac2.db
$ sqlite trac2.db .dump | sqlite3 trac.db
}}}

=== Updating Fink

Start by making sure your Fink base system is the most current:

{{{#!sh
$ fink selfupdate
}}}

'''Note:''' it is recommended to have the [http://fink.sourceforge.net/doc/users-guide/packages.php?phpLang=en#src UseBinaryDist option] enabled in fink (defaults to `on` in newer fink installations).

When it's done it will tell you to update the rest of your packages. It's generally ok to defer that until a little later, although it is advisable to update all your packages at that point.

=== Installing SQLite

You can install SQLite this way:

{{{#!sh
$ fink install sqlite3 sqlite3-dev
}}}

'''Note:''' this will install SQLite3. If you want to stay with SQLite2 use the {{{sqlite}}} and {{{sqlite-dev}}} packages instead.

Though ''fink'' manages the administrator/root permissions for you, which might be handy. You probably have to allow fink to use [http://fink.sourceforge.net/faq/usage-fink.php?phpLang=en#unstable unstable packages]. Otherwise it might not be able to find the SQLite package. In FinkCommander->Preferences tick ''Use unstable packages''.

'''Note:''' unless you know what you're doing, you're best off using the system version of SQLite, because Apple include extra code in their build to make file locking work better on a variety of filesystems. There is [http://www.alastairs-place.net/2006/07/sqlite_and_mac/ a patch] available for SQLite 3.3.6 that adds the necessary code if you must build SQLite yourself, but the Apple supplied version (presently 3.1.3) should work fine with Trac.

=== Installing Subversion

Assuming you want Subversion to support secure connections, install it this way (for Mac OS X 10.4):

{{{#!sh
$ fink install svn svn-client svn-swig-py24
}}}

'''Note:''' you can use the -py23 variants if you prefer Python 2.3.

'''Note:''' the non -ssl variants on 10.4 include SSL connection method for Mac OS X 10.4. On 10.3, however, you should do:

{{{#!sh
$ fink install svn-ssl svn-client-ssl svn-ssl-swig-py24
}}}

=== Updating Fink Packages

Now is a good time to have Fink update the rest of its installed packages:

{{{#!sh
$ fink update-all
}}}

=== Installing Clearsilver, pysqlite and Trac

It used to be that Pysqlite and Clearsilver couldn't be installed using Fink; instructions on how to manually download and install them are below. Since then however a new Fink package has appeared:

{{{#!sh
$ fink install trac-py24
}}}

'' See Troubleshooting note below if using trac-py24 ''

You can now set up your [wiki:TracEnvironment Trac environment] as per the usual instructions. If you do end up needing to install pysqlite, Clearsilver and Trac manually after having installed the rest with Fink as above, read on.

=== Setting up Trac using Apple Personal Webserver

'' For a more in depth description read TracInstall ''

To initialize a Trac environment at {{{/path/to/projectenv}}} run the following commands, trac-admin will ask for an existing Subversion repository:

{{{#!sh
$ trac-admin /path/to/projectenv initenv
$ sudo chown -R www /path/to/projectenv
}}}

'''Note:''' Remember to set appropriate permissions for your Subversion repository. (which are? Maybe someone could expand on this?)

The Apache user (by default, www) will need at the very least read-access to the repository, and write-access if you want to be able to do commits over http. However, a permission set blocking users/groups other than www from direct access to the repository is recommended. See [http://subversion.tigris.org/faq.html#reposperms this FAQ] at subversion.tigris.org.

Open the Apache configuration file located in {{{/sw/etc/apache2/sites-enabled/}}} (for 10.4) or {{{/etc/httpd/httpd.conf}}} (for 10.3) for editing:

{{{#!sh
$ sudo nano -w /sw/etc/apache2/sites-enabled/000-default
}}}

Add the following to have Trac appear at {{{yourdomain.tld/webpath}}} (with TracPrettyUrls) and change {{{/path/to/projectenv}}} to your particular setup:

{{{#!apache
Alias /trac/ /sw/share/trac/htdocs/

RewriteEngine On

<Directory "/sw/share/trac/htdocs">
   Options Indexes MultiViews
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>

# You need this to allow users to authenticate
# trac.htpasswd can be created with
# cmd 'htpasswd -c trac.htpasswd' (UNIX)
# do 'man htpasswd' to see all the options
<Location "/webpath/login">
    AuthType Basic
    AuthName "trac"
    AuthUserFile /path/to/projectenv/conf/trac.htpasswd
    Require valid-user
</Location>

SetEnv TRAC_ENV "/path/to/projectenv/"
ScriptAliasMatch ^/webpath(.*) /sw/share/trac/cgi-bin/trac.cgi$1
}}}

Check that the mod_env is enabled in your config. By default, the config is commented out. This is what you are looking for:

{{{#!apache
LoadModule env_module         libexec/httpd/mod_env.so
AddModule mod_env.c
}}}

Now check if Apache is started, and possibly reload the configuration files:

{{{#!sh
$ sudo /sw/sbin/apache2ctl graceful
}}}

'''Note:''' on Trac 10.3 the command is {{{$ sudo /sw/sbin/apachectl graceful}}}.

Your Trac installation should now be available at yourdomain.tld/webpath/.

=== Manually Installing Clearsilver

Download [http://www.clearsilver.net/ Clearsilver] version 0.9.12. Compile it with Python support and install it in the Fink prefix:

{{{#!sh
$ ./configure --prefix=/sw --with-python=/sw/bin/python2.4 --disable-ruby
$ make install
}}}

Change the hard-coded `/usr/local/bin/python` path to `/sw/bin/python2.4` (or `/usr/bin/python` if you're using the system Python)
on the first line of `scripts/document.py` when running {{{make install}}}. 

=== Manually Installing Pysqlite

The file {{{setup.py}}} in the pysqlite distribution doesn't recognize the Darwin platform, so you'll have to add the following lines to {{{setup.py}}}. It should be quite obvious where, but don't put it too late in the list of operating systems it checks:

{{{#!sh
elif sys.platform == "darwin":
    include_dirs = ['/sw/include/']
    library_dirs = ['/sw/lib/']
    libraries = [sqlite]
    runtime_library_dirs = []

    extra_objects = []
}}}

After that modification the installation should be:

{{{#!sh
$ /sw/bin/python2.4 ./setup.py install
}}}

=== Manually Installing Trac

You should now be all set to install Trac using the TracInstall instructions. Make sure to use {{{/sw/bin/python2.4}}} when running the {{{setup.py}}} script. Most likely, you will also need to add the path to svn-python to your path both when running trac-admin from the command line:

{{{#!sh
export PYTHONPATH=/usr/local/lib/svn-python/
}}}

and in your Apache configuration:

{{{#!apache
<Location "/cgi-bin/trac.cgi">
   SetEnv PYTHONPATH "/usr/local/lib/svn-python/"
</Location>
}}}

An alternative to setting PYTHONPATH is to execute the following from the shell once:

{{{#!sh
echo /usr/local/lib/svn-python/ > /sw/lib/python2.4/SVN.pth
}}}

This will cause /usr/local/lib/svn-python/ to be permanently added to the Python search path.

These instructions were originally written by [wiki:JonasBorgstrom Jonas Borgstrom's], and edited by Ryan Schmidt, and probably edited
and corrected by many others. If you find errors or omissions, please edit the page and make the corrections. You can also contact Jonas.

  I recently installed Trac on an Intel Mac and had a bit of a struggle. I was getting some very annoying `ImportError: No module named svn` errors. I noticed that some python packages install to `/Library/Python/2.3/site-packages/` and some install to `/sw/lib/python2.4/site-packages`. (I guess that's the difference between the manual installations and the Fink installations.) I found that inserting this line into `/Library/Pyhton/2.3/site-packages/Extras.pth` got everything going:

{{{#!sh
/sw/lib/python2.4/site-packages
}}}
  - ''[http://www.soundevolution.com.au/ Matt Connolly]''

== Troubleshooting

=== CGI

If you have problems getting Apple's personal web sharing (Apache 1.3) to run trac.cgi with the correct Python interpreter (/sw/bin/python2.4), you can place this dummy {{{trac.cgi}}} in {{{/Library/WebServer/CGI-Executables/}}}:

{{{#!sh
#!/bin/sh
/sw/bin/python2.4 /somewhere/cgi-bin/trac.cgi
}}}

''This is required due to a bug in the way Python locates its own library directory. It is present in all versions of Python up to 2.3.4, but will be fixed in both 2.4 and 2.3.5.''  -- Mark Rowe

Update your python23 installation if you still need this fix:

{{{#!sh
$ fink install python24
}}}

or:

{{{#!sh
$ fink rebuild python24
}}}

=== Trac-py24

If using the Fink packages python24, trac-py24 and clearsilver-py24 you may get the error:

{{{#!sh
No module named neo_cgi
}}}

when using trac-admin or viewing through a web browser. This is because the Fink clearsilver-py24 package does not appear to include its python bindings, so do a manual make of Clearsilver from the corresponding source version to the fink version, then copy the python binding to the python lib:

{{{#!sh
$ cd <source dir>/python
$ sudo cp neo_cgi.so /sw/lib/python2.4/site-packages/
}}}

== Installing using pkgsrc

As an alternative to Fink and compiling by hand, you can install from [http://www.netbsd.org/Documentation/software/packages.html pkgsrc], which runs just as well on Mac OS X as it runs on NetBSD or Linux. See TracOnNetBsd for more information.

Note that at least one person couldn't get this method to work at all.

== Installing using !MacPorts

See also these [http://trac.edgewall.org/wiki/TracOnOsxMacPorts instructions to install Trac with Macports].

Installation steps:

 1. sudo port install subversion +mod_dav_svn
 1. sudo port install mod_python25
 1. sudo port install trac

'''Note''': Macports Trac depends on Python 2.5 so you have to use mod_python25.

Here is the Trac configuration from my httpd.conf:

{{{#!apache
<VirtualHost *>
        ServerName projects.<domain>.com
        DocumentRoot "/Projects/Trac"

         #
         # Trac mod_python configuration
         #
         Alias /trachtdocs/ "/opt/local/share/trac/htdocs/"
         <Location /trac>
                 SetHandler mod_python
                 #PythonHandler trac.ModPythonHandler
                 PythonHandler trac.web.modpython_frontend
                 PythonOption TracUriRoot "/trac"
                 PythonOption TracEnvParentDir "/Projects/Trac"
         </Location>

         <LocationMatch /trac/[[:alnum:]]+/login>
                 AuthType Basic
                 AuthName "Trac"
                 AuthUserFile "/opt/local/etc/trac-auth-file"
                 Require valid-user
         </LocationMatch>
</VirtualHost>
}}}

== Setting up tracd as a launchd service

If you use tracd to locally serve Trac projects under Mac OS X Tiger, you can set it up to be automatically launched by way of Tiger's launchd service. I use tracd instead of Apache because I'm only serving Trac to myself and I don't want to modify Apache configurations. See TracOnOsxTracdAsLaunchdService for a recipe of how to set this up.