Update 1 March 2010: I had to fight with a Trac/Subversion setup to get it running properly. The server in question kept reporting a 403 Forbidden error when a checkout was done from the Repository, but it would allow me to navigate/list the repository contents just fine. The problem turned out to be how Apache handles virtual directories (via the Location directive). Unless otherwise specified, Apache will try to check physical file permissions when requests are made. It does this by tacking the virtual directory onto the end of the DocumentRoot value. Which leads to things like "/var/www/mydomain/public_html/svn" being looked for, when in fact the "svn" directory doesn't exist. Hence you get the 403 error. The Apache logs report this as "client denied by server configuration" or something similar. The fix is dead simple - Add an "Allow from all" directive to your Location block. To be thorough you should also add the "AllowOverride" and "Order deny,allow" lines to be thorough. The sample configuration below has been modified to reflect this.
Trac is a decent tool for tracking information about a project. Some believe it is ONLY good for software projects, but this is just one area it is a good fit for. This issue crops up because it is "understood" that revision control is only good for software projects, and THAT understanding is flawed. Revision control works for ANYTHING that can go through various versions. Configuration files, personal documents, web sites, audio files, etc. As such, Trac works well for almost anything that can be versioned and needs a system to track extra information, known issues, outstanding tasks, etc. Project managment in general.
BUT, one of the stumbling blocks of Trac is their approach to only focus on ONE project. You can pretend a Trac "environment" manages more than one project by using some of the configurable elements in creative ways. Components are often used to emulate sub projects. This doesn't always work well, and those sub projects need their own Wiki, their own tickets, timeline, etc.
Enter the idea of "Multiple Projects". This is a special configuration allowing one installation of Trac to run many Trac "environements" (aka projects). But getting a Multi-Project site running "just right" can be challenging. The documentation is spread across many different pages, and/or sites. The installation requires an understanding of Subversion, Apache, Trac, and some Python, as well as how to configure each of these in their various flavors.
I've been working with Trac for some time, but have been limping along on a "good enough" installations where I didn't mind if I needed to jump through some extra hoops. Afterall, it was only ME using these installations. But that has changed. My customers are beginning to ask for Trac in all it's Multi-Project glory, so I had to knuckle down and work out the "right" way to set up the environments. And here's how to do it.
There's more than one way to do things, but I'll focus on the Apache2 with mod_python approach. In addition, we'll cover how to set up the AccountManager plugin. But, I'm assuming you know how to install the elements so this is not a COMPLETE guide in that sense. Still, it's the configuration side of things where life is um... interesting.
Regarding installations, most software package managers I've seen do not have the more recent versions of Trac. For this reason, I recommend the "egg" method of installing Trac, and not using the package managers.
Here's the routine I've come to:
- First, go take a look at http://trac.edgewall.org/wiki/TracModPython. Everything you need to know (beyond getting Apache and Subversion installed) are here. Though the details can sometimes be cryptic, and it won't all make sense until you've gone through the routines a few times.
- Build your directory structure. I built mine like so:
Root Directory - home - svn - projects
Where the "projects" directory contains Trac environments, and the "svn" directory contains sub directories that are individual repositories for the projects. The names are arbitrary, as is the structure really. But do NOT try to put the Subversion repository INSIDE the Trac directories - this just leads to troubles. (of course, if you know what you are doing, do what you'd like... :) )
- Next, create the Subversion repository:
svnadmin create /home/svn/project1
Repeat this as needed for each of your projects.
- Set up the Trac environment for the project:
trac-admin /home/projects/project1 initenv
Answer the questions as they come up. For the repository, make sure you indicate the same path you used in the "svnadmin create" commands.
- Now set up your access control. I prefer to have a separate access list for each project, but want the same credentials used for both the Trac pages AND the Subversion repository of a single project. I do this by setting up an HtPasswd file for each project, inside the repository folders.
htpasswd -c /home/svn/project1/.htpasswd myuser
Change the "myuser" part to whatever username you'd like. Careful here do NOT use the "-c" option if the file already exists (i.e. after you create the first user), or you will overwrite the file. For user number 2 or later, use
htpasswd /home/svn/project1/.htpasswd
One other note here. You can name the credentials file whatever you'd like. ".htpasswd" works for me.
- Make sure your user has full access to the project:
trac-admin /home/projects/project1 permission add myuser TRAC_ADMIN
- change the project path and the "myuser" user account as needed.
- NOW we can set up Apache to access both of the repository AND the Trac environment. I use a Virtual Host for this, but the core config files can be set up in a regular httpd.conf. Here's the contents of my vhost configuration:
ServerName trac.myserver.com
Options FollowSymLinks AllowOverride None Options Indexes FollowSymLinks AllowOverride AuthConfig Order allow,deny allow from all # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn ErrorLog /var/log/apache2/trac-error.log CustomLog /var/log/apache2/trac.log combined # IF we don't want to see the project listing, we could use LocationMatch # - see http: //trac.edgewall.org/wiki/TracModPython#Settingupmultipleprojects SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /home/projects/ PythonOption TracUriRoot / #Apached Based htpasswd authentication # - Uncomment this section, and change the Location directory, # as well as the AuthUserFile path (and optionally the # AuthName value) # #NOTE: # A Trac environment may need a user to login first, before # the AccountManager (aka web based login) functions # properly. In this case, temporarily uncomment this section, # set the values accordingly, save, restart Apache, navigate # to the Trac project/environment, Login. # Then enable the AccountManager configurations, comment out # this section, save the file, and then restart apache. # # AuthType Basic # AuthName "testing" # AuthUserFile /home/svn/project1/.htpasswd # Require valid-user # # SVN Configurations # - Copy this Location section for each SVN repository needed # - Change the AuthName, AuthUserFile, AuthzSVNAccessFile, and # SVNPath values to match each repository # project1AllowOverride all # adjust this to match your specific needs Order deny, allow Allow from all DAV svn AuthType Basic AuthName "My Project" AuthUserFile /home/svn/project1/.htpasswd AuthzSVNAccessFile /home/svn/project1/conf/authz SVNPath /home/svn/project1 Require valid-user And a quick explanation:
- First, a warning. The syntax highlighter has mangled the case of the Directory, Location, and LocationMatch directives. It also messes up with URLs, so watch for the spaces on the referenced links. Line 57 is mangled good, and should read "<Location /svn/project1>" (without the quotes)
- Up to line 20 are typical virtual host configurations. The only real thing to note here is that we are allowing AuthConfig to be overridden in the directory where our Trac environments are stored.
- Lines 22 to 28 set up our base Location. With this configuration, you can navigate to trac.myserver.com and see a list of the sub directories that appear to be Trac environments (under the /home/projects directory). See below if you don't want the project listing.
- Lines 43-48 define how we might use Apache to do the authentication for us. This is fine for basic sites, but gets to be cumbersome when managing users. We'll set up the AccountManager to make this unnecessary. BUT, I have seen reports that indicate AccountManager will not work until AFTER someone has logged into the Trac site at least once. In this case, you can uncomment this block for the Project in question and get things set up, then comment out the block again.
- Lines 57-68 set up access to your Subversion repository through Apache. Change all instances of "project1" to point to your project.
Restart Apache when you are done with this file, and then fix any errors that may crop up.
Now, when you want to add another project, you only need to copy/paste the final section for Subversion, and then tweak the pasted text to match the new project.
Getting Rid of the Project Listing
There are times where you want a Multi-Project set up, but you don't want to make it known what projects are actually on the server. In this case the project listing feature needs to go. We do that by replacing the Location directives (lines 22 and 28 in the above virtual host sample) with LocationMatch directives:
SetHandler mod_python
PythonInterpreter main_interpreter
PythonHandler trac.web.modpython_frontend
PythonOption TracEnvParentDir /home/projects/
PythonOption TracUriRoot /
Again, the syntax highlighter has mangle the Directives. The first line should read
<LocationMatch "/.+">
and the last line should be </LocationMatch>.
Notice that everything between the LocationMatch directives hasn't changed.
By using LocationMatch like this, the project listing is not seen, and we can even now specify a DocumentRoot for the the virtual host if we wanted, and set up our own custom page. I prefer to just leave a standard error message though.
Setting Up AccountManager
Final step to make life easy.
Visit http://trac-hacks.org/wiki/AccountManagerPlugin and follow the instructions for getting AccountManagerPlugin installed. Read up on the configurations so you understand the differences between the options. But we'll take a shortcut here
The EASIEST way to get AccountManger going that I've found is to copy an existing working configuration. Edit the Trac configuration file - /home/projects/project1/conf/trac.conf. Make sure the following appears there:
[account-manager] force_passwd_change = true generated_password_length = 8 password_file = /home/svn/project1/.htpasswd password_store = HtPasswdStore [components] trac.web.auth.LoginModule = disabled acct_mgr.admin.accountmanageradminpage = enabled acct_mgr.api.accountmanager = enabled acct_mgr.htfile.abstractpasswordfilestore = enabled acct_mgr.htfile.htpasswdstore = enabled acct_mgr.pwhash.htpasswdhashmethod = disabled acct_mgr.web_ui.accountmodule = enabled acct_mgr.web_ui.loginmodule = enabled
Change the path as needed for the password file.
If you had Apache doing authentication for you, comment this out and restart Apache. You may need to close your browser and re-open it (due to how http authentications are handled by some browsers).
Now, navigate to your Trac project, and click the Login link in the upper right area. You should see a web form for your username and password. Enter these. When you login, you should now be able to see the restricted portions of your project (depending on your permissions of course).
Trouble areas:
You may get a "Authentication information not available." error, usually when you try to access something that needs more permission than the default anonymous access. You may also see a "No administration panels available" message when trying to access the admin pages. It SEEMS these both stem from the same problem - email notifications. If you have the registration module and have set up email notifications, you may see these errors if the email has not been responded to. My personal "fix" for this is to turn off notifications for account changes. This only affects the AccountManager. Your regular trouble ticket notifications (if you've set them up) are not involved.
All Done!
If all went well, you now have a Multi-Project Trac server that can be managed without going to the command line.
Happy project managment!