====== Trac on SDF ======

This tutorial discusses how to install [[http://trac.edgewall.org/|Trac]], in the words of its creators a minimalistic approach to web-based management of software projects.

==== Contents ====

  - [[#Introduction]]
  - [[#Installing a Trac instance on SDF|Installation]]
  - [[#Running Trac]]
  - [[#Further reading]]

----

===== Introduction =====

Trac includes wiki, bug tracker, milestone plan and an interface to Subversion. It is installed on SDF, so you can setup your own instance and manage your projects.

===== Installing a Trac instance on SDF =====

==== Setting up an SVN repository ====

Skip this step if you want to use Trac //without// a repository. Otherwise run the commands

  $ mkdir .svn_repos
  $ svnadmin create .svn_repos/my-cool-project

to setup a repository named "my-cool-project" in your homedir under "$HOME/.svn_repos". You can then checkout your repository from your home using the [[http://svnbook.red-bean.com/en/1.4/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sshauth|svn+ssh protocol]].

==== Setting up Trac ====

Get started with

  $ trac-admin /path/to/trac initenv

where "/path/to/trac" is the directory where Trac will be installed (it will be created if doesn't exist). The installation routine will ask you a bunch of questions, including your project's name, database connection (default is fine), repository type and path (type in the path you have chosen above, e.g. "~/.svn_repos/my-cool-project") or leave it blank if you didn't setup a repository. **Whenever you are not sure what to do, just hit [return] to use the default.**

If the output finally reads Project environment for 'My cool project' created and Congratulations!, you have just successfully installed Trac. Pat yourself on the back and read on!

===== Running Trac =====

There are currently two ways to run Trac on SDF: with the standalone server "tracd" and as CGI within Apache.

==== Using the standalone server "tracd" ====

This is by far the least painful, but requires the MetaARPA membership because "tracd" opens a port on the machine.

First, run the command

  $ id -u

and note down the number that is printed on the terminal. This will be your port number (to avoid conflicts between users) and will be refered to as "PORT" from here on.

Next, run the command

  $ tracd --port PORT /path/to/trac

You will now be able to connect to your Trac instance with your Browser of Choice™ at http://sverige.freeshell.org:PORT/trac

==== Running Trac as CGI within Apache ====

With this setup, you will be able to run Trac under your own domain. The tradeoff is performance – "tracd" is considerably faster.

Copy "trac.cgi" into your "html/" directory:

  $ cp /usr/pkg/share/trac/cgi-bin/trac.cgi html/

and fix the permissions using "mkhomepg -p". Add the following lines to "trac.cgi" just after the comments:

  import os
  os.environ['TRAC_ENV']='/path/to/trac'

Now Trac can locate the directory containing your instance.

If you rename the CGI to "index.cgi", it can be called just by the directory. In that case, you may consider setting up a subdirectory (like MYPROJECT) and copying the CGI there.

Point your browser to http://YOURLOGIN.freeshell.org/trac.cgi (or even just YOURLOGIN.freeshell.org/MYPROJECT if you renamed the CGI and copied it to the MYPROJECT subdirectory of your html/) to check that it works. Please be patient, CGI takes a while to load the page.

**Note:** If you want to use Trac in your VHOSTed domain at SDF, be sure to put "trac.cgi" into the corresponding domain directory under "html/".

===== Further reading =====

To use prettier URLs, please refer to [[http://trac.edgewall.org/wiki/TracPrettyUrls#Usingmod_rewritefrom.htaccessfiles|Prettier URLs for Trac]].

Most basic information (tickets, milestones, etc.) can be changed through the web interface. However, administrative tasks must be done on the command line using the "trac-admin" command. Please refer to [[http://trac.edgewall.org/wiki/TracAdmin|Trac Admin]] for details.

Lastly, [[http://trac.edgewall.org/wiki/0.10/TracGuide|the Trac User and Administration Guide]] is pretty thorough and should answer all Trac-related questions.