At work we have a dedicated machine that runs Apache+SSL, Trac (as a Python module) and Subversion. I configured this machine a while back and while doing so I didn’t find a single tutorial or HOWTO on how to do this, so I thought I might as well write one. I will not go into detail on every little bit of the configuration of these services. I will mostly explain the stuff I wasn’t sure about myself when I set up the machine at work. If you find any flaws or errors in the setup described in this tutorial please let me know so I can fix it! I’m a developer but since I like to fiddle with sysadmin stuff from time to time I got the job of setting up this machine at work.
At work we use the CentOS distro, but since I’m a Debian kinda guy I’ll use a clean Debian Etch based machine called debby for this tutorial. If you don’t use Debian the configuration files I mention will probably be placed in other directories.
All commands will be run as the root user, and I will use apt-get when installing most of the software mentioned in this post. The first thing we want to do is to install Subversion.
Installing Subversion
Installing Subversion should not be too much of a hassle. Simply run the following command:
apt-get install subversion
When this is done we need to decide on a directory layout for our repositories. For this I will use a somewhat similar layout as the one we use at work. You don’t have to use this directory layout, but if you choose a different one remember to use that one in the rest of the tutorial. I will make a directory that both the Trac and Subversion stuff will reside in:
mkdir -p /services/svn/repositories
When we have our parent directory we can create a couple of repositories with the svnadmin command:
svnadmin create /services/svn/repositories/proj1 svnadmin create /services/svn/repositories/proj2
We will leave these projects alone for now. When we have Apache set up we can checkout these projects and add files and such. More on that later.
Next on our list is to install the Apache web server.
Installing the Apache web server
This is just as simple as installing Subversion:
apt-get install apache2
When apt-get is finished you should have a working Apache on the server. Check it out by making a request to the machine in some browser. On debby I get the output shown in Figure 1.
Figure 1 - Default Apache index page
Modules for Apache
Now that we have Apache installed we need some modules for it that is not included in the apache2 package. The ones we are interested in are mod_python (for Trac) and dav_svn (for Subversion).
Install these by doing:
apt-get install libapache2-mod-python apt-get install libapache2-svn
Now that we have installed the modules we can configure Apache to access our Subversion repositories.
Configuring Apache for Subversion access
On Debian all configuration files for the apache2 package can be found in /etc/apache2. As mentioned, this differs from distro to distro. If you don’t use Debian you will need to find the same files for your distro somewhere else.
I like to split up the configuration files, so I will create a separate file for the Subversion configuration in /etc/apache2/conf.d/ called subversion.conf. The file will look like this:
<Location /svn>
DAV svn
SVNParentPath /services/svn/repositories
</Location>
This means that whenever someone makes a request to /svn on the web server the svn DAV module will be used and the SVNParentPath environment variable will be set to the parent path of all the repositories, which in my case is /services/svn/repositories. Now, save the file and restart Apache.
Once reloaded you are able to browse and change the content of the repository via HTTP. Before we try it out we need to change the permission of the directory that holds the repositories. Since all changes will go though Apache, the user that Apache runs as will need write access on the directories. On Debian, the default user and group that Apache runs as is www-data.
Change the persmissions by running the following commands:
chown -R www-data.www-data /services/svn/repositories find /services/svn/repositories/ -type d|xargs chmod g+sw
The g+sw argument in the second command will set the sticky bit for the group on all directories so that all files and directories created inside /services/svn/repositories will get www-data as group.
Now, lets try to checkout one of the projects, add a file and then commit. On my workstation I run the following command:
svn co http://debby/svn/proj1
Enter the proj1 directory and create a file, add it to Subversion and commit the change:
touch index.html svn add index.html svn commit -m "Added file" index.html
As output from the last command you should get something like:
Adding index.html Transmitting file data . Committed revision 1.
Success! We are now able to read and write to the Subversion repositories on debby via HTTP.
Now it’s time to get Trac up and running so we can start to manage our projects.
Installing Trac
Since the Trac package in the Debian stable repository is a bit outdated (0.10.3 while writing this) I will install Trac-0.11.1 using easy_install from the python-setuptools package. If you don’t have this package you can install it by doing:
apt-get install python-setuptools
Now, install Trac by running the following command:
easy_install http://svn.edgewall.org/repos/trac/tags/trac-0.11.1/
Trac uses sqlite pr. default as storage so we need the python-sqlite package:
apt-get install python-sqlite
We also need to install a package that includes Subversion bindings for Python. In Debian it is called python-subversion and can be installed with the following command:
apt-get install python-subversion
Now that Trac is installed we can go ahead and create a couple of instances that will use the Subversion repositories we created earlier. The Trac instances will be placed in /services as well:
mkdir -p /services/trac/projects
Now, create two projects:
trac-admin /services/trac/projects/proj1 initenv trac-admin /services/trac/projects/proj2 initenv
When creating the projects you will be asked a couple of questions about the name of the project and so forth. You can call it what you want, but I will call them “Project 1″ and “Project 2″. While configuring you will also need to enter the paths to the repositories we created earlier. If these commands generate errors it’s likely that you are missing some packages that Trac depends on. If you get errors, try to install the missing packages and run the above commands again.
Now it’s time to configure Apache to run Trac as a Python module.
Configuring Apache for Trac
Just as we did when configuring Apache for Subversion, we will create a separate file for the Trac configuration called trac.conf in /etc/apache2/conf.d/. The file looks like this:
<Location /trac>
SetHandler mod_python
PythonInterpreter main_interpreter
PythonHandler trac.web.modpython_frontend
PythonOption PYTHON_EGG_CACHE /tmp/python_egg_cache
PythonOption TracEnvParentDir /services/trac/projects
</Location>
This informs Apache that whenever someone makes a request to /trac it will handle the request with mod_python as well as set some options for Python.
Now, restart Apache and check out Trac’s simple project listing by making a request to /trac. My listing can be seen in Figure 2.
Figure 2
Click on one of the projects and see what happens. You _should_ get a Traceback from Python saying that the www-data user needs to be able to read _and_ write to some files. Let’s fix that. We will need to do about the same as we did when letting www-data write to the Subversion repositories:
chown -R www-data.www-data /services/trac find /services/trac/ -type d|xargs chmod g+sw
Now you should be able to reload the page in your browser and see the Trac installation.
There is one problem though. You can’t really do too much here yet. You can’t add tickets or edit the wiki pages. The only thing of interest you can do at this point is to browse the source of the repository of each Trac. Click the “browse source” link and see the contents of the repository. If you added a file earlier you should be able to see it along with the comment you may have written. As you might see the comment is made by anonymous. This is because we have on authentication yet.
Click on the login link in the menu and you’ll get a Trac error rambling on about missing authentication information. Let us fix that! Since we are about to do authentication over HTTP we want SSL to be enabled first.
Configuring SSL
First we need to generate a self signed certificate that Apache can use. Since it is self signed, browsers will give a warning that forces you to do some extra clicks the first time the certificate is loaded.
We will need openssl to be able to generate the certificate so install it if it’s not already on the server by doing:
apt-get install openssl
After openssl is installed enter the /etc/ssl/private/ directory and run the following command to create a private key for Apache (you may use a different name for the key file):
cd /etc/ssl/private openssl genrsa -des3 -out debby.key 1024
You are asked to enter a passphrase for the key. We will remove this passphrase later on, so just enter whatever you like (just don’t forget it). Now we can make a certificate based on this key. Enter the /etc/ssl/certs/ directory and run the following command:
cd /etc/ssl/certs openssl req -new -x509 -days 365 -key ../private/debby.key -out debby.crt
First you are asked to enter the passphrase you used when creating the key. After that you are prompted for some more information like State, City and so forth. It’s important to write something when you are asked for “Common Name”. If you don’t do this you will have problems checking out the code from the Subversion repositories later on.
When done you will have a file called debby.crt (or whatever name you chose).
Now we need to get rid of the passphrase from the key file or else Apache will ask you for the passphrase every time you restart it. To do that run the following commands:
cd /etc/ssl/private cp debby.key debby.key.org openssl rsa -in debby.key.org -out debby.key chmod 400 debby.key debby.key.org
And thats that! The key no longer has a passphrase and it is only readable by the root user. Now we need to configure Apache so that SSL is enabled and that it uses the certificate we have just created.
On Debian the SSL module for Apache is installed together with the apache2 package, but not enabled. If your distro does not include the SSL module you will need to install it first.Now, let’s enable it and make some changes to the default configuration.
Enter the /etc/apache2/mods-enabled/ directory and make a couple of symlinks:
cd /etc/apache2/mods-enabled/ ln -s ../mods-available/ssl.load ln -s ../mods-available/ssl.conf
The next time Apache restarts it will load the SSL module and use the configuration from the ssl.conf file in the mods-enabled directory.
Now we want Apache to listen to port 443 instead of 80. This can be done by editing the ports.conf file in the /etc/apache2/ directory. Simply put in 443 instead of 80 and save the file.
We need to configure the SSL module to use the certificate we just created. Instead of editing the default configuration file we will create a file called ssl.conf in /etc/apache2/conf.d/ together with trac.conf and subversion.conf and make it look like this:
<VirtualHost _default_>
DocumentRoot "/services/apache/debby/html"
SSLEngine on
SSLCertificateFile /etc/ssl/certs/debby.crt
SSLCertificateKeyFile /etc/ssl/private/debby.key
</VirtualHost>
SSL is now enabled on the default virtual host on our Apache server and will use the certificate and key we just created. As you can see I have set the DocumentRoot of the default virtual host to a directory that does not yet exist. Create it by running the following command:
mkdir -p /services/apache/debby/html
Now we can restart Apache and we should have SSL support. I can now make a request to https://debby/trac and get the project listing. http will no longer work since the server only listens on port 443. The first time you request something from https you will get a warning about the certificate. In Firefox you can just make an exception in the rules and it will no longer nag about the certificate. You get this warning because the certificate is not signed by a Certifying Authority. The certificate will work just fine, except for the annoying warning the first time your browser loads it.
Now that we have SSL we can go ahead and configure authentication for our Trac and the Subversion repositories.
Configuring basic authentication
For this I will simply create a regular htpasswd file with some users and then configure the server to authenticate every request against that file.
To create the file and add a user called christer I run the following command:
htpasswd -cm /services/apache/debby/htpasswd christer
Now that we have a user we need to edit the ssl.conf file to enable authentication on our virtual host. Open up /etc/apache2/conf.d/ssl.conf and make it look like this:
<VirtualHost _default_>
<Location />
AuthType Basic
AuthName "Requires authentication"
AuthUserFile /services/apache/debby/htpasswd
Require valid-user
</Location>
DocumentRoot "/services/apache/debby/html"
SSLEngine on
SSLCertificateFile /etc/ssl/certs/debby.crt
SSLCertificateKeyFile /etc/ssl/private/debby.key
</VirtualHost>
Restart Apache and make a request to /trac. Enter the credentials of the user you just created and click on one of the projects. Trac should now say “logged in as <username>” where the login link used to be. Now we can start to edit the wiki pages and create tickets.
Each Trac should have an admin user that can administer permission and other info. Let us call the admin user for tracadmin. Add the user to the htpasswd file by running the following command:
htpasswd -m /services/apache/debby/htpasswd tracadmin
Now we need to tell Trac that whenever a user with the tracadmin username is logged in the user should have TRAC_ADMIN rights. This can be done using the trac-admin tool that we used to create the Trac instances earlier in the tutorial. First run the following command to start the administration console:
trac-admin /services/trac/projects/proj1
The run the following command:
permission add tracadmin TRAC_ADMIN
and then exit the console with ctrl+c. Whenever you log in to /trac/proj1 with the tracadmin user you will see the Admin link in the menu. From there you can edit basic settings, permissions and other things.
Since we put the authentication on / we will also need to authenticate when working with Subversion. Try to make a checkout of the proj2 repository and see what happens:
svn co https://debby/svn/proj2
You will be asked to accept the certificate and then authenticate as one of the users in the htpasswd file. After you have checked out proj2 try to add a file and then commit. If you browse the source in the Trac for proj2 you will see that the user who have made the change is the user you used for authentication when you made the checkout.
And thats that actually. We now have a machine that runs Apache+SSL, Subversion and Trac and they should all work nicely together.
If you encounter any problems when following this tutorial please leave a comment. Hopefully I’m able to help you fix it. If you have some issues with some other distro I probably won’t be able to help. Anyways, hope this helped you in some way. Have a nice one!
