gitolite/doc/1-INSTALL.mkd

# gitolite installation

(Note: git servers are most commonly used with ssh URLs, and this document
describes installing gitolite to support such usage.  If your users prefer
http URLs, read [this][http] to install gitolite to support "smart http").

In this document:

  * <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
      * <a href="#_side_note_upgrading">(side note) upgrading</a>
      * <a href="#_package_method">package method</a>
      * <a href="#_non_root_method">non-root method</a>
          * <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a>
      * <a href="#_root_method">root method</a>
  * <a href="#_troubleshooting">troubleshooting</a>
  * <a href="#_important_points_to_note">important points to note</a>
  * <a href="#_naming_conventions_used">naming conventions used</a>
  * <a href="#_requirements">requirements</a>
      * <a href="#_client_workstation">client/workstation</a>
      * <a href="#_server">server</a>
      * <a href="#_technical_skills">technical skills</a>
  * <a href="#_getting_the_gitolite_software">getting the gitolite software</a>
      * <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
  * <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
  * <a href="#_uninstalling">uninstalling</a>
      * <a href="#_cleaning_out_a_botched_install">cleaning out a botched install</a>
      * <a href="#_uninstalling_gitolite_completely">uninstalling gitolite completely</a>
  * <a href="#_appendix_a_the_from_client_method">appendix a: the from-client method</a>
  * <a href="#_appendix_b_PATH_issues_for_gl_setup">appendix b: PATH issues for gl-setup</a>

----

<a name="_installing_and_upgrading_gitolite"></a>

### installing and upgrading gitolite

This section tells you how to install/upgrade gitolite, without too much
background.  Later sections have more details and troubleshooting info; please
read them before asking for help if you have problems.

A bare minimum gitolite setup has:

  * a server
  * a "hosting user" on the server (a real Unix userid; we use "git" in this
    document, although RPM/DEB installs use "gitolite")
  * a virtual "admin user" -- the user who sets up gitolite and configures it
  * the admin user's client or workstation, from which he does all his work

Gitolite allows 3 methods of install.  The two most common are (1) the
**package method**, used if you have a gitolite RPM or a DEB available, and
(2) the **non-root method** which is the preferred manual install mode.  Less
commonly used is (3) the **root method**, which is useful if you plan to have
multiple "hosting users" on the same server.

These install methods are described in detail below.  (*Once you finish the
install, read the [admin document][admin] to administer your gitolite
installation*).

<a name="_side_note_upgrading"></a>

#### (side note) upgrading

Upgrading is easy; you just re-run some of the same commands used for install.
These commands are clearly noted in the install instructions below.

However, if you've added any new hooks, you must also run the next step (the
`gl-setup` command), although this time you don't need to supply a pubkey
filename as an argument.

[admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
[http]: http://sitaramc.github.com/gitolite/doc/http-backend.html

<a name="_package_method"></a>

#### package method

(Unlike in the rest of this document, we use "gitolite" as the "hosting user"
instead of "git" here, because that is the user that both the Fedora and
Debian packages create.  Your distro/OS may vary.)

On your *workstation*:

  * copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server

On your *server*, as *root*:

    yum install gitolite    # or 'apt-get install gitolite', or whatever
    # this is the only step you need to repeat when upgrading gitolite

    # current RPM/DEB create a hosting user called "gitolite"
    su - gitolite

    # (now as gitolite)
    gl-setup /tmp/YourName.pub

On your *workstation*:

    git clone gitolite@server:gitolite-admin

<a name="_non_root_method"></a>

#### non-root method

**IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method
you had better know the password to the hosting user on the server, or be able
to `su` to it from root, just in case you manage to lock yourself out by
messing with the keys.

**NOTE**: This method is exhaustively described in the [tutorial][tut], if
you're interested.  (That tutorial is by someone else but it's nice enough for
me to link it here).

On your *workstation*:

  * copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server

On your *server*, as *git* (the "hosting user"), first check if `$HOME/bin` is
on the default PATH.  If not, fiddle with the `.bashrc` or `.bash_profile` or
similar files and add it somehow.  Then:

    git clone git://github.com/sitaramc/gitolite
    cd gitolite
    src/gl-system-install
    # defaults to being the same as:
    # src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks

    # to upgrade gitolite, repeat the above commands.  Make sure you use the
    # same arguments for the last command each time.

    gl-setup /tmp/YourName.pub

On your *workstation*:

    git clone git@server:gitolite-admin

<a name="_upgrading_from_from_client_method_to_non_root_method"></a>

##### upgrading from from-client method to non-root method

Since the from-client method is now deprecated for reasons explained
elsewhere, some folks may want to do their next upgrade using the non-root
method.

There are many, many ways to skin this cat; here's one way:

  * follow non-root install but stop after the gl-system-install step

  * temporarily rename your `~/.gitolite.rc` file to something else

  * now run the gl-setup step

    (background: this will create a default rc file with default values, but
    crucially, it will give you the correct values for two very critical
    variables that are not used in the old from-client install method)

  * edit `~/.gitolite.rc` and bring in any non-default settings you may have
    had in your old rc file.

    When you're done, the only difference between your old and current rc
    files should be that the `$GL_PACKAGE_CONF` and the `$GL_PACKAGE_HOOKS`
    variables are no longer commented out and look somewhat like this:

        $GL_PACKAGE_CONF = '/home/git/share/gitolite/conf';
        $GL_PACKAGE_HOOKS = '/home/git/share/gitolite/hooks';

    Now save the file.

<a name="_root_method"></a>

#### root method

On your *workstation*:

  * copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server

On your *server*, as *root*:

    git clone git://github.com/sitaramc/gitolite
    cd gitolite
    src/gl-system-install
    # defaults to being the same as:
    # src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks

    # to upgrade gitolite, repeat the above commands.  Make sure you use the
    # same arguments for the last command each time.

    # now create your "hosting user" ('git' in our examples) using whatever
    # command your distro expects you to use

    # switch to the hosting user
    su - git

    # (now as git)
    gl-setup /tmp/YourName.pub

On your *workstation*:

    git clone git@server:gitolite-admin

----

<a name="_troubleshooting"></a>

### troubleshooting

  * The most common thing that goes wrong in an install is something to do
    with ssh.

    Here are three facts of ssh:

      * ssh is a pain
      * most people don't know ssh well enough
      * even people who think they do, don't

    Please read how [gitolite uses ssh][glgas] and the [ssh
    troubleshooting][glsts] documents before asking for help.

  * If you've tried multiple methods of install, you may have multiple copies
    of the sources lying around.  This could be a problem; see appendix b for
    how to detect and deal with this.

If none of this works read the rest of this document, understand it as much as
you can, then ask for help.

<a name="_important_points_to_note"></a>

### important points to note

  * gitolite runs as a single (real) user on a server, and is invoked via ssh.
    Traditionally, this "hosting user" is "git", and thus all git URLs start
    with `ssh://git@server` (or the equivalent shorter form `git@server:`).

      * RPM/DEB create and use "gitolite" as the hosting user

      * there is *usually* only one hosting user per server (machine), but
        gitolite makes it trivial to have as many as you want.  In fact, every
        user on the server is a potential hosting user.  Advanced users can
        look [here][mgs]!)

  * using this single user and sshd (or httpd) authentication, gitolite allows
    you to create any number of "virtual" users.  Virtual user names only mean
    something to gitolite, and they need not be the same as any real userid on
    the server or any of the clients accessing it.

      * the first such virtual user is the "admin user", created during the
        install sequence.

  * 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/ssh-troubleshooting.mkd][glsts] for help.

  * gitolite **does NOT** like it when people with shell access to the server
    fiddle with files and directories it controls.

    Apparently this was not obvious to some people.

It is possible to have the server and the client be the same machine, and even
the admin user be also the hosting user, (i.e., `sitaram@server` can install
and administer a gitolite setup running under `sitaram@server`, a situation
that is common with some hosting services).  It's actually fairly easy and
**safe** to do, **as long as you have password access to the server** for
emergency use.  However, I will not be documenting it because (a) if you know
ssh you'll know how to extrapolate my instructions to do this and (b) if you
don't know ssh it'll be a nightmare to support you.

<a name="_naming_conventions_used"></a>

### naming conventions used

Throughout the documentation, we use "YourName" as the admin user, and his
workstation is called "client".  The hosting user is "git", and the server is
called "server".  **Please substitute your values as needed**.

**If you're using DEB or RPM**, the installer creates a user called
"gitolite", so substitute that for "git" anywhere in the docs where the
"hosting user" is mentioned as "git".

Also, we often say "the rc file".  This means `~/.gitolite.rc` on the server.
And when we say the "access control rules", or "conf file", or "config file",
we mean `conf/gitolite.conf` on your gitolite-admin clone.

<a name="_requirements"></a>

### requirements

<a name="_client_workstation"></a>

#### client/workstation

  * git version 1.6.6 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="_server"></a>

#### server

  * 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.6 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
    (probably optional if you're using the http backend)
  * a Unix userid to be the hosting user, usually "git" but it can be any
    user, even your own normal one.  (If you're using an RPM/DEB the install
    probably created one called "gitolite").

<a name="_technical_skills"></a>

#### technical skills

  * if you're installing gitolite, you're a "system admin", like it or not.
    Ssh is therefore a necessary skill.  Please take the time to learn at
    least enough to get passwordless access working.

  * you also need to be somewhat familiar with git itself.  You cannot
    administer a whole bunch of git repositories if you don't know the basics
    of git.

  * some familiarity with Unix and shells is probably required

  * regular expressions are a big part of gitolite in many places but
    familiarity is not necessary to do basic access control.

<a name="_getting_the_gitolite_software"></a>

### getting the gitolite software

You can get the latest version of gitolite from github or google code using
the 'git clone' command:

    git clone git://github.com/sitaramc/gitolite.git
            # (OR)
    git clone https://code.google.com/p/gitolite/

<a name="_getting_a_tar_file_from_a_clone"></a>

#### getting a tar file from a clone

If you are on an internal network and cannot clone the gitolite repo, you can
do the clone on some other machine and create a tar file from it to use on the
internal network.  Here's how:

    git clone git://github.com/sitaramc/gitolite.git
            # (OR)
    git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
    cd gitolite
    make master.tar
    # or maybe "make pu.tar"

Please use the make command as shown, not a plain "git archive", because the
Makefile adds a file called `.GITOLITE-VERSION` that will help you identify
which version you are using.

--------------------------------------------------------

<a name="_special_cases_multiple_gitolite_servers"></a>

### special cases -- multiple gitolite servers

(**Advanced users only, please!**)

There is no gitolite "daemon"; it gets invoked via sshd which calls
"gl-auth-command" via the "command=" option in the authkeys file (see
[gitolite and ssh][glgas] for more).

If you think about it, this means every real (unix) user on the system can
host her own gitolite server!

Of course, one doesn't normally do that in the interests of sanity, but let's
say you want to create one gitolite instance for each department on some
company-wide mega-server.

Using one of the first two methods of installation, it's trivial to create
multiple gitolite instances -- essentially any Unix user can then run
`gl-setup` with some pubkey filename as an argument and that user is now a
gitolite host.

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="_uninstalling"></a>

### uninstalling

<a name="_cleaning_out_a_botched_install"></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`
      * depending on which install method you used, you may also need to clean
        out all gitolite files from `/usr/local/bin` or `$HOME/bin`, and then
        delete `/var/gitolite/conf` and `/var/gitolite/hooks` or
        `$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks`

<a name="_uninstalling_gitolite_completely"></a>

#### uninstalling gitolite completely

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

----

<a name="_appendix_a_the_from_client_method"></a>

### appendix a: the from-client method

This method was the only install mode at one time, but the newer ones are much
better, so it's kinda legacy now (Wow -- fancy something being "legacy" in
software that is not yet 2 years old!)

The only advantage of this method is that it forces you to solve the ssh
pubkey problem **before** attempting to install.

But I'm not sure if that is worth the hassle of supporting an install scheme
that ends up with the admin user having [two keys][twokeys], though.  And this
in turn forces the admin to use a different URL to access 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.

All in all, I plan to obsolete it eventually.  Meanwhile, it is verbosely
documented in this [transcript][], including *outputs* of the commands
concerned.

<a name="_appendix_b_PATH_issues_for_gl_setup"></a>

### appendix b: PATH issues for gl-setup

If you've tried multiple methods of install, you may have multiple copies of
the sources lying around, and when you ran `gl-setup` it picked up the wrong
one.  This might also happen if the directory you supplied as the first
argument to `src/gl-system-install` is not even in the `$PATH`.

Run `su - git` then `which gl-setup` to see which it picked up.  This is what
it should be for each method:

  * RPM/DEB method: probably `/usr/bin`
  * root method: the first argument to the `src/gl-system-install` command (or
    `/usr/local/bin` by default)
  * non-root method: the first argument to the `src/gl-system-install` command
    (or `$HOME/bin` by default)

If this is not what you get, remove the partially installed or extraneous
sources, if any, and try again.  Or fix your `$PATH`.

One situation that is not easy to solve is if the system admin installed
gitolite using the RPM/DEB or root methods, and you want to install a later
version using the non-root method.  Since `/usr/bin` and `/usr/local/bin` are
usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
Good luck.

[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
[doc9unin]: http://sitaramc.github.com/gitolite/doc/uninstall.html
[twokeys]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#twokeys
[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers
[glgas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial