When we start to get a reasonable size team together working on a large web project we can run into problems like; one team member has the latest copy of the production code on their computer and they’ve gone on leave for a week or they, with the best of intentions, clean up the test server and accidentally remove someone else’s latest updates. Its at this point we need to consider using revision control software. In very simple terms revision control software provides a central repository for all the files in a project and keeps track of all the changes made to the files (see http://en.wikipedia.org/wiki/Revision_control for more detail). This kind of software has more traditionally been used by software developers but as web development teams and web projects have become bigger and more complicated revision control systems have become invaluable for web developers.
Getting revision control software installed and running for a small team can be an onerous task but finding information on how to do it can be more so, so I’ve put together the following end-to-end guide of how we have set up our own revision control server. We chose subversion as our revision control server software as we are a mostly Mac team with a few token WinTel users for system balance. We’re all mad Dreamweaver users (Dreamweaver has subversion client tools in CS4) as does one of our favorite text editors (TextMate) and the box we have to run the system from is an OS X Leopard server. One other reason for choosing subversion is that it came at the right price – free.
So here is the process we went through (minus the back-tracks and stuff-ups) to set-up subversion on OS X Leopard server for revision control of a Website project.
1. Instal subversion
There are a number of methods you can use to install subversion. You can take the geeky route and use MacPorts or Fink but by far the simplest most painless way to do it is to download the binary install from openCollabNet.
Universal Subversion 1.6.2 Binaries for MAC OS X (32 and 64 bit) from openCollabNet (Universal)
N.B. Whilst leopard reportedly comes with subversion (Ver 1.4.4 – ?) I think if you are serious about using it you’ll want to get the latest stable release.
2. Test subversion installation
The simple way to test whether or not your install was successful is to open the terminal and type…
$ svn
The response should be…
Type 'svn help' for usage.
3. Create *a* Subversion repository and give the web server user access
The first thing we need to do once we’ve installed subversion is to create a repository where subversion can keep control of your files for us. We’re going to give users access to the repository via a web service so the httpd user, usually www, will need to be able to access the repository.
Create the repository
$ sudo svnadmin create /usr/local/svn_repository
Give the httpd user (www) access / ownership
$ sudo chown -R www /usr/local/svn_repository
Notes
- As in the example above you may need to use superuser i.e. sudo
- Give the repository a meaningful name. Whilst names like ‘repo’ often appear in documents like this ‘svn_repository’ is much more meaningful.
4. Create the basic structure and commit the changes to the repository
Recommended practice prescribes the use of a folder structure that at the minimum, for a single project repository, includes the folders tags, branches and trunk. This style of repository layout may not be suitable/necessary for all projects but it’s good practice to start this way.
Were going to be creating some folders then committing them to the repository to create its initial structure so its best to cd to temp space to do this.
$ cd /tmp
Checkout the repository: Checking out the repository creates a working copy and forges a link between the working copy and the repository. FYI ‘co’ is short-hand for checkout.
$ svn co file:///usr/local/svn_repository
Checked out revision 0.
cd into the working copy
$ cd svn_repository
Create the basic structure in working copy
$ svn mkdir tags branches trunk
A tags
AÂ Â Â Â branches
AÂ Â Â Â trunk
Commit the content of the working copy to the repository: FYI ci is shorthand for check in.
$ sudo svn ci -m "initial structure"
Password:
Adding   branches
Adding   tags
Adding   trunk
Committed revision 1.
Having created an initial repository we have made it easier to create and test a HTTP connection to the repository.
5. Configure HTTP access via the built-in Apache 2.0 web server
5.1. Activate the required Apache modules
Open server admin and select the web service on the server you want to configure.
Select Settings then Modules and check the box next to the following modules…
- dav_module
- dav_fs_module
- dav_svn_module
- authz_svn_module
Click the save button
5.2. Enable WebDAV on your site*
Switch to Sites and select the site you want to host the service (if you have more than one).
Select Options and check the box next to WebDAV.
Click the save button.
- This may not be necessary?
5.3. Create a Realm
Access to the subversion repository will be controlled by the Apache web service not through subversion itself. This make life a lot simpler and if you have a third party access control mechanism such as an LDAP server it makes it very easy to configure this.
Whilst you are in Sites with the host service selected switch to Realms.
Click the plus button under the Realms list and enter the following into the enter information for the realm dialogue…
- Realm Name: svn_realm
- Authentication: Basic
- (Change the dropdown from Folder to) Location: /svn
Click the OK button.
Click the plus button under the User & Groups list then drag and drop users to the list and modify there permissions accordingly. Most svn users will need ‘Browse and Read/Write WebDAV.’
Click the save button.
5.4. Edit the Apache site config file
Locate the site config file related to the site hosting the svn repository. The usual location is ‘/etc/apache2/sites’ and the file name should start with ’000x’ followed by the site name and then the extension .conf.
Find the section of the config file that begins with the line ‘<Location “/svn”>’ and add the following lines at the end of that section…
DAV svn
SVNPath /usr/local/svn_repository
Save and close the config file and then restart the Web server by stopping and starting it again in Server Admin or using apachectl restart in the termainal.
N.B. If you add users to the realm after making these configuration changes the server will rewrite the line ‘DAV svn’ to ‘DAV off’. A fix for this is to put the two lines above in a file called ‘svn.conf’ in the ‘/etc/apache2′ folder and replace them in the site config file with an include statement.
6. Create a working copy on the server and give httpd (www) access to it
We can’t use the repository directly as a web site because it is in reality a database and as a pile of files makes no sense. The solution to this is to have subversion output the files to a directory which the web sever can use a site root. The best way I’ve found so far to do this is to create a working copy of the repository and have subversion update it when content is committed. The fist step in this process is to create a working copy of the repository and then give httpd access to it.
Create a folder for your web site. We’ll use ‘htdocs’ in this example.
In the terminal cd into the htdocs folder…
$ cd /htdocs
Checkout the repository into the htdocs folder…
$ svn co file:///usr/local/svn_repository/trunk .
Checked out revision 0.
Notes
- We checked-out the trunk and not the root of the repository. Trunk usually contains the most up-to-date content of the project.
- The period on the end of the checkout command, for those of you who don’t know, simply means ‘here’ in terms of the servers file path. In this case it means ‘/htdocs’.
cd out of the htdocs folder and change the ownership of the files to give access to the httpd user (www). If you remember earlier we set the server up to give users of subversion access via http so when users interact with service httpd will be doing the work for them.
$ cd /
$ sudo chown -R www /htdocs
Next we need to configure our subversion repository to update the htdocs folder when users commit content to the repository.
7. Edit the post-commit file to update the working copy when users commit content to the store
Locate the ‘post-commit.tmpl’ which usually lives in the ‘hooks’ folder in your repository in this example set-up you will find at ‘/usr/local/svn_repository/hooks/post-commit.tmpl’. Open it with your favorite text editor (one that can handle editing files as superuser e.g. BBedit or TextMate) and save the file as ‘post-commit’ (no extension) in the same folder. This file is a shell script that subversion will run after content is submitted to the repository.
Add the following lines to the script after the line ‘REV=”$2″‘…
/usr/bin/svn up --non-interactive /htdocs
N.B. The full path to svn may not be necessary but its a good safeguard.
Save the post-commit file and make it excitable.
e.g. from the terminal…
$ chmod a+x post-commit
Now when ever a user commits a file to the repository the working copy in htdocs will be updated. All that remains to be done now is for the web service to be pointed at this folder as its Web Folder.
2 Comments
Peter this post saved me a ton of trouble. I’ve spent the last few days dealing with permission issues on post-commit in Snow Leopard and your tutorial just worked. Thank you so much for posting this.
Glad I could help.