How to Install and Setup Trac

How to Install and Setup Trac

Trac is an web-based issue tracking and project management system. It is written in Python, and can use SQLite or Postgres as its database backend. Currently, MySQL support is only experimental, and not recommended for production use.

These instructions are designed to take you through the process of installing Trac on a brand-new (S or M) Accelerator.

These instructions are also based on installing Trac 0.11.1.

If you do wish to install Trac 0.10, you should be able to do so through either Blastwave or Pkgsrc.

Trac 0.11.1 provides a large number of improvements over Trac 0.10, including a new, native-Python templating system.

Preflight

Prerequisites

This tutorial assumes that pkgsrc is available to install initial dependencies (although pkgsrc is not used to install Trac itself).

If you ordered your Accelerator after March 22 2008, pkgsrc should be setup and you're good to go. If you ordered an Accelerator before March 22 2008, please follow the step-by-step instructions for installing pkgsrc before continuing with these instructions.

You'll use pkgsrc to install the latest available versions of following packages:

Python (2.4)
Subversion (1.4.4) (with Python bindings)
SQLite3 (and Python bindings)
py-PgSQL (Postgres Python bindings)

Assumptions

This tutorial assumes you want to use Trac with Subversion. It is also possible to use Trac with the Mercurial (hg) and git version control systems.

Install SQLite 3 (databases/sqlite3)

Trac uses SQLite as its default database backend. To install, you'll need to make two changes:

work around a known issue: databases-sqlite3
choose the thread-safe version of SQLite: http://trac.edgewall.org/wiki/PySqlite#TheSQLitelibrary

  cd /opt/pkgsrc/databases/sqlite3/
  nano Makefile

and change the line from:

   CONFIGURE_ARGS+=

to:

   CONFIGURE_ARGS+=        --disable-tcl --enable-threadsafe

   bmake extract
   gsed -i"" 's/B_/BOOL_/g' work/sqlite-3.4.2/tool/lemon.c
   bmake install

Alternatively, you can choose to use SQLite 2. In which case, consult these known issues for information on how to build.

Install Python, Subversion, Database Bindings

Build and install Python:
```
cd /opt/pkgsrc/lang/python24 && bmake install
```
(see also Python on Accelerators)

Build and install Subversion and Python bindings:

cd /opt/pkgsrc/devel/subversion && bmake install
cd /opt/pkgsrc/devel/py-subversion && bmake install

Build and install Python XML support (expat bindings):
```
cd /opt/pkgsrc/textproc/py-expat && bmake install
```
Build and install Python Database Bindings:
1. if you want to use Trac with SQLite 3:
```
cd /opt/pkgsrc/databases/py-sqlite2 && bmake install
```
2. and/or, if you want to use Trac with PostgreSQL:
```
cd /opt/pkgsrc/databases/py-PgSQL && bmake install
```
By default, pkgsrc installs a binary as python2.4. Create a symbolic link:
```
ln -s "/opt/local/bin/python2.4" /opt/local/bin/python
```
Recommended: If you want additional markup language support for your Trac wiki and and ticketing system, then installing Textile and reStructured Text support is highly recommended. To install:
```
cd /opt/pkgsrc/textproc/py-textile && bmake install
cd /opt/pkgsrc/textprox/py-docutils && bmake install
```
Optional: Trac 0.11 uses the Genshi templating system, but some older Trac plugins may still use the Clearsilver templating system. If you know you might want to use older plugins, build and install Clearsilver:
```
cd /opt/pkgsrc/www/py-clearsilver && bmake install
```

If chose to install SQLite 2, and not SQLite 3, install the Python bindings for that version. Replace step 4 with:

  cd /opt/pkgsrc/databases/py-sqlite && bmake install

Install Trac

Create a new directory for Python source:

mkdir -p /opt/local/python
cd /opt/local/python

Download and install EasyInstall:

wget http://peak.telecommunity.com/dist/ez_setup.py
python ./ez_setup.py

Use EasyInstall to install the Genshi and Pygments text-processors into your Python site-packages directory (currently, these text processors are unavailable through pkgsrc):
```
easy_install Pygments
easy_install Genshi
```
In future versions of Trac, installation should just be a matter of easy_install trac, but for now we'll build the latest version from Subversion:
1. For Trac 0.11.1:
```
   # svn co http://svn.edgewall.org/repos/trac/tags/trac-0.11.1 trac-0.11
```
2. For Trac trunk:
```
   # svn co http://svn.edgewall.org/repos/trac/trunk trac-0.11
```

Then:

   # cd trac-0.11
   # python setup.py install

Verify trac-admin, the console-based admin tool, and tracd, the built-in simple webserver, installed successfully:

   # which trac-admin
   trac-admin is /opt/local/bin/trac-admin
   # which tracd
   tracd is /opt/local/bin/tracd

Textile and Docutils can also be installed with easy_install, but its a good idea to keep install what you can through pkgsrc, as pkgsrc only knows about what is installed through it. In the case that python needs to be upgraded or reinstalled through pkgsrc, anything in site-packages folder not installed through pkgsrc may be nixed and reinstalling manually.

   # easy_install docutils
   # easy_install textile

Switching between Trac versions

Once you follow the instructions on this page all the way through (including setting up tracd as a Service, you should find that switching between a tag in Subversion and the trunk, a simple matter of issuing the following commands:

   # svn switch http://svn.edgewall.org/repos/trac/trunk
   # svn switch http://svn.edgewall.org/repos/trac/tags/trac-0.11.1
   # svn up
   # python setup.py install
   # svcadm restart tracd

Outfitting Trac

This step is optional, but the following plugins are useful in many scenerios and provide customization far beyond which is included in a standard installation.

After each easy_install you should restart your Trac instance to use the plugin:

svcadm restart tracd

Account Manager

Form-based authentication against a number of backends, rather than the default basic authentication:

  easy_install http://trac-hacks.org/svn/accountmanagerplugin/trunk

Full Blog Plugin

Provides blogging capability within Trac:

  easy_install http://trac-hacks.org/svn/fullblogplugin/0.11

Theme Engine Plugin

Provides full look and feel customization for your Trac installation:

easy_install http://trac-hacks.org/svn/themeengineplugin/0.11/

See documentation for more information.

Creating a new Trac instance

To be added

Creating a Service, SMF Manifest

Create a new file on your server tracd.xml, and copy the contents of the following into it:

<?xml version="1.0"?>
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
 
<service_bundle type="manifest" name="tracd">
    <service name="network/tracd" type="service" version="1">
        <create_default_instance enabled="true"/>
        
        <single_instance/>
 
        <dependency name="fs" grouping="require_all" restart_on="none" type="service">
            <service_fmri value="svc:/system/filesystem/local"/>
        </dependency>
        
        <dependency name="net" grouping="require_all" restart_on="none" type="service">
            <service_fmri value="svc:/network/loopback:default"/>
        </dependency>
 
        <exec_method type="method" name="start" exec="/opt/local/bin/tracd -d -p 9001 -e /home/trac/sites" timeout_seconds="60">
            <method_context>
                <!-- method_credential user='USER' group='GROUP' -->
                <method_environment>
                   <envvar name="PATH" value="/usr/bin:/bin:/opt/local/bin"/>
                   <envvar name="LC_CTYPE" value="en_US.ISO8859-1"/>
                </method_environment>
            </method_context>
        </exec_method>
            
        <exec_method type="method" name="stop" exec=":kill" timeout_seconds="60">
            <method_context/>
        </exec_method>
        
        <exec_method type="method" name="refresh" exec=":kill &amp;&amp; /opt/local/bin/tracd -d -p 9001 -e /home/trac/sites" 
timeout_seconds="60">
                        <method_context>                                                                                                               
                <!-- method_credential user='USER' group='GROUP' -->                                                                       
                <method_environment>                                                                                                       
                   <envvar name="PATH" value="/usr/bin:/bin:/opt/local/bin"/>                                                              
                   <envvar name="LC_CTYPE" value="en_US.ISO8859-1"/>                                                                       
                </method_environment>                                                                                                      
            </method_context>  
        </exec_method>
        
        <template>
            <common_name>
                <loctext xml:lang="python">Trac Client Daemon</loctext>
            </common_name>
            <documentation>
                <manpage title="tracd" section="1M"/>
                <doc_link name='trac.edgewall.org' uri='http://trac.edgewall.org/'/>
            </documentation>
        </template>
        
    </service>
</service_bundle>

Check for for any typos:

 # xmllint --valid tracd.xml

Then import the Service manifest:

 # svccfg import tracd.xml

You should then be able to start up tracd:

 # svcadm enable tracd

Proxying from Apache

# cd /opt/csw/apache2/etc/virtualhosts
# touch trac.YOURHOSTNAME.com.conf

And add the following lines to trac.YOURNAME.com.conf in your favorite editor:

<VirtualHost YOURPUBLICIP:80>
ServerName         trac.YOURHOSTNAME.com
ProxyPreserveHost  On
ProxyPass          / http://127.0.0.1:9001/
ProxyPassReverse   / http://127.0.0.1:9001/
</VirtualHost>

Restart Apache:

# svcadm restart http:cswapache2

Upgrading Trac

Minor Release Upgrade (for 0.11.x)

If you followed an older version of these instructions for installing Trac 0.11 (such as for one of the beta or Release Candidate version), you may upgrade to the latest minor version as follows (see also the note Changing Versions above):

Disable the current Trac instance and change to your Python source directory:
```
# svcadm disable tracd
# cd /opt/local/python
```
If you're unsure of the latest version of Trac 0.11, type the following to see a list of released (tagged) versions:
```
# svn ls http://svn.edgewall.org/repos/trac/tags/ | grep trac-0.11
```
Change into your Trac 0.11 working directory:
```
# cd trac-0.11
```

Use 'svn switch' to change to the latest tagged version and update:

# svn switch http://svn.edgewall.org/repos/trac/tags/trac-0.11.1
# svn up

Then proceed to install as normal:
```
# python setup.py install
```
Re-enable your Trac instance:
```
# svcadm enable tracd
```
Finally, depending on the upgrade path you chose, you may need to upgrade the wiki pages and database for each of your site instances. Change to your Trac sites directory and for each Trac site that you're running:
```
# trac-admin <site_name> upgrade
# trac-admin <site_name> wiki upgrade
```

Backing up Trac

See Backing up your Accelerator.

Acknowledgements

These instructions are influenced by a set of articles entitled “Pimping your Trac and Python on TextDrive”, written by Ches Martin:

Joyent