Trac

Trac is an open source project management tool and bug tracker.

Getting Started with Trac

To set up a Trac application to work with a Subversion or Git repository, follow the steps in this section.

Create Applications and a Website

First, create a version control repository, Trac application, and website:

  1. Create a version control repository application.

    1. Log in to the control panel.

    2. Click Domains / websites ‣ Applications. The list of applications appears.

    3. Click the Add new application button. The Create a new application form appears.

    4. In the Name field, enter a name for the version control application.

    5. In the App Category menu, click to select Git or Subversion.

    6. If applicable, in the Machine menu, click to select a web server.

    7. If you selected Git, in the Extra info field, enter a password for the default user.

      See also

      See Strengthening Passwords for important information about choosing passwords.

      If you selected Subversion, you may optionally enable anonymous read access. To enable anonymous read access, in the Extra info field, enter anonymous_read.

    8. Click the Save button. The application is installed and added to the list of applications.

  2. Create a Trac application.

    1. Click the Add new application button. The Create a new application form appears.
    2. In the Name field, enter a name for the Trac application.
    3. In the App Category menu, click to select Trac.
    4. In the App Type menu, click to select a Trac variant. If you selected Subversion for version control, choose a Subversion Trac variant. If you selected Git for version control, choose a Git Trac variant.
    5. If applicable, in the Machine menu, click to select a web server.
    6. In the Extra info field, enter the name of the version control repository application.
    7. Click the Save button.
  3. Create a website to serve the version control repository and Trac applications.

    1. Click Domains / websites ‣ Websites. The list of websites appears.

    2. Click the Add new website button. The Create a new website form appears.

    3. In the Name field, enter a website name.

    4. If applicable, in the Machine menu, click to select the server to host the website.

    5. If you want your site served over an HTTPS connection, click to select Encrypted website (https).

    6. For each domain name you want to use with the website, add it to the list of domains. In the Domains field, enter the domain name. Enter one or more domain names. If the domain has not yet been added to the control panel, click the Create link that appears at the bottom of the list of domains to add it.

    7. Click Add an application ‣ Reuse an existing application. The Reuse an existing web app form appears.

    8. Click to select the Trac application.

    9. Click the Save button. The application is added to the website’s list of applications.

    10. Click Add an application ‣ Reuse an existing application. The Reuse an existing web app form appears.

    11. Click to select the version control repository application.

    12. In the URL field, enter a URL path for the repository (for example, /repository, /svn, or /git).

    13. Click the Save button. The application is added to the website’s list of applications.

    14. Click the Save button. The website is created and added to the list of websites.

  4. Wait two minutes for the changes to take effect.

Now your Trac site is ready to use at the specified domain.

Customizing the Trac Application

Now that your Trac site is working, here are some additional steps for customizing and controlling Trac:

Enabling Email Notifications

Trac can be configured to send email notifications to ticket owners, reporters, and CC subscribers that have provided an email address in their preferences. To enable Trac email notifications:

  1. Open ~/webapps/trac/conf/trac.ini in a text editor, where trac is the name of the Trac application.
  2. Change the mail configuration settings in the [notification] section:
    1. Replace email_sender = SmtpEmailSender with email_sender = SendmailEmailSender.
    2. Replace smtp_enabled = false with smtp_enabled = true.
    3. Replace smtp_from = trac@localhost with smtp_from = from_address where from_address is the outgoing email address to be used by your Trac application. Many users opt to use a “no-reply” address.
    4. Replace smtp_from = trac@localhost with smtp_replyto = replyto_address where replyto_address is the email address to be used in Trac notification email messages’ Reply-To header. Many users opt to use a “no-reply” address.
    5. Optional: To have all notifications sent to a specific address (for example, a mailing list or project manager), replace smtp_always_cc = with smtp_always_cc = cc_addresses, where cc_addresses is a comma-separated list of email addresses.
  3. Save and close the file.

Now Trac will send email notifications on ticket change events.

See also

To make additional customizations to your Trac email notifications, please see the Trac wiki page Email Notification of Ticket Changes.

Enabling reStructuredText

Our Trac environment does not support reStructuredText (RST) by default. To enable reStructuredText, you must install docutils in your home directory or in your Trac application’s lib directory. To install docutils:

  1. Open an SSH session to your account.
  2. Install docutils.
    • To install docutils to your home directory, enter easy_install-2.6 docutils and press Enter.
    • To install docutils to your Trac application’s lib directory, enter PYTHONPATH=$HOME/webapps/trac/lib/python2.6 easy_install-2.6 --install-dir=$HOME/webapps/trac/lib/python2.6 --script-dir=$HOME/webapps/trac/bin docutils, where trac is the name of the Trac application as it appears in the control panel, and press Enter.

You can now use reStructuredText markup in Trac.

Managing Users

Trac users are managed with .htpasswd file in ~/webapps/trac, where trac is the name of the Trac application.

See also

Alternatively, you may also install the Account Manager Plugin to manage users with a web interface.

To add a user or change an existing user’s password:

  1. Open an SSH session.

  2. Switch to the Trac directory. Enter cd ~/webapps/trac and press Enter.

  3. Enter htpasswd .htpasswd username, where username is the user account to modify, and press Enter. A password prompt appears.

    Note

    Trac usernames may not be all uppercase characters.

  4. Enter the new password and press Enter.

    See also

    See Strengthening Passwords for important information about choosing passwords.

  5. Reenter the new password and press Enter.

  6. Optional: To grant admin privileges to the user, enter ./bin/trac-admin . permission add username TRAC_ADMIN, where username is the user account to modify, and press Enter.

    Note

    You can also grant this privilege from Trac’s Admin interface with an existing admin user:

    1. Log in to the Trac site.
    2. Click Admin. The Basic Settings page appears.
    3. Click Permissions. The Manage Permissions page appears.
    4. In the Subject field, enter the username.
    5. In the Action menu, click to select TRAC_ADMIN.
    6. Click the Add button.

To delete a user:

  1. Open an SSH session.
  2. Switch to the Trac directory. Enter cd ~/webapps/trac and press Enter.
  3. Enter htpasswd -D .htpasswd username, where username is the user to delete, and press Enter.

Disable .htpasswd Authentication

By default, Trac applications installed with the control panel use basic access authentication to control access. To disable authentication:

  1. Open an SSH session to your account.
  2. Switch to the Trac application directory. Enter cd ~/webapps/trac, where trac is the name of the Trac application as it appears on the control panel, and press Enter.
  3. Enter echo -e "Satisfy Any\nAllow from all" > .htaccess and press Enter.

Changing the Git Repository Path

For Trac applications that use Git for version control, you can use a different Git repository by editing the value of repository_dir in trac.ini. To edit the value of repository_dir:

  1. Open your Trac application’s trac.ini file in a text editor. The full path to the file is ~/webapps/app/conf/trac.ini, where app is the name of your Trac application.

  2. Find the repository_dir key in the [trac] section of the file. It will look something like this:

    repository_dir = /home/username/webapps/mygit/repos/proj.git
    
  3. Replace the existing path with an absolute path to the root of a Git repository.

  4. Save and close the file.

The Trac application will now use the repository found at the specified path.

Note

In the control panel, the Trac application’s Extra info field will continue to show the name of the Git application used when the Trac application was originally installed.

Setting Trac’s Default Time Zone

  1. Open an SSH session to your account.

  2. Open $HOME/webapps/trac_app/conf/trac.ini in a text editor, where trac_app is the name of the Trac application.

  3. In the [trac] section, insert a new line containing default_timezone = GMT offset, where offset is the hours and minutes from Greenwich Mean Time in the form ±XX:YY. For example, the offset for Eastern Daylight Time is -04:00 and the offset for Indian Standard Time is +05:30.

    Note

    An offset is not daylight saving time-aware. If pytz is installed for the Trac application, then you may substitute offset with a daylight saving time-aware Region/City Name-style time zone name from the IANA Time Zone Database. For example, the United States Eastern time zone name is America/New_York and the Indian Standard Time name is Asia/Kolkata.

    To install pytz for the Trac application:

    1. Open an SSH session to your account.
    2. Switch to the Trac application directory. Enter cd $HOME/webapps/trac_app/ and press Enter.
    3. Install pytz. Enter PYTHONPATH=$PWD/lib/python2.6 easy_install-2.6 -d $PWD/lib/python2.6 -s $PWD/bin pytz and press Enter.
  4. Save and close the file.

Dates and times are now shown in the default time zone for logged-out users and logged-in users who have not selected a time zone in their preferences.

Upgrade a Trac Application

To upgrade an existing Trac application to the newest version:

  1. Open an SSH session to your account.
  2. Switch to the Trac application directory. Enter cd ~/webapps/trac/, where trac is the name of the Trac application, and press Enter.
  3. Get the latest version of Trac. Enter PYTHONPATH=$PWD/lib/python2.6 easy_install-2.6 -Z -d $PWD/lib/python2.6 -s $PWD/bin pysqlite trac==version, where version is the Trac version number to which you’re upgrading, and press Enter.
  4. Upgrade the Trac database. Enter ./bin/trac-admin . upgrade and press Enter.
  5. Upgrade the Trac wiki pages. Enter ./bin/trac-admin . wiki upgrade and press Enter.
  6. Upgrade Trac’s image and style resources. Enter ln -f -s $PWD/lib/python2.6/Trac-version-py2.6.egg/trac/htdocs ./ and press Enter.

Now Trac is running the latest version.

Note

The control panel shows the originally installed version number for the Trac application. The actual version number appears in Trac’s footer as Powered by Trac 0.XY.