Advantage Labs is a firm believer in maintaining "version control" of its managed sites. A software called Subversion allows us to set up a system for "checking out" sites from the server to make changes (experimenting with new modules for example) on a local computer without affecting the live site. Then, if and when the changes are deemed ready for the live site, the changes can be "checked in" back to the server with a log containing notes about the changes. Other site maintainers using the Subversion system will have access to seeing all the versions of the site and the history of changes. Reverting back to an earlier version, sans changes, is also possible. This system makes keeping track and control of the web development process a much easier and more flexible process.
As a managed site client, you are given access to the Subversion "respository" of your site. Another Knowledge Base Entry outlines how the Advantage Labs repository structure is set up. This entry will show you how to set up your local Mac OS X computer to take advantage of Subversion. If you are looking for instructions for setting up a Windows computer, refer to this Knowledge Base Entry.
Setting up your local computer to for serving your Drupal website
Before you can download your site from the server, you will need to configure your computer to operate as a webserver. The Macintosh OSX operating system has webserver software technology-- Apache -- built in and ready to be turned on. However, a more contained environment is easier to control. Open source software to set up a contained webservinge enviroment-- Apache, MySQL, and PHP-- exists. It is called MAMP (the first M is for Mac). MAMP is available for free download from http://www.mamp.info. Information about downloading and setting up MAMP is also available from the site. Additionally, the Drupal consulting firm Lullabot has produced an excellent 8-minute video screencast on the setup of MAMP for OSX. We highly recommend watching this as the best way to get you through this step of the process. With MAMP installed and configured you are ready to move forward.
Installing Subversion
In order to use Subversion, there are software elements that need to be installed on your computer first. Subversion, like other software, has different versions. At this time (July 2007), Subversion's latest version is 1.4.4. There are many sources and methods for installing the necessary Subversion software "binaries" on your computer. Collab.net offers a comprehensive installer that can be downloaded at http://downloads.open.collab.net/binaries.html. The download page has a good readme article explaining the binaries and where files will be installed on your computer. After reading the readme, dowload the installer package and install on your computer. With these Subversion binaries installed, you will be ready for the next step.
Installing Subversion Client Software
Now that you have Subversion binaries installed and ready to operate, you will need to install and configure an a client software package that will allow you to download your site's repository files, make and track changes, and upload your changes using the Subversion system. There are a few stable open source (i.e. freely downloadable) Subversion client software packages available providing a GUI interface for handling the Subversion process. The one we have found most often recommended is called SVNX. Information about SVNX and downloading are available from La Chose Interactive, SVNX's developer. Versiontracker.com also maintains download mirrors for SVNX. We recommend downloading SVNX and installing it onto your computer.
Configuring Subversion Client Software
To use your GUI Subversion client software will require some configuring. Basically, you need to tell the software where your "repository" is and where your "working copy" will reside. The repository is the location of your Drupal installation on Advantage Labs' server. Your working copy is a folder on your local computer where you will store the "checked out" version of your Drupal site for local modifying.
First create a folder for your working copy. Technically, you can create a folder anywhere on your computer for this purpose. But, we have found that the Sites folder is a logical place. Each user on your computer has a Sites folder. Click on the User and open the Sites folder. Create a new folder inside the Sites folder and name it to reflect the name of your site. For example if your site is foo.com, you could name your working copy folder "foo_svn" or something similar. From within your client software, you will identify this folder as the place to store files checked out from the server.
Now open your client software and navigate to your Working Copies window. In SVNX click on Window>Working Copies. Click to add (+ button in SVNX) your new working copy folder. In the Path field, click to navigate (magnifying glass icon in SVNX) to your newly set up folder (foo_svn in the example). You can also type in the path. If you followed the above example it would be: Users/[yourusername]/Sites/[foo_svn] Give the working copy a name. foo_workingcopy for example. In SVNX you also have the ability to add a username and password for access to the working copy.
You also need to let your client software know the location of your site's repository. In SVNX this is handled in the Respositories window (Window>Repositories). Give your Repository a name, foo_repository, for example. Your repository lives on the Advantage Labs subversion server at http://svn.advantagelabs.com. The specific path to your site is (replace the foo.com with your site's url): http://svn.advantagelabs.com/sites/foo.com/drupal/branches/drupal-5
Add your Advantage Labs username and password to the settings and the Respository settings are ready for you to use.
Configuring Apache for URL Local Aliasing
The pieces are coming together. You have Subversion binaries configured on your system. You have a Subversion GUI client software on your computer configured to access your site's repository and store a working copy on your local computer. Now it's time to configure your computer to recognize the working copy of your website once you've downloaded it. This involves adding some settings to both MAMP's running version of Apache (webserving software program) and also your Mac's webserving addressing settings. Adding these settings will allow you to view and work on your Drupal's working copy within your web browser by giving it the URL: local.foo.com
First you'll need to add some code to an Apache file in your MAMP installation. Technically, you will be setting up what's called a Virtual Host for your Drupal site's working copy. The document you need to work with is named "http.conf." It is located in Applications>MAMP>conf>apache>httpd.conf Open this file using a text editor. TextEdit will work fine. Another free text editor, TextWrangler, is easy to use and adds the advantage of highlighting web and other software code in different colors to make editing of code easier. The important thing is to work with your documents in text-only mode. If you use MS Word, make sure to not save the resulting document as a Word document (.doc). It's best just to use an editor like TextEdit or TextWrangler that are designed to work with text-only documents.
Once you have httpd.conf open, scroll down to "Section 3: Virtual Hosting" at the bottom of the document. This section is mostly "commented out" meaning it has # symbols at the beginning of each line which keeps the code from being utilized. You will be removing the # symbols from some of the code at the bottom and modifying its contents to become active. You will be creating "virtual hosts" for your MAMP installation start page and also your website's working copy. Each of these hosts will be surrounded by the tag <virtualhost *80></virtualhost>. There are three components to each virtualhost entry: ServerAdmin, DocumentRoot and ServerName.
- ServerAdmin: the value for this component is username@localhost where "username" is an Administrative username for your computer
- DocumentRoot: this is the path to the "drupal" folder in your site's local working copy folder (as documented above)-- Users/username/Sites/foo_svn/drupal-- where "foo_svn" is the name of the folder you set up above
- ServerName: this is the URL for your site to be used in your web browser to access your site-- local.foo.com -- where foo.com is your site's live URL; note you will be setting up your computer to recognize this URL in the next section of these instructions
The full code for your site's working copy virtualhost will look like this:
<virtualhost *:80>
ServerAdmin username@localhost
DocumentRoot /Users/username/Sites/foo_svn/drupal
ServerName local.foo.com
</virtualhost>
If you will be maintaining multiple websites using Subversion, you can add additional virtualhost entries in this document.