What is Pushmi?

Pushmi is a Subversion accelerator. It presents a local copy of one or more remote repositories, speeding up Subversion queries by removing latency to the master server. It additionally supports transparent write-through to the master server, allowing users to both read and commit using it.

Getting started

This package consists of a standalone Pushmi appliance disk image. Depending on the version you have, it may either be in the form of a VMware Server package (a .tar.bz2 archive of a collection of files), or a Xen disk image (a .img file).

Installing the VMware image

The following instructions and images presume you are using VMware Server 2.0.

Unpack the Pushmi-8.10.tar.bz2 archive inside your VMware Server datastore. The default location for the datastore is /var/lib/vmware/Virtual Machines/
```
    $ cp Pushmi-8.10.tar.bz2 /var/lib/vmware/Virtual Machines/
    $ cd /var/lib/vmware/Virtual Machines/
    $ tar xjf Pushmi-8.10.tar.bz2
```
Log into the VMware Server web interface as root, or any user which has permissions to create virtual machines.
From the Virtual Machine menu, choose Add Virtual Machine to Inventory.
Navigate to, and select, the Pushmi.vmx file.
Start the new Pushmi virtual appliance.

First boot configuration

When your Pushmi application is first started, it will ask a number of networking questions, so it can better configure itself. The foremost question it poses is whether to continue to obtain a DHCP address, as it did in the first boot, or to use a static address.

DHCP configuration

Using DHCP is the simplest use case; this is ideal for private VMware appliances for testing, or a single developer. If VMware is configured for NAT networking, the Pushmi appliance will be given a private (but consistent) internal IP address, which can be used by the VMware host machine.

The drawbacks to this configuration are that the Pushmi appliance is only useful to the VMware host, obviously. Configuring the VMware host for Bridged networking and relying on a DHCP server on the host's network will not work around this drawback, as the external DHCP server will most probably not provide a consistent IP address to the Pushmi appliance. It will suffice for simple multi-user testing, however.

Static IP configuration

To make the Pushmi appliance useful to more than one developer, you will want to configure VMware for Bridged networking, and ask your local network administrator to allocate a static IP address for your Pushmi appliance. You will need to know the following information:

Hostname
IP address
Netmask
Subnet
Default gateway

With this information, the Pushmi appliance can reconfigure itself to obtain a static IP address for subsequent boots.

Creating a local mirror

Replicas

The first step after successfully configuring your Pushmi instance is to create a new local replica. A local replica is a complete mirror of a remote repository, including all revision history. You will need to give a human-readable name, as well as a URL to the root of the repository to mirror. At this time, Pushmi only supports mirroring repositories which are available via http://, https://, or file://

Some repositories may require authentication in order to read the repository -- in all other cases, the username and password fields are optional. Pushmi will prompt you when authentication is required to read the repository.

Pushmi will then prompt you for the location to locally mirror the repository, then initialize it. The final step is to mirror all of the remote revisions of the repository locally, so they are available to clients.

Bootstrap files

For large replicas, you may need a "bootstrap file." Bootstrap files are simply the output of svnadmin dump, optionally gzip'd. To generate a bootstrap file, you will need access to the filesystem which the repository resides on; you cannot create a bootstrap file remotely -- svnadmin acts on paths, not URLs. Creating a bootstrap file is a simple matter of running:

    svnadmin dump /path/to/repository | gzip > bootstrap.gz

This may take some time for large repositories. After the command completes, place the bootstrap.gz file somewhere accessible by HTTP from the Pushmi application. During the synchronization step, Pushmi will prompt you to enter the URL to a bootstrap file, which will allow synchronization to proceed significantly faster.

Subversion client configuration

After setting up your replica, you should reconfigure your Subversion clients to use it. On each replica's page, there should be a Mirrored locally as section. From each subversion checkout of the repository, run:

    svn switch --relocate http://master.example.com/project \
                          http://pushmi.example.com/project

...replacing http://master.example.com/project with the master repository URL (available via running svn info, and reading the URL entry), and http://pushmi.example.com/project with the URL provided in the Mirrored locally as section discussed above.

By default, Pushmi presents replicas via http://, and clients should be able to svn switch to them with no change in their username or password. In the future, Pushmi will be able to present replicas via https://, as well as svn:// and possibly svn+ssh://.