HOWTO: Subversion for Windows with Apache server - a beginner's guide [version 0.4]

Index

• 1. Introduction
• 2. Installation
• 2.1. Setting up the OS
• 2.2. Installing Subversion
• 2.3. Installing Apache 2.0
• 3. Configuration
• 3.1. Configuring Subversion
• 3.2. Configuring Apache 2.0 server
• 4. Backup
• 4.1. What to back up?
• 4.2. Creating a repository dump
• 5. Upgrade
• 5.1. Upgrading Apache 2.0 server
• 5.2. Upgrading Subversion
• Conclusion
• History of changes

1. Introduction

The Subversion for Windows HOWTO describes from a beginner's perspective, how to install the Subversion server on a Windows system, and get it running. This how to describes how to use the Apache 2.0 server as the network server component of the Subversion.

This guide is from beginner to beginners. The author of this HOWTO doesn't have any experience with any other Version Control system, so when we decided to start using such a system, everything was mostly new.

The guide will describe topics like the installation, basic configuration and setting up backup. It will provide working examples of configuration, ready for you to modify and use. Hopefully the HOWTO will grow, as the author gets more familiar with the system, more topics will get added, and providing the decision I have made are correct, not much will get changed.

Before I begin, I must mention the Subversion book which was really helpful, but still sometimes there just isn't time to read the book, and you're looking for a quick guide that will help you get the system up and running ASAP. There is always time to read the book later [yeah, right].

Hopefully, this will turn out to be such a guide. It contains examples that you can download, modify and start using immediately. It should help you set up a Subversion server, including repository backup, in under two hours. It does not contain instructions or examples for the Subversion client. But, if you're using Eclipse, the Subclipse client will not take more than additional five minutes of your time.

2. Installation

2.1. Setting up the OS

2.2. Installing Subversion

The Subversion Windows installation package can be downloaded from the Subversion server, at the following URL:

http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91

I have downloaded the distribution packaged in a standard Windows installation program. For the Subversion version 1.1.3, grab the file named svn-1.1.3-setup.exe .

The installation itself is completely straight-forward. You read [and accept] a license agreement, select the destination directory, press Next a couple of times, wait for the file copying to stop and press finish. What you get in the end, is a link to the documentation on your desktop [the icon image is broken], and the Subversion is installed in the directory you have specified.

The default directory is C:\Program Files\Subversion, and here is a list of directories the installation creates:

The C:\Program Files\Subversion\bin is added to the path.

And that's about all there is to the installation.

2.3. Installing Apache 2.0

The Apache 2.0 server for Windows installation package can be downloaded from the Apache.org server, at the following URL:

http://httpd.apache.org/download.cgi

I have downloaded the distribution packaged in a standard Windows installation program - the Win32 Binary (MSI Installer) .

The installation itself is completely straight-forward. You read [and accept] a license agreement, enter your domain name, server name, the administrator's e-mail address, and the port the server will be listening on. The default values are already selected for you. For dedicated a subversion server, I suggest you leave it running on port 80. You can always change it later.

Then you can select typical, or custom install. Selecting typical install lets you choose the destination directory, and after that it starts copying files. When it finishes, you're done.

At this point it is probably recommendable to restart the system, before moving on to configuration.

3. Configuration

3.1. Configuring Subversion

    C:\Repositories\project1
    C:\Repositories\project2
    

    svnadmin create C:\Repositories\project1
    svnadmin create C:\Repositories\project2
    

Basically this is pretty much it, when it comes to creating the repositories. As the Subversion book tells us, each repository is stored in a Berkeley DB database, which can be configured in many different ways, but the default configuration works, and for a beginner, I found no reason to change anything.

To make them available to your development teams, the Apache server needs to be configured.

3.2. Configuring Apache 2.0 server

Step 2
Modify the C:\Program Files\Apache Group\Apache2\conf\httpd.conf file:

Add the modules to the Apache server

    LoadModule  dav_module             modules/mod_dav.so
    LoadModule  dav_svn_module         modules/mod_dav_svn.so
    LoadModule  authz_svn_module       modules/mod_authz_svn.so

Add the Access lines to the <Directory> sections, to protect your system.

<Directory />
    Options FollowSymLinks
    AllowOverride None
    Order Allow,Deny
    Allow from 10.0.1
</Directory>

<Directory "C:/Program Files/Apache Group/Apache2/htdocs">

#
# Possible values for the Options directive are "None", "All",
# or any combination of:
#   Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
#
# Note that "MultiViews" must be named *explicitly* --- "Options All"
# doesn't give it to you.
#
# The Options directive is both complicated and important.  Please see
# http://httpd.apache.org/docs-2.0/mod/core.html#options
# for more information.
#
    Options Indexes FollowSymLinks

#
# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
#   Options FileInfo AuthConfig Limit
#
    AllowOverride None

#
# Controls who can get stuff from this server.
#
    Order allow,deny
    Allow from 10.0.1

</Directory>

This allows access from all computers in the address range 10.0.1.1 - 10.0.1.254 .

At the end of the file, include a Subversion configuration file. We will create this file in one of the next steps.

    Include c:/etc/subversion.conf

We place the subversion.conf file in the before mentioned etc directory.

Step 3
Our decision was that anonymous access to repositories will not be allowed. Also, we would like that only the developers working on a specific project, can modify the contents of that project's repository. All other developer will have read only permissions to all projects. After all, we want our developers to share their code, don't we.

So first, we create a password file for authentication. All the developers that will use our Subversion server must chose a user name and a password. Unfortunately, the simplest way to do this is locally, so you must ask all the developers to come to the system and enter chose a password.

In the best tradition of Subversion book, let us name our developers Harry and Sally. Since we have two projects, we'll have a somewhat bigger development department, adding Ross and Rachel to our list of employees.

C:\etc>C:\Program Files\Apache Group\Apache2\bin\htpasswd -cm C:\etc\svn-auth-file harry
New password: ***** 
Re-type new password: *****
Adding password for user harry

C:\etc>C:\Program Files\Apache Group\Apache2\bin\htpasswd -m C:\etc\svn-auth-file sally
New password: *******
Re-type new password: *******
Adding password for user sally

C:\etc>C:\Program Files\Apache Group\Apache2\bin\htpasswd -m C:\etc\svn-auth-file ross
New password: ***** 
Re-type new password: *****
Adding password for user ross

C:\etc>C:\Program Files\Apache Group\Apache2\bin\htpasswd -m C:\etc\svn-auth-file rachel
New password: ***** 
Re-type new password: *****
Adding password for user rachel

When using the command for the first time, add the -c option. This creates the file named C:\etc\svn-auth-file . The -m option instructs the htpasswd utility to use MD5 algorithm to encrypt the passwords.

Step 4
Now that we can authenticate our users, we must configure the access rights to our repositories. To do this, we create another file in our etc directory.

C:\etc\svn-acl

#
# specify groups here
#
[groups]
team1 = ross, rachel

#
# team1 group has a read/write access to project1 repository
# all subdirectories
# all others have read access only 
#
[project1:/]
@team1 = rw
* = r

#
# project2 repository, only harry and sally have read-write access to project2
#
[project2:/]
harry = rw
sally = rw
* = r

#
# ross is helping with the time zone part of the project2
#
[project2:/timezone]
harry = rw
sally = rw
ross = rw
* = r

The groups section can be used to define groups of users. For repository project1, only users from the group team1 have read/write access. All other users have read only access.

It is possible to define access for the entire repository, or for specific directory within repository.

Step 5
In the end it is time to link the Apache server with the Subversion. This is done using the C:\etc\subversion.conf file:

<Location /project1>
  DAV svn
  SVNPath C:/Repositories/project1

  AuthType Basic
  AuthName "Subversion Project1 repository"
  AuthUserFile c:/etc/svn-auth-file

  Require valid-user

  AuthzSVNAccessFile c:/etc/svn-acl
</Location>

<Location /project2>
  DAV svn
  SVNPath C:/Repositories/project2

  AuthType Basic
  AuthName "Subversion Project2 repository"
  AuthUserFile c:/etc/svn-auth-file

  Require valid-user

  AuthzSVNAccessFile c:/etc/svn-acl
</Location>

The developers can access the C:\Repositories\project1 repository at the http://subversion/project1 URL. The access is only available to a valid user, and a basic HTTP authentication is used. The Apache server can read the valid user names and passwords from the C:\etc\svn-auth-file file. The c:\etc\svn-acl file defines the access rights to the repository.

Conclusion
So, we have created the Subversion repositories, and configured an Apache server to get them over the network. User names and passwords have to be used to access the repositories, and different levels of access are given to different users. So, we now have a working Version control system - it is time move on to the next chapter.

4. Backup

After reading the Subversion book I have decided, that since I don't know anything about the Berkeley DB administration, and that if our server crashes, we might move to a new version of Subversion, it seems wisest to backup all the data in the Subversion dump file format. This will [hopefully] allow any future version of Subversion to digest the data, and in the event of system recovery, we will not have to battle with a set of unknown database tools.

Hopefully, getting to know the system will not make me regret this decision. So, all we are left to do is create a system utility that will run every once in a while, and dump all the changes made to a repository in a new file. Moving that data to some sort of a permanent storage [tape or CD-ROM] is not a subject of this HOWTO.

4.1. What to back up?

4.2. Creating a repository dump

The file backup.vbs is available for download.

Const ForReading = 1
Const ForWriting = 2
Const ForAppending = 8

Const folderName = "C:\backup\dumps\"
Const repositoryProj1 = "C:\Repositories\project1"
Const repositoryProj2 = "C:\Repositories\project2"

getYoungestProj1 = "C:\Progra~1\Subversion\bin\svnlook.exe youngest " + repositoryProj1
getYoungestProj2 = "C:\Progra~1\Subversion\bin\svnlook.exe youngest " + repositoryProj2

Set objFSO = CreateObject( "Scripting.FileSystemObject" )
Set WshShell = CreateObject( "WScript.Shell" )

Call CreateDump( "C:\backup\proj1.log", "C:\etc\proj1-last", getYoungestProj1, repositoryProj1, "proj1" )
Call CreateDump( "C:\backup\proj2.log", "C:\etc\proj2-last", getYoungestProj2, repositoryProj2, "proj2" )

WScript.Quit( 0 )

'********************************************************************************
'*
'* End of script body
'*
'********************************************************************************

Sub CreateDump( logFileName, lastFileName, getYoungestCmd, repository, dumpName )

  ' Open the log file
  Set objLogFile = objFSO.OpenTextFile( logFileName, ForAppending, True )
  objLogFile.WriteLine Now & " - - Script started - -"
  
  ' Default last revision is 0
  lastRev = 0
  
  ' Does the file exist?
  If ( objFSO.FileExists( lastFileName ) ) Then
    Set objFile = objFSO.GetFile( lastFileName )
    ' Does it contain anything?
    If ( objFile.Size > 0 ) Then
      Set objTextFile = objFSO.OpenTextFile( lastFileName, ForReading )
      ' Get the last revison and increase it by 1
      lastRev = objTextFile.Readline
      lastRev = lastRev + 1
    End If
  End If
  
  ' Execute the getYoungestCmd and read its output
  Set objExec = WshShell.Exec( getYoungestCmd )
  
  Do While ( objExec.Status <> 1 )
       WScript.Sleep 100
  Loop
  
  youngest = objExec.StdOut.Readline
  
  ' Is the youngest revision above the last one?
  If ( CLng( lastRev ) > CLng( youngest ) ) Then
    objLogFile.WriteLine Now & "   Exiting: lastRev (" & lastRev & ") > youngest (" & youngest & ")"
    objLogFile.WriteLine Now & "     Script done"
    objLogFile.Close
    Exit Sub
  End If
  
  ' Compose the file name
  dumpFileName = folderName & dumpName & "-" & lastRev & "-" & youngest & ".dmp"
  
  ' Add incremental, if not starting a new dump
  incremental = ""
  If ( lastRev > 0 ) Then
    incremental = " --incremental"
  End If
  
  ' Compose the dump command for the current repository
  dumpCommand = "C:\Progra~1\Subversion\bin\svnadmin.exe dump " & repository & _
                " --revision " & lastRev & ":" & youngest & incremental
  
  ' Open the destination file and execute the dump command
  Set objDumpFile = objFSO.OpenTextFile( dumpFileName, ForWriting, True )
  Set objExecDump = WshShell.Exec( dumpCommand )
  
  ' Read the dump output and write it to the file
  Do While True
       If Not objExecDump.StdOut.AtEndOfStream Then
            input = objExecDump.StdOut.Read( 1 )
            objDumpFile.Write input
       Else
         Exit Do
       End If
  Loop
  objDumpFile.Close
  
  ' Write the latest revision into the file
  Set objTextFile = objFSO.OpenTextFile( lastFileName, ForWriting, True )
  objTextFile.Write youngest
  objTextFile.Close
  
  ' Close the log file and exit
  objLogFile.WriteLine Now & "     Script done"
  objLogFile.Close
  
End Sub

5. Upgrade

5.1. Upgrading Apache 2.0 server

Now you are ready to install the new Apache 2.0 server as described in section 2.3. Installing Apache 2.0. After that, all you need to do is put the old httpd.conf in the C:\Program Files\Apache Group\Apache2\conf folder, copy the mod_authz_svn.so and mod_dav_svn.so into the C:\Program Files\Apache Group\Apache2\modules folder, and you're done. You have just successfully apgraded Apache 2.0 server.

5.2. Upgrading Subversion

***** IMPORTANT *** Upgrading from 1.1.x to 1.2.x *** IMPORTANT *****

In this release, we've upgraded BerkeleyDB from version 4.2.52 to
4.3.27.  If you are currently using Subversion 1.1.x as a server on
Windows with BerkeleyDB, use the following steps to upgrade your
repositories:

  -- Make sure nobody is using the repository (stop Apache/svnserve,
     restrict access via file://).
  -- For each repository, using the old (1.1.x) binaries:
     -- Run "svnadmin recover <repos-dir>";
     -- Create a backup of the repository;
     -- Run "svnadmin list-unused-dblogs <repos-dir>"
        and remove the listed files;
     -- Delete all the "<repos-dir>\db\__db.00?" files.
  -- Upgrade Subversion.

Once again, this is only necessary for repositories based on BDB.
You do NOT have to dump/reload your repositories.

*********************************************************************

    svnlook youngest C:\Repositories\project2

    C:\windows\system32\cscript.exe c:\etc\backup.vbs

Step 4
Now you can run the Subversion installation. The process is described in section 2.2. Installing Subversion, with a few minor differences.

The installation process detects that you are running an Apache 2.0 server, and notifies you, that it will stop its services, and restart them after the installation. Also, it offers to copy the mod_authz_svn.so and mod_dav_svn.so to the C:\Program Files\Apache Group\Apache2\modules folder for you, but there is an error in the current installation of Subversion, which prevents this from happenning.

After the installation is complete, check the Apache services, and stop them if they are running.

Step 5
Recreate the directories first:

    C:\Repositories\project1
    C:\Repositories\project2

Step 6
And the repositories themselves; the default storage for the repository has changed from BerkeleyDB to FSFS, so you need to specify --fs-type bdb explicitly if you want to create a BerkeleyDB repository.

    svnadmin create --fs-type bdb C:\Repositories\project1
    svnadmin create --fs-type bdb C:\Repositories\project2

Step 7
Now you need to reload the repositories from the backup files, using the load command.

    svnadmin load C:\Repositories\project1 < C:\backup\dumps\proj1-0-53.dmp
    svnadmin load C:\Repositories\project1 < C:\backup\dumps\proj1-54-64.dmp
    [ etc ]
    
    svnadmin load C:\Repositories\project2 < C:\backup\dumps\proj2-0-32.dmp
    svnadmin load C:\Repositories\project2 < C:\backup\dumps\proj2-33-109.dmp
    [ etc ]

Step 8
One last thing you need to do, is manually copy the mod_authz_svn.so and mod_dav_svn.so files to the C:\Program Files\Apache Group\Apache2\modules directory. The location of the files has changed with the version 1.2.0 and the msi script doesn't seem to be aware of that either. You can find both files in the C:\Program Files\Subversion\bin directory.

Step 9
There is just one final thing left to do, and that is start the Apache server.

Subversion is now upgraded to version 1.2.0, and if that is what you have decided, your repositories have been reloaded from revision 0 up with all your data, resulting in a faster repository operations.

Conclusion

This has been my experience with the Subversion. If you have any comments, suggestions, have better ideas, or plainly want to correct some colossal stupidity this HOWTO contains, you can contact me at mike5@eunet.si.

Please note, that this is my public e-mail address [think TONS of SPAM, and more to come after this, I guess :( ], so please start your Subject with "Subversion HOWTO" or something, to make it stand out from all the Viagra offerings, and unknown hot women trying to get a date with me :).

History of changes