setup and usage

server level setup

To start with, assign each server a short name. We will use 'frodo', 'sam', and 'gollum' as examples here.

Generate ssh keys on each machine. Copy the .pub files to all other machines with the appropriate names. I.e., frodo should have sam.pub and gollum.pub, etc.

Warning: server keys are different from user keys. Do NOT attempt to (re-)use a server key for normal gitolite operations, as if the server were a normal "user"; it won't work.
Install gitolite on all servers, under some 'hosting user' (we'll use git in our examples here). You need not use the same hosting user on all machines.

It is not necessary to use the same "admin key" on all the machines. However, if you do plan to mirror the gitolite-admin repo also, they will eventually become the same anyway. In our example, frodo does mirror the admin repo to sam, but not to gollum. (Can you really see frodo or sam trusting gollum?)
Now copy hooks/common/post-receive.mirrorpush from the gitolite source, and install it as a custom hook called post-receive; see here for instructions.
Edit ~/.gitolite.rc on each machine and add/edit the following lines. The GL_HOSTNAME variable must have the correct name for that host (frodo, sam, or gollum), so that will definitely be different on each server. The other line can be the same, or may have additional patterns for other git config keys you have previously enabled. See here and the description for GL_GITCONFIG_KEYS in this for details.
```
$GL_HOSTNAME = 'frodo';     # will be different on each server!
$GL_GITCONFIG_KEYS = "gitolite.mirror.*";
```
(Remember the "rc" file is NOT mirrored; it is meant to be site-local).

Note: if GL_HOSTNAME is undefined, you cannot push to repos which have the 'gitolite.mirror.master' config variable set. (See 'details' section below for more info on this variable).

If you wish, you can also add this hostname information to the GL_SITE_INFO variable in the rc file. See the rc file documentation for more on that.
On each machine, add the keys for all other machines. For example, on frodo you'd run these two commands:
```
gl-tool add-mirroring-peer sam.pub
gl-tool add-mirroring-peer gollum.pub
```
Create "host" aliases on each machine to refer to all other machines. See here for what/why/how.

The host alias for a host (in other machines' ~/.ssh/config files) MUST be the same as the GL_HOSTNAME in the referred host's ~/.gitolite.rc. Gitolite mirroring requires this consistency in naming; things will NOT work otherwise.

For example, if machine A's ~/.gitolite.rc says $GL_HOSTNAME = 'frodo';, then all other machines must use a host alias of "frodo" in their ~/.ssh/config files to refer to machine A.

Once you've done this, each host should be able to reach the other hosts and get a response back. For example, running this on sam:

ssh frodo info

should get you

Hello sam, I am frodo.

Check this command from everywhere to everywhere else, and make sure you get expected results. Do NOT proceed otherwise.

repository level setup

Setting up mirroring at the repository level instead of at the "entire server" level gives you a lot of flexibility (see "discussion" section below).

The basic idea is to use git config variables within each repo (gitolite allows you to create them from within the gitolite.conf file so that's convenient), and use these to specify which machine is the master and which machines are slaves for the repo.

Let's say frodo and sam are internal servers, while gollum is an external (and therefore less trusted) server that has agreed to help us out by mirroring one of our high traffic repos. We want the following setup:

the "gitolite-admin" repo, as well as an internal project repo called "ip1", should be mastered on frodo and mirrored to sam.
internal project "ip2" has almost all of its developers closer to sam, so it should be mastered there, and mirrored on frodo.
an open source project we manage, "os1", should be mastered on frodo and mirrored on both sam and gollum.

So here's how our example would go:

Clone frodo's and sam's gitolite-admin repos to your workstation, then add the following lines to both their gitolite.conf files:
```
repo ip1 gitolite-admin
    config gitolite.mirror.master   =   "frodo"
    config gitolite.mirror.slaves   =   "sam"

repo ip2
    config gitolite.mirror.master   =   "sam"
    config gitolite.mirror.slaves   =   "frodo"
```
You also need normal access control lines for ip1 and ip2; I'm assuming you already have them elsewhere, at least on frodo. (What you have on sam won't matter in a few minutes, as you will see!)

Commit and push these changes.
There are a couple of quirks to keep in mind when you make changes to the gitolite-admin repo's config.
- the first push will create the git config entries required, but by then it is too late to act on them; i.e., actually do the mirroring. If there were any older values, like a different list of slaves perhaps, then those would be in effect.
  
  This is largely because git invokes post-receive before post-update. In theory I can work around this but I do not intend to.
  
  Anyway, this means that after the 2 pushes, you have to make a dummy push from frodo:
```
git commit --allow-empty -m empty; git push
```
  which gets you something like this amidst the other messages:
```
remote: (25158&) frodo ==== (gitolite-admin) ===> sam
```
  telling you that frodo is sending gitolite-admin to sam in the background.
- the second quirk is that your clone of server sam's gitolite-admin repo is now completely out of date, since frodo has overwritten it on the server. You have to 'cd' to that clone and do this:
```
git fetch
git reset --hard origin/master
```
That completes the setup of the gitolite-admin and the internal project repos. We'll now setup things for the open source project, "os1".

On frodo's gitolite-admin clone, add the following lines to conf/gitolite.conf, then commit and push:
```
repo os1
    config gitolite.mirror.master   =   "frodo"
    config gitolite.mirror.slaves   =   "sam gollum"
```
Also, send the same lines to gollum's administrator and ask him to add them into his conf/gitolite.conf file, commit, and push.