HowTo: Install Trac and Subversion on Ubuntu Gutsy
Install Ubuntu Gutsy Server Edition
I'm not going to tell you exactly how to do this, but at the proper step, the one where it asks what software packages you'd like, select the OpenSSH server and LAMP server packages.
Once the installation is complete and you've rebooted, remember to get the latest updates.
sudo apt-get update
sudo apt-get upgrade
Install Trac and Subversion
sudo apt-get install trac \
libneon26 libsvn1 python-clearsilver \
python-pysqlite2 python-subversion \
subversion python-setuptools libapache2-svn \
libapache2-mod-python
Setup Subversion Repository
Before we create our Trac environment, we need to setup our Subversion repository. I set mine up in the /var/lib/svn folder. Assuming this is the location you want to create yours, use the following commands to do so now.
sudo mkdir /var/lib/svn
sudo svnadmin create /var/lib/svn
Before we move on, we need to setup authorization and access to the subversion repository through Apache. First, let's create the authentication file.
sudo htpasswd -cm /var/lib/svn/.htpasswd youruser
This command creates the file and adds your user to it. It will prompt you for a password.
We are going to setup Apache to serve the repository. Apache needs write access to the repository folder you just created. Let's do that now:
sudo chown -R www-data:www-data /var/lib/svn
Now, let's move on to Apache. Create a new file called /etc/apache2/sites-available/svn and populate it with the following:
<Location /svn>
DAV svn
SVNPath /var/lib/svn
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /var/lib/svn/.htpasswd
Require valid-user
</Location>
Save the file and enable the site. Enable the site by creating a link in sites-enabled.
sudo ln -s /etc/apache2/sites-available/svn sites-enabled/002-svn
Also, we're not going to use the default Apache site. You can disable it now:
sudo rm sites-enabled/000-default
Restart Apache to get everything running.
sudo /etc/init.d/apache2 restart
You can now navigate to the /svn folder on your web server to browse the Subversion repository, i.e. http://yourserver/svn. The browser will prompt you for credentials which match up to those you entered while walking through the htpasswd command.
Setup Trac Environment
Now we're ready to setup the Trac environment. My location, as with Subversion, will be in /var/lib, i.e. /var/lib/trac. Use the following commands.
sudo trac-admin /var/lib/trac initenv
Be prepared. The init script asks you for some basic information:
- name of your project
- database connection information
- source control repository type
- path to the source control repository (assuming you've selected SVN or other file based system supported by Trac)
- templates directory
Once you've answered the questions, the script sets up the environment in the directory you specified. You're now ready to move on to configuring Apache.
Configure Apache
Apache needs write access to the directory and everything underneath. Issue the next command to take care of that.
sudo chown -R www-data /var/lib/trac
We need to tell Apache some things about Trac. Create a new /etc/apache2/sites-available/trac file and populate it with the following contents:
ServerName yourserver
<VirtualHost *>
DocumentRoot /var/www
<Location />
SetHandler mod_python
PythonInterpreter main_interpreter
PythonHandler trac.web.modpython_frontend
PythonOption TracEnv /var/lib/trac
PythonOption TracUriRoot /
</Location>
<Location /login>
AuthType Basic
AuthName "Trac Server"
AuthUserFile /var/lib/trac/.htpasswd
Require valid-user
</Location>
</VirtualHost>
Now, you need to enable the site. Create a link in the /etc/apache2/sites-enabled folder to your new file and restart Apache.
sudo ln -s /etc/apache2/sites-available/trac sites-enabled/001-trac
sudo /etc/init.d/apache2 restart
At this point enough is setup to do a quick test. Try pulling up the trac site by navigating to http://yourhostname/. You should see the base Trac site with some introductory text. However, we're not done. We need to do some configuration.
Setup admin user
The Ubuntu package includes some basic configuration, which allows you to check the setup at the end of the last section. We are going to install a WebAdmin plugin that allows you to change the configuration through the web interface. Before we do, we need to setup the admin user for the Trac environment just created.
Switch to the trac environment direction, e.g. /var/lib/trac. Issue the htpasswd command to create the trac.htpasswd file we configured Apache to look at.
sudo htpasswd -c .htpasswd youruser
The command asks you for the password for the user. Enter it to move on.
Once that's done, let's set the permissions on the file. This probably isn't absolutely necessary, but we'll do it to keeps things in the trac environment folder clean and consistent.
sudo chown www-data .htpasswd
The last thing we need to do is put the user in the TRAC_ADMIN group for the environment. The trac-admin command provides the way to accomplish this.
sudo trac-admin . permission add youruser TRAC_ADMIN
You should now be able to login to your Trac environment using the credentials you setup. You will see new options for creating and removing pages in the environment.
Install WebAdmin plugin
Ubuntu Gutsy contains the 0.10.4 version of Trac. This version does not contain the WebAdmin plugin, which is quite useful for administering your Trac environment. We need to install it manually, so let's do that now.You have to download the plugin in order to install it. Switch to a directory you'd like to work out of and issue the following command:
svn export http://svn.edgewall.com/repos/trac/sandbox/webadmin/
This command retrieves the plugin and puts it in a sub-directory named webadmin in the directory you issue the command from. Now we can install it:
cd webadmin
sudo ./setup.py install
Once that completes, switch back to your Trac environment directory (/var/lib/trac), edit the conf/trac.ini file and add the following lines to the end:
[components]
webadmin.* = enabled
Now you need to restart Apache to make sure cached files get reset and such.
sudo /etc/init.d/apache2 restart
Install AccountManager plugin
The AccountManager plugin works in conjunction with the WebAdmin plugin to allow you to manage user accounts for the Trac environment. Install it using the following command:
sudo easy_install http://trac-hacks.org/svn/accountmanagerplugin/0.10
You need to create the python egg cache directory. The folder to create is /var/www/.python-eggs. The Apache user needs read/write access to this directory and you can accomplish that by making the owner of the new directory www-data. Here are the commands:
sudo mkdir /var/www/.python-eggs
sudo chown www-data /var/www/.python-eggs
Once the plugin is installed, you need to enable it in your Trac environment. There are two ways to do this: manually editing the trac.ini file, or using the WebAdmin plugin.
Users with the TRAC_ADMIN permission can enable the plugin using the WebAdmin. Once logged in, navigate to the admin page and select plugins. Expand the TracAccountManager section and check the components you want to turn on. I selected all, but this isn't exactly right. Some of these features don't work together. When I get around to looking at this again, I'll update the how to. If you want to get fancy with it right away, look at the documentation on the AccountManagerPlugin wiki page..
Once you turn on the plugin, we need to tell it where to find the htpasswd file we started using. You should now see an Accounts section in the left menu. The first entry under Accounts is Configuration. Select it and enter the path to the htpasswd file, i.e. /var/lib/trac/.htpasswd if you've been following these instructions exactly. If not, put in the actual path you used.
Restart Apache to clear cache and such:
sudo /etc/init.d/apache2 restart
Setup SMTP for change Notification
Email notifications of ticket creation and changes is a useful feature. WebAdmin does not support administration of the SMTP settings, so we will have to return to the trac.ini file. This file contains a section [notification]. The package version of this file has SMTP turned off by default. To enable it, you need to provide a few pieces of information.
The [notification] section of the package trac.ini file looks like this:
[notification]
smtp_server = localhost
always_notify_updater = true
smtp_port = 25
smtp_password =
smtp_enabled = false
smtp_replyto = trac@localhost
smtp_always_cc =
always_notify_owner = false
smtp_from = trac@localhost
always_notify_reporter = false
use_tls = false
smtp_always_bcc =
mime_encoding = base64
smtp_subject_prefix = __default__
use_public_cc = false
smtp_user =
use_short_addr = false
smtp_default_domain =
You need to make changes to the appropriate sections. For example, my internal email SMTP server uses standard ports. I changed the following settings:
- smtp_enabled = true
- smtp_default_domain = my base domain name, e.g. foo.com
- smtp_from = my email address
- smtp_password = my passwd
- smtp_replyto = my email address
- smtp_server = name of my smtp server
- smtp_user = my username
Once you make these changes, restart Apache to ensure Trac looks at the new configuration.
sudo /etc/init.d/apache2 restart
Trac Ready
At this point, Trac should be ready to go. One of the things I like about Trac, though, is that it has a flexible plugin API written in Python! There are a number of plugins, scripts and macros I plan to use. I'll add HowTos as I put them together. Some of the ones I plan to use:
- WantedPages - to show broken links
- TracWysiwygPlugin - to make it easier for non-tech folks to edit the pages
- email2Trac - to update tickets via email
- WikiNotificationPlugin - to allow users to subscribe to notifications of updates to wiki pages
- ...