# gitolite installatation

In this document:

  * <a href="#A1">please read this first</a>
      * <a href="#A2">important notes</a>
      * <a href="#A3">conventions used</a>
      * <a href="#A4">requirements</a>
          * <a href="#A5">client side</a>
          * <a href="#A6">server side</a>
  * <a href="#A7">installation and setup</a>
      * <a href="#A8">(package method) directly on the server, using RPM/DEB</a>
      * <a href="#A9">(root method) directly on the server, manually, with root access</a>
      * <a href="#A10">(non-root method) directly on the server, manually, without root access</a>
      * <a href="#A11">(from-client method) install from the client to the server</a>
  * <a href="#A12">special cases -- multiple gitolite instances</a>
  * <a href="#A13">upgrading</a>
  * <a href="#A14">uninstalling</a>
      * <a href="#A15">cleaning out a botched install</a>
      * <a href="#A16">uninstalling gitolite completely</a>

----

<a name="A1"></a>

### please read this first

<a name="A2"></a>

#### important notes

Please make sure you understand the following points first.

  * gitolite is somewhat unusual as far as "server" software goes -- every
    userid on the server is a potential "gitolite host".

  * gitolite depends **heavily** on ssh pubkey (passwordless) access.  Do not
    assume you know all about ssh -- most people **don't**.  If in doubt, use
    a dedicated userid on both client and server for installation and
    administration of gitolite.

    To make matters worse, ssh problems in gitolite don't always look like ssh
    problems.  See [doc/6-ssh-troubleshooting.mkd][doc6] for help.

<a name="A3"></a>

#### conventions used

We assume the admin user is "sitaram", and his workstation is called "client".
The hosting user is "git", and the server is called "server".  Substitute your
values as needed.

<a name="A4"></a>

#### requirements

<a name="A5"></a>

##### client side

  * git version 1.6.2 or greater
      * even msysgit on Windows is fine; please don't ask me for help if
        you're using putty, plink, puttygen, etc., for ssh; I recommend
        msysgit for Windows and the openssh that comes with it
  * if you're using the "from-client" method of install (see below), the bash
    shell is needed
      * again, msysgit on Windows is fine

<a name="A6"></a>

##### server side

  * any Unix system with a posix compatible "sh".
      * people using "csh" or derivatives please don't ask me for help -- tell
        your admin csh is not posix compatible
  * git version 1.6.2 or greater
      * 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 (but since git requires it anyway, you probably have it)
  * openssh or any ssh that can understand the `authorized_keys` file format

<a name="A7"></a>

### installation and setup

<a name="A8"></a>

#### (package method) directly on the server, using RPM/DEB

  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
    Put it in `/tmp/sitaram.pub`.

  * (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.).

  * on the server, "su - git", then as "git" user, run `gl-setup
    /tmp/sitaram.pub`.

  * on the client, run `cd; git clone git@server:gitolite-admin`

<a name="A9"></a>

#### (root method) directly on the server, manually, with root access

  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
    Put it in `/tmp/sitaram.pub`.

  * (U) on the server, as root, do the following:

        cd $HOME
        git clone git://github.com/sitaramc/gitolite gitolite-source
        cd gitolite-source
        mkdir -p /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
        src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks

  * on the server, "su - git", then as "git" user, run `gl-setup
    /tmp/sitaram.pub`.

  * on the client, run `cd; git clone git@server:gitolite-admin`

<a name="A10"></a>

#### (non-root method) directly on the server, manually, without root access

WARNING: if you use this method you'd better know enough about ssh to be able
to keep your keys straight, and you'd also better have password access to the
server so that if you screw up the keys you can still get on, or be able to
"su - git" from some other user on the server.

  * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
    Put it in `/tmp/sitaram.pub`.

  * (U) on the server, as "git", do the following:

        cd $HOME
        git clone git://github.com/sitaramc/gitolite gitolite-source
        cd gitolite-source
        mkdir -p $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
        src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks

  * on the server, still as "git", run `gl-setup /tmp/sitaram.pub`.

  * if `$HOME/bin` is not on the default PATH, fiddle with your `.bashrc` or
    `.bash_profile` files and add it somehow.  You can also try adding
    `$GIT_PATH = "$ENV{HOME}/bin";` to `~/.gitolite.rc` on the server.

  * on the client, run `cd; git clone git@server:gitolite-admin`

<a name="A11"></a>

#### (from-client method) install from the client to the server

This used to be the most common install method for a long time, and it is
still the one I use for most of my testing.  The **main advantage** of this
method is that it **forces you** to solve the ssh pubkey problem **before**
attempting to install.  Sadly, it also forces the admin to use a **different**
URL for gitolite repos than normal users, which seems to confuse a heck of a
lot of people who don't read the prominently displayed messages and/or the
documentation.

This method is verbosely documented in [doc/7-install-transcript.mkd][doc7],
including *outputs* of the commands concerned.

<a name="A12"></a>

### special cases -- multiple gitolite instances

With the first two methods (package or root methods) of installation, it's
trivial to create multiple gitolite instances (say one for each department, on
some mega company-wide server).  You can even do this without giving shell
access to the admins.  Here's an example with just two "departments", and
their admins Alice and Bob:

  * create userids `webbrowser_repos` and `webserver_repos`
  * ask Alice and Bob for their pubkeys; copy them to the respective home
    directories for convenience
  * run `su - webbrowser_repos`, then `gl-setup alice.pub`
  * (similarly with `webserver_repos` and `bob.pub`, and so on for others)

That's it.  The URL for all web browser projects is now something like
`webbrowser_repos@server:reponame`, and similarly for the others.

Notice that you only have to do this once for each "department", and it's
really just one command after creating the userid.  None of these admins need
to have a command line on the server, so don't give them the passwords if you
don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations.

<a name="A13"></a>

### upgrading

Upgrading gitolite is easy.  In each method above, just re-do the step that is
marked "(U)".  Also, if you're using either of the two methods that use the
`src/gl-system-install` command, please make sure you give it the same
arguments!

Also, remember that some new features may require additional settings in your
`~/.gitolite.rc` file.

<a name="A14"></a>

### uninstalling

<a name="A15"></a>

#### cleaning out a botched install

When people have trouble installing gitolite, they often try to change a bunch
of things manually on the server.  This usually makes things worse ;-) so
here's how to clean the slate.

  * client-side
      * edit `~/.ssh/config` and delete the paragraph starting with `host
        gitolite`, if present.
      * remove `~/gitolite-admin`
  * server-side
      * edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite
        start` and `# gitolite end` inclusive.
      * remove `~/.gitolite`, `~/.gitolite.rc` and
        `~/repositories/gitolite-admin.git`

<a name="A16"></a>

#### uninstalling gitolite completely

There's some duplication between this and the previous section, but
uninstalling gitolite is described in great detail in
[doc/9-uninstall.mkd][doc9unin]

----

[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd
[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd