In Part 1 I walked through the installation of the Apache Web server. With that step complete it's time to install the Subversion server and integrate Subversion and Apache. Once we've completed these steps we'll have our source control server environment in place and we'll be ready to install some Subversion client tools.
Several resources on the Internet offer instructions on downloading and installing a Subversion server. Many of the resources focus on ease of installation and recommend the Subversion 1-click installation. This installer does make things easy by installing the Subversion command-line utilities (svnserve), and TortoiseSVN. It also creates an initial repository and project. We will not be using the 1-click installer and there are several reasons why. First, the 1-click installer sets up svnserve, the standalone Subversion server, and I'm focusing specifically on integrating Subversion with Apache. With Apache integration your Subversion server and it's repositories are available as long as Apache is running. In other words, the standalone server (svnserve) is not used. If you were to not integrate Subversion with Apache you would have to start and stop the svnserve service explicitly. For more advantages regarding Subversion and Apache over svnserve, check out the Advantages of Using the Apache Web Server section in Part 1.
To download the Subversion server point your Web browser here. This Web page lists several Windows versions of Subversion most notably, the Win32 binaries. At the time of this writing both 1.3.2 and 1.4.2 were available for download. For the purposes of this text, you should download svn-1.4.2-setup.exe. UPDATE: Just before releasing this paper, version 1.4.3 of Subversion was publicly released. While this text remains centered around 1.4.2, you should have no problems installing and using 1.4.3.
Just like the Apache installation, Subversion should be installed on your development server. To begin installing Subversion double-click the executable you downloaded earlier.
Figure 13: Begin Subversion Installation
Subversion prompts you to confirm you want to install the software.
Figure 14: Subversion Installation Welcome Screen
The Subversion installation lets you know which version (and build) you are installing. Press Next to view the software terms and license. Accept the terms and press Next.
Figure 15: Subversion Destination Location
The default destination directory is fine and is what I reference throughout this text.
Figure 16: Additional Subversion Installation Tasks
Select which additional installation tasks you want the installer to perform. Make sure you select the last option, which directs the installer to add a few "hooks" to your Apache Web server by editing your httpd.conf configuration file.
Figure 17: Subversion Installation Completion
After Subversion has been installed you'll see a completion screen. Press Finish to exit the installation.
Verify the Subversion Installation
Figure 18: Verifying the Subversion Installation
Before we move further we need to verify Subversion was installed correctly by making sure the "hooks" were added to Apache. One way to do this is to request an invalid Web page (index.html is not in the Apache Web root - see Figure 6) from Apache since requesting a page that doesn't exist will cause Apache to display the default "Not Found" page. This page has, at the bottom, information pertaining to the version of Apache running on our development server as well as the version of Subversion we just installed. In Figure 18, the key text is SVN/1.4.2 DAV/2 Server.
Configure Apache and Subversion Modules
Figure 19: First Change to httpd.conf
There are three changes the Subversion installation made to Apache's httpd.conf configuration file - all of which deal with Apache's module API. Apache modules are external Shared Objects (.so file extension) that can be included or "loaded" into Apache when the Web server starts. The LoadModule directive is pretty simple, mapping a module name to it's equivalent .so file on the server. By default, certain modules are loaded while others are not. Modules that are not loaded are commented out in the httpd.conf file with a pound (#) sign. To include a module, and it's functionality, stop the Apache server, find the LoadModule directive for the module you want to include, and remove the pound sign. Figure 19 illustrates Subversion's first change, uncommenting the DAV module (mod_dav.so located in Apache's modules directory). I've added a blank line before and after the DAV module to make the line stand out in the screen shot. While a full discussion of the mod_dav.so library is outside the scope of this text a basic explanation is in order. The mod_dav.so module provides *WebDAV (Web-based Distributed Authoring and Versioning) functionality for Apache. WebDAV extends the stateless HTTP protocol giving Apache the ability to create, move, copy, and delete files and directories on the Web server. You can think of mod_dav.so as the central hub to all Subversion actions operating on the repositories you create.
*For more on WebDAV see http://www.webdav.org/mod_dav/.
Figure 20: Second Change to httpd.conf
The second and third changes the Subversion installation made are the addition of two new LoadModule directives. These are placed at the end of all other LoadModule directives and are visible in Figure 20. The first module, mod_dav_svn.so is used to make repositories available to others over a network and works hand-in-hand with mod_dav.so. The second module, mod_authz_svn.so is used to enable per-directory access control over your repositories. In order to get our httpd.conf file cleaned up there are a few changes we need to make. First, you'll notice the mod_dav_svn and mod_authz_svn modules are located in Subversion's bin directory. There's nothing inherently wrong with this but since all the rest of the Apache modules are located in Apache's modules directory, I recommend moving these files to C:\Program Files\Apache Group\Apache2\modules\. To do this, stop Apache using the Apache Monitor. Move the mod_dav_svn.so file to Apache's modules directory. You don't need to move the mod_authz_svn.so file as I won't be convering per-directory access controls. Now, make a few changes to the httpd.conf file. First, delete the LoadModule directive for mod_authz_svn and then move the mod_dav_svn directive from its current location to the line immediately following the mod_dav LoadModule directive. It's imperative the mod_dav_svn directive be located after the mod_dav directive as it depends on it being loaded first. Finally, edit the directory path for mod_dav_svn changing it to modules/mod_dav_svn.so. When you're done, your LoadModule directives should look just like those in Figure 21.
Figure 21: Final LoadModule Directives
With the two LoadModule directives configured (Figure 21) we have Apache and Subversion talking to each other. However, we aren't ready to start Apache yet as we haven't told it where our Subversion repositories are located nor have we created a directory to hold our repositories!
Creating the Repositories Directory
Figure 22: Create the repository directory
Subversion repositories must be stored somewhere on the server and it's common practice to place them in a svnrepos folder. This is usually created at the root of the C: drive but in my implementation it's the root of the E: drive. It doesn't really matter where you create this folder as long as you remember the location and make the appropriate httpd.conf changes as we progress. Subversion clients (we haven't gotten to this part yet) will interact with Apache which will in turn interact with the folder and files that (eventually) live in the svnrepos directory. One final thing to mention about this folder; it is for Subversion *only*. You shouldn't ever modify, move, delete or directly alter its contents. The only process that should do so is the Subversion server.
Exposing the Repositories Directory to Apache
Figure 23: Exposing the repository directory to Apache
In order for Apache to know where our repository directory is located we must give it some instructions. This can be accomplished several different ways but we'll start with the Location directive. This directive gives Apache specific instructions when requests are received for a named resource (a URL path). For Subversion access, we simply want Apache to hand off requests for URLs that point at versioned resources to the DAV layer. This is accomplished by mapping a URL path to the absolute directory path of the repository. In Figure 23 above, the URL path is /svn and the absolute directory path of the repository is the directory we created earlier (E:/svnrepos) with the slash reversed*. This path translates to http://svn.yourcompany.com:81/svn for our purposes. The DAV svn directive tells Apache's mod_dav to use the Subversion server when any requests come in using the aforementioned URL. The SVNParentPath represents the absolute location of our repository directory. This directive is special in that it informs Apache any child directories in the nominated path contain Subversion repositories. Another option is to use the SVNPath directive which tells Apache where the Subversion repository is located without giving it information on child directories. Either SVNPath or SVNParentPath must be present but not both. The last directive, SVNListParentPath on is convenient when multiple repositories will be stored in E:\svnrepos and browsed via a Web browser. Anytime a user visits http://svn.yourcompany.com:81/svn in a Web browser they will see a list of all the repositories on the server. Because of the obvious security risk imposed by exposing all the names of the repositories (and there locations) this setting is turned off by default.
Testing the Initial Subversion - Apache Hook
Figure 24: Testing your work
Apache should still be stopped so start it using the Apache Monitor. Point your Web browser to http://svn.yourcompany.com:81/svn and you should see something similar to Figure 24 above. If you do, congratulations, you've just integrated Subversion and Apache! When the Web request reaches Apache with the /svn directory on the end of the URL, it knows - via the Location directive we added - to pass control to the Subversion/DAV server. This allows Apache to show all of the repositories in the E:\svnrepos directory. Since the directory is empty right now, nothing shows up. At this point we could leave things the way they are and move on to creating our first repository. But I'm not too happy with the URL used to access the repository. Since the Apache Web server is already configured with a sub-domain (svn.yourcompany.com) there's really no need to tack on the /svn directory. We can easily nix this portion of the URL by using Apache Virtual Hosts. Virtual Hosts allow Apache to serve content from multiple domains. You could have yourcompany.com serve your normal Web site and svn.yourcompany.com serve your repositories. This provides a nice level of flexibility for your Web environment. With that in mind, let's reconfigure our repository access using Virtual Hosts instead of the Location directive.
Enabling Apache Virtual Hosts
Figure 25: Enabling Apache Virtual Hosts
Before you are able to utilize Virtual Hosts you must enable them in the httpd.conf file. Using the Apache Monitor stop Apache and find the #NameVirtualHost line in httpd.conf. To enable Virtual Hosts, remove the pound sign at the start of the line. Since my Apache Web server is listening on port 81, I also had to make sure my Virtual Hosts were configured for port 81 (*:81 instead of *:80). We're now ready to create our Virtual Host.
Configuring a Virtual Host for Subversion
Figure 26: Creating the SVN Virtual Host
A Virtual Host is defined by a starting and ending VirtualHost tag. Within the body of the VirtualHost tag are directives that determine how the Virtual Host behaves. You probably noticed the Location directive which, other than one small change, is exactly the same as our previous version (Figure 23). The difference here is the / URL mapping in place of the previous /svn. What I'm doing here is pointing the entire domain to the Subversion repository instead of one directory (/svn). If your setup does not involve an svn.yourcompany.com sub-domain you may want to keep the /svn mapping. Other than the Location directive, the first important setting is *:81 in the starting tag which says all traffic served by Apache should be directed through this Virtual Host. This means any and all domains that point to this server (and have port 81 in the URL) will obey the rules set forth in this Virtual Host container. The ServerName and ServerAdmin settings should be self-explanatory. The ErrorLog and CustomLog directives instruct Apache to store any Web logs for this Virtual Host in a custom location that we've nominated. This will allow us to separate any other Web server logs (like normal site logs) from our Subversion logs. Before this separation can occur we must create the appropriate log directory.
Creating the Custom Logs Directory
Figure 27: Create the svn log directory
Create the svn directory in the C:\Program Files\Apache Group\Apache2\logs directory.
Testing the Final Subversion - Apache Hook
Figure 28: Testing the Virtual Host Configuration
With the Virtual Host now in place it's time to test our work. Start Apache and access the repository URL (svn.yourcompany.com or yourcompany.com/svn depending on your configuration). What you see should be exactly the same as what is displayed in Figure 24. This time, we are accessing the repository through a Virtual Host instead of a vanilla Location directive. Our changes also mean we now have two log files stored in C:\Program Files\Apache Group\Apache2\logs\svn. The svn-error.log file holds any errors generated by users accessing the repository (either through a Web browser or a Subverion client) while the svn-access.log file shows all the successful actions taken on the repository. These include checking out repository files, committing files, and more. If you open the svn-access log file you will see some entries from your recent Web access. The information displayed is not very readable or useful yet.
Let's review our work in this part. We began by downloading and installing Subversion. Next, we verified the Subversion installation in a Web browser and configured several Apache/Subversion shared objects. We then created our repository directory, exposed the directory to Apache via the Location directive and tested our work in a Web browser. In order to make the environment more flexible we enabled Virtual Hosts, configured a Virtual Host for our Subversion sub-domain - which allowed us to create a dedicated Subversion logs directory - and finally we tested our work again in a Web browser.
At this point we are able to serve up repositories anonymously and we're logging all repository access. What we don't have are any actual Subversion repositories. To learn how to set this up read Part 3: Installing TortoiseSVN and Creating Your First Repository. For information on refining the Subversion - Apache hook adding more meaningful logging and authenticated repository access, read Part 4: Subversion and Apache - Better Logging and Authenticated Access. Finally, to learn how to integrate Subversion access into Eclipse review Part 5: Accessing Subversion Repositories With Subclipse.
5 related blog entries
- Part 5: Accessing Subversion Repositories With Subclipse (March 15, 2007)
- Part 4: Subversion and Apache - Better Logging and Authenticated Access (March 14, 2007)
- Part 3: Installing TortoiseSVN 1.4.3 and Creating Your First Repository (March 14, 2007)
- Part 1: Installing and Configuring Apache 2.0.59 (March 12, 2007)
- Configuring a Development Environment with Apache, Subversion, TortoiseSVN, and Subclipse (March 12, 2007)