Initial Setup

In Ubuntu Hardy, all the tools you will need for a basic subversion server are included in the subversion package. If you haven’t already you can install it with the following command:

sudo aptitude install subversion

The next steps is to create a new group that will be responsible for subversion tasks.

• From the Panel, navigate to System > Administration > Users and Groups
• If necessary, unlock the dialog, and then click “Manage Groups”
• Click “Add Group”. Create a group named “subversion”, and add yourself to it.
• Log out and back re-log in for the changes to take effect.

Now that the group is created, the next step is to create the directory structure where our repositories will live. You can create the folder wherever you’d like, but a good choice is /home/svn

• In a terminal, create your new folder, using the commands:

cd /home

sudo mkdir svn

That’s it for the basic setup. Of course, the subversion server isn’t useful until we add a repository or two..

Adding the First Repository

In subversion, each project or directory structure is contained within its own repository. Each repository (or repo for short) maintains its own access control, versioning, and logs. Let’s create a new repository called “my-project”

First, we need to create the repository folder:

cd /home/svn

sudo mkdir my-project

Finally, we use the “svnadmin” command to create some base files and configure the repository.

sudo svnadmin create /home/svn/my-project

Now, change the access permissions to give the subversion group the proper settings:

sudo chgrp -R subversion my-project

sudo chmod -R g+rws my-project

This is the minimum work required to initialize a repository. At this point, you could start accessing your repository from the host computer. But, you may also want to fine-tune your configuration below.

Configuring Your Repository

At this point, you should have a working repository. However, there are still a few options you might want to tweak. In particular, the access permissions. By default, a fresh repository will be readable by anyone and writable by authorized users. To change these settings, open /home/svn/my-project/conf/svnserve.conf in your favorite text editor– you can use the command:

gedit /home/svn/my-project/conf/svnserve.conf

The lines that control access restrictions look like:

# anon-access = read

# auth-access = write

These two lines control anonymous access and authenticated access, respectively. To change from the default behavior for each value, remove the leading ‘#’ character, and set the right-side value to ‘read’, ‘write’, or ‘none’, for read-only, read-write, or no access, respectively. When you are finished, you can save the file and close it.

If you plan on using authenticated access to your repository, you will need to set up at least one username and password. To do so, open the /home/svn/my-project/conf/passwd file in a text editor:

gedit /home/svn/my-project/conf/passwd

To create a username, simply add a line to the bottom of the form:

username = password

There are a few examples already in the file, but commented out. You may add as many usernames as you need. When you are finished, save the file and close it. These are the basic configuration steps you’ll need, although more are discussed in the Final Steps.

Access From the Host Computer

At this point you are ready to test out your new repository. Any configured repositories should be accessible from the host computer as-is. You can test it out by checking-out your first working copy:

svn checkout file:///home/svn/my-project ~/my-project-wc

Perhaps you would like to add a “trunk” directory, where you will develop your project:

cd ~/my-project-wc

mkdir trunk

svn add trunk

svn commit -m "Add a trunk directory for development."

Depending on your configuration above, you may be asked for a user name and password. You should use the values you entered in the passwd file.

Access from a LAN Computer

If you have another laptop or desktop in your home, then you may want to also access your repository from it. Fortunately, extending your subversion server within a LAN isn’t too much more complicated, using the svn:// protocol.

First, you will need to set up a daemon on the host computer to listen for connections, using the svnserve command:

svnserve -d -r /home/svn

This starts a process in the background that will silently wait for connections to the subversion server. To run in the foreground, simply use the –foreground parameter.

Then, you can connect to your repository from any computer within your LAN, using the syntax:

svn checkout svn://my-host/my-project ~/my-project-wc

where my-host is the name your host computer. Note that it is also possible to connect using a Windows or Mac machine, with the same syntax.

Access from Outside the LAN

If others outside your LAN will need to use the repository, or you often work away from home, then you’ll want to set up your subversion server for access anywhere. This will require tweaking some setting in your router. Particularly, you will need to forward TCP port 3690 to the machine hosting the subversion server. I used a DD-WRT based router, but most router interfaces are similar.

• Open the web-based router control panel, and enter the administrative username and password. Generally, the address is similar to http://192.168.1.1
• Locate the settings for “Port Forwarding”. If you are using DD-WRT, navigate to NAT / QoS > Port Fowarding
• Add a new entry to forward TCP port 3690 to the IP address of your subversion host computer, with destination port also 3690. This is the default port that subversion listens on. Then, save your settings and close.

You can test your forwarded port by trying to connect using your external IP address. There are many websites that will help you find your external IP, such as http://whatismyipaddress.com/ Note that it shouldn’t start with 192.168…

svn checkout svn://{external-ip}/my-project ~/my-project-wc

If you plan to work away from home frequently, you may want to set up dynamic DNS– this provides you with a personalized hostname, so you don’t need to remember a cryptic IP address. If you are using DD-WRT, you can follow the following steps:

• Go to DynDNS.com and sign up for an account. Create a “Dynamic DNS” (DDNS) hostname.
• Log in to your DD-WRT admin panel as before, and navigate to Setup > DDNS.
• Enter your DynDNS account details into the appropriate fields.
• Hit “Apply Settings”– the DDNS status should show that your IP has updated successfully.

Once you have your DDNS hostname set up, you can use it to access your subversion repository, using the command:

svn checkout svn://{ddns-hostname}/my-project ~/my-project-wc

This should be accessible both inside and outside your LAN.

Final Steps

At this point, you should have a subversion repository up and running. However, there are still a few features you may be interested in.

To access your repository using the svn:// syntax, you will need to have the svnserve daemon running. You can easily set the command to run when you log in with the following steps:

• From the desktop panel, open System > Preferences > Sessions.
• Click the “Add” button to add a new Startup program.
• In the “Name” field, enter “Subversion Server Daemon”
• For the command, enter: svnserve -d -r /home/svn
• And in the description, add a useful summary such as “Listen for connections to the subversion repository”.

Now, your subversion repository will be accessible as long as your username is logged in.

Once you being using multiple repositories, you may want to share the same username database for them. For this, you will need to configure repositories to use the same “passwd” file and belong to a common realm. For each of the repositories that will share a username database:

• Open a terminal in the root directory of the repository:

cd /home/svn/{repository-name}

• Open the svnserve.conf file located in the conf directory using a text editor:

gedit conf/svnserve.conf

• Find and uncomment the line that starts with “passwd-db”. Enter the location of the passwd file that will be shared between databases. You may enter an absolute path, or a path relative to the conf directory.
• Find and uncomment the line that starts with “realm”. Set the right side to a name that will be shared between each of the repositories accessing the common database. You may use a descriptive name such as “work-repository-realm”.

Finally, you may want to use subversion from the file browser. Although not strictly part of setting up a server, it is often useful to install the Nautilus subversion plugin. This will allow you to right click on a subversion working copy folder and perform common subversion tasks. To install, simply enter the command:

sudo aptitude install nautilus-script-collection-svn

Update: Actually, it’s a little bit tricky to get the Nautilus plugin working.  If you’re having trouble, check out these instructions to enable SVN access in Nautilus.

And that’s it! Now, start using your repository and enjoy the benefits of version control. Are there any other tips that you would offer for setting up subversion? Let’s hear your experiences in the comments.