# installing gitolite

This document tells you how to install gitolite.  After the install is done,
you may want to see the [admin document][admin] for adding users, repos, etc.

[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd

There's an easy install script that requires bash (**strongly** recommended),
but if you have no bash or you're on one of the legacy Unixes there's a
slightly more manual process.  Both are explained here.

In this document:

  * easy install
      * typical example run
      * advantages over the older install methods
      * disadvantages
  * manual install
  * upgrades
  * other notes
  * next steps
  * appendix: server and client requirements

----

### easy install

There is an easy install script that makes installing very easy for the common
case.  **This script is meant to be run on your workstation, not on the
server!**  It will take care of all the server side work, *and* get you
"push-to-admin" too :-)  In short, it does **everything**!

Assumptions/pre-requisites:

  * you have a server to host gitolite
  * git is installed on that server (and so is perl)
  * you have a userid on that server
  * you have ssh-pubkey (**password-less**) login to that userid
      * (if you have only password access, run `ssh-keygen -t rsa` to create a
        new keypair if needed, then run `ssh-copy-id user@host`)
  * you have a clone or an archive of gitolite somewhere on your workstation

If so, just `cd` to that clone and run `src/gl-easy-install` and follow the
prompts!  (Running it without any arguments shows you usage plus other useful
info).

#### typical example run

A typical run for me is:

    src/gl-easy-install -q git my.git.server sitaram

`-q` stands for "quiet" mode -- very minimal output, no verbose descriptions
of what it is going to do, and no pauses unless absolutely needed.  However,
if you're doing this for the first time or you appreciate knowing what it is
actually doing, I suggest you skip the `-q`.

#### advantages over the older install methods

  * all ssh problems reduced to **just one pre-requisite**: enable ssh pubkey
    (password-less) access to the server from your workstation first
  * the script takes care of all the server side work
  * when done:
      * you get two different pubkeys (the original one for command line
        access as before, plus a new one, created by the script, for gitolite
        access)
      * you can admin gitolite by commit+push a "gitolite-admin" repo, just
        like gitosis (i.e., full "push to admin" power!)

#### disadvantages

  * need a recent bash

### manual install

If you don't have bash, it's not very complicated to do it manually.  Just
open the file `src/gl-easy-install` in a nice, syntax coloring, text
editor, and follow the instructions marked "MANUAL" :-)

### upgrades

Upgrading gitolite is easy.

To upgrade, pull the latest "master" (or other) branch in your gitolite repo
clone, then run the same exact command you ran to do the install, except you
can leave out the last argument.

And you might want to add a `-q` to speed things up :-)

Note that this only upgrades the software.  Unlike earlier versions, it does
**not** touch the `conf/gitolite.conf` file or the contents of `keydir` in any
way.  I decided that it is not possible to **safely** let an upgrade do
something meaningful with them -- fiddling with existing config files (as
opposed to merely creating one which did not exist) is best left to a human.

### other notes

  * if you run `src/gl-easy-install` without the `-q` option, you will be
    given a chance to edit `~/.gitolite.rc`.  You can change any options (such
    as paths, for instance), but be sure to keep the perl syntax -- you
    *don't* have to know perl to do so, it's fairly easy to guess in this
    limited case.

### next steps

The last message produced by the easy install script should tell you how to
add users, repos, etc., and you will find more details in the [admin][admin]
document.

<a name="server_reqs"></a>

### appendix: server and client requirements

There are 3 machines *potentially* involved in installing and administering
gitolite.

#### server

This is where gitolite is eventually installed.  You need a *normal* userid
(typically "git" but can be anything) on this machine; root access is *not*
needed.

You need the following software on it:

  * git
      * can be in a non-PATH location if you are unable to install it
        normally; see the `$GIT_PATH` variable in the "rc" file
  * perl
      * default install is fine; no special modules are needed
      * (a normal install of git also requires/installs perl, so you probably
        have it already)
  * openssh server
      * (I guess any ssh server that can understand the `authorized_keys` file
        format should work)
  * **bash shell**
      * a small part of the gitolite server side is written in "bash"; I
        intend to test it (time permitting) on non-bash (like ksh or plain sh)
        on non-Linux servers.  Once that is done, this bash dependency will go
        away.

#### install workstation

Installing or upgrading the gitolite software itself is best done by running
the easy-install program from a clone, usually on a different machine.

This script is heavily dependent on bash, so you need a unix machine that has
a bash shell available.  Unlike the server side dependency mentioned above,
this bash dependency is probably permament.

*However*, you do not need to use this machine every day.  Day to day
administration of gitolite (adding users, repos, etc) can be done from
anywhere; see next section.

If you do not have such a machine, you have the following alternatives:

  * use a different userid on the same server
  * use the same userid on the same server!
  * (either of the above cases makes bash mandatory on the server, by the way)
  * manually simulate the script directly on the server; doable, but tedious

#### admin workstation(s)

When you install gitolite, it creates a repository called "gitolite-admin" and
gives you permissions on it.

Administering gitolite (adding repos/users, assigning permissions, etc) is
done by cloning this repo, making changes to a file called
`conf/gitolite.conf`, adding users' pubkeys to `keydir/`, and pushing the
changes back to the server.

Which means all this can be done from *any* machine, even Windows.  [Just make
sure your pubkey (from the Windows machine) has been added and permissions
given to allow you to push to the gitolite-admin repo.  This is also how other
people can be added as "admins": add their pubkey to as
`keydir/<username>.pub`, and give `<username>` at least `RW` permissions on
the `gitolite-admin` repo in the `conf/gitolite.conf` file.]