gitolite/doc/0-INSTALL.mkd

# installing gitolite

[Update 2009-11-18: easy install now works from msysgit also!]

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

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

**Please note** that gitolite depends heavily on proper ssh setup and pubkey
based access.  Sadly, most people don't know ssh as well as they think they
do.  To make matters worse, ssh problems in gitolite don't always look like
ssh problems.  Please read about [ssh troubleshooting][doc6] if you have *any*
kind of trouble installing gitolite!

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

In this document:

  * install methods
  * user install
      * typical example run
      * advantages over the older install methods
      * disadvantages
      * upgrades
      * other notes
  * system install / user setup
      * multiple gitolite instances
  * next steps
  * appendix A: server and client requirements for user install
      * server
      * install workstation
      * admin workstation(s)
  * appendix B: uninstalling gitolite
  * appendix C: NOTE TO PACKAGE MAINTAINERS

----

### install methods

There are 2 ways to install gitolite: The **user-install** mode was the
traditional way, and is used when *any* of the following is true:

  * you don't have root on your "server" (some types of hosting setups, many
    corporate paranoia setups ;-)
  * your server distro does not have gitolite in its package repositories
  * your server distro's package repositories have an old version of gitolite
  * you want to stay current with the latest gitolite versions
  * your server is not Linux (maybe AIX, or Solaris, etc.)

The "user install" section describes this method.

The **system-install followed by user-setup** mode is used when you (or
someone who has root) has installed an RPM or DEB of gitolite and you intend
to use that version.  [Update 2010-04-27: there is now a script called
`gl-system-install` that helps you do a system-install if your distribution
does not yet have a package for gitolite; details below].

The "system install / user setup" section describes this method.

----

### user install

The `gl-easy-install` script makes installing very easy for this case.  **This
script will setup everything on the server, but you have to run it on your
workstation, NOT on the server!**

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`.  If you do
        not have `ssh-copy-id`, read doc/3-faq-tips-etc.mkd and look for
        `ssh-copy-id` in that file for instructions
  * you have a clone or an archive of gitolite somewhere on your workstation
      * if you don't have one, just run `git clone git://github.com/sitaramc/gitolite`
  * your workstation has bash (even msysgit bash will do)

Once you have all this, 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`.

A detailed transcript of an install done using this method can be found in
[doc/7-install-transcript.mkd][7it].

[7it]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd

#### 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

#### 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.

----

### system install / user setup

(Note: other than getting a public key from the admin's workstation,
everything in this mode of install happens on the server).

In this mode, the software is first installed system-wide, then the user runs
a command to set up the hosting, supplying a public key.

The root user can **install the software system-wide**, using either a package
(rpm, deb, etc.), or by using the `gl-system-install` script.  (Run the script
without any arguments for a brief usage message.  If that's not clear enough,
read Appendix C below for details.)

A normal user can then **set up the hosting** by running a command like this:

    gl-setup adminname.pub

where adminname.pub is a copy of a public key from that user's workstation.

The first time this is run, it will create a "gitolite-admin" repo and
populate it with the right configuration for whoever has the corresponding
private key to clone and push it.  In other words, that person is the
administrator for this particular gitolite instance.

If your system administrator upgrades gitolite itself, things will usually
just work without any change; you should not have to do anything special.
However, some new features may require additional settings in your
`~/.gitolite.rc` file.

Finally, in the rare case that you managed to lose your keys to the admin repo
and want to supply a new pubkey, you can use this command to replace any such
key.  Could be useful in an emergency -- just get your new "yourname.pub" to
the server and run the same command as above.

**IMPORTANT**: there are two variables in the `~/.gitolite.rc` file:
`$GL_PACKAGE_CONF` and `$GL_PACKAGE_HOOKS`.  If you remove or change either of
them, expect trouble :-)

#### multiple gitolite instances

With this mode of install, 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.

----

### next steps

If you installed it using "gl-easy-install", the last message produced by that
script should tell you how to add users, repos, etc.  In any case, you will
find more details in [doc/2-admin.mkd][admin].

----

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

### appendix A: server and client requirements for user install

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, but it has to be some sort of Unix (not Windows).

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)

#### install workstation

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

This script is heavily dependent on bash, so you need a machine with a bash
shell.  Even the bash that comes with msysgit is fine, if you don't have a
Linux box handy.

If you have neither Linux nor Windows+msysgit, you still have a few
alternatives:

  * use a different userid on the same server (assuming it has bash)
  * use the same userid on the same server (same assumption)
  * 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.  You'll normally do it
from the same machine you used to install gitolite, but it doesn't have to be
the same one, as long as your pubkey has been added and permissions given to
allow you to push to the gitolite-admin repo.

<a name="uninstall"></a>

### appendix B: uninstalling gitolite

Sometimes you might find gitolite is overkill -- you have only one user
(yourself) pushing maybe.  Or maybe gitolite is just not enough -- you want a
web-based front end that users can use to manage their keys themselves, etc.,
in which case you'd probably switch to [github][g1], [girocco][g2],
[indefero][g3] or [gitorious][g4].  [Gerrit][g5] is quite nice too, if you
want collaborative code review there's nothing like it.  Either way, you'd
like to uninstall gitolite.

[g1]: http://github.com
[g2]: http://repo.or.cz/w/girocco.git
[g3]: http://www.indefero.net/
[g4]: http://gitorious.com/
[g5]: http://code.google.com/p/gerrit/

Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
not, adjust accordingly):

**server side tasks**

  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
    gitolite end` markers and all the lines between them.  This will prevent
    any of your users from attempting a push while you are doing this.

    If you are the only user, and/or *need* one or more of those keys to
    continue to access this account (like if one of them is your laptop or
    your home desktop etc.) then instead of deleting the line you can just
    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".

  * Now remove (or move aside or rename to something else if you're paranoid)
    the following files and directories.

        ~/.gitolite
        ~/.gitolite.rc
        ~/repositories/gitolite-admin.git

  * You can remove all of `~/repositories` if you have not really started
    using gitolite properly yet; that's your choice.

    If you *do* need to preserve the other repos and continue to use them,
    remove all the `update` hooks that git installs on each repository.  The
    easiest way is:

        find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f

    but you can do it manually if you want to be careful.

**client side tasks**

  * Any remote users that still have access must update their clone's remote
    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
    actual path used, in order for the remote to still work.  This is because
    you'll now be accessing it through plain ssh, which means you have to give
    it the full path.

  * Finally, you as the gitolite admin will probably have a host stanza for
    "gitolite" in your *client*'s `~/.ssh/config`.  Find and delete lines that
    look like this:

        host gitolite
            user git
            hostname your.server
            port 22
            identityfile ~/.ssh/your-gitolite-admin-username

### appendix C: NOTE TO PACKAGE MAINTAINERS

Here's how you'd package gitolite.  In the following description, location "X"
can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
"Y" can be perhaps `/usr/share/gitolite/hooks`.  It's upto your distro
policies where they are.

**Step 1**: Clone the gitolite repo and run the make command inside the clone

    git clone git://github.com/sitaramc/gitolite.git
    cd gitolite
    make pu.tar     # or "make master.tar" or "make v1.2.tar" etc

Then you explode the tar file in some temporary location.

*Alternatively, you can `git checkout` the tag or branch you want, and run
this command in the clone directly*:

    git describe --tags --long > conf/VERSION

**Step 2**: Now make the following changes (no trailing slashes in the
location values please):

  * `src/gl-setup` should have the following line:

        GL_PACKAGE_CONF="X"

  * `conf/example.gitolite.rc` should have the following lines:

        $GL_PACKAGE_CONF="X";
        $GL_PACKAGE_HOOKS="Y";

  * delete `src/gl-easy-install`; that script is meant for a totally different
    mode of installation and does *not* play well in this mode :-)

**Step 3**: Move (or arrange to move) the files to their proper locations as
given below:

  * everything in "src" goes somewhere on the PATH
  * everything in "conf" goes to location "X"
  * everything in "hooks" goes to location "Y"

**Step 4**: There is no step 4.  Unless you count telling your users to run
`gl-setup` as a step :)

On the initial install (urpmi, yum install, or apt-get install), you could
also choose to setup a userid called "gitolite", and run "gl-setup" as that
user; however I do not know how you would come up with the initial pubkey that
is needed.  Anyway, the point is that the "gitolite" user is no more special
than any other in terms of hosting gitolite.  Any user can host gitolite on
his userid by just running "gl-setup".

When you upgrade, just overwrite all the files; it'll all just work.  In fact,
other than the initial "gl-setup" run, the only time a gitolite hosting user
has to actually do anything is to edit their own `~/.gitolite.rc` file if they
want to enable or disable specific features.