gitolite/doc/1-INSTALL.mkd

# gitolite installatation

In this document:

  * <a href="#_please_read_this_first">please read this first</a>
      * <a href="#_important_notes">important notes</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="#_installation_and_setup">installation and setup</a>
      * <a href="#_install_methods_and_deciding_which_one_to_use">install methods and deciding which one to use</a>
      * <a href="#_conventions_used">conventions used</a>
      * <a href="#_package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
      * <a href="#_root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
      * <a href="#_non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
      * <a href="#_from_client_method_install_from_the_client_to_the_server">(from-client method) install from the client to the server</a>
  * <a href="#_URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</a>
  * <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
      * <a href="#_package_method_and_root_method">package method and root method</a>
      * <a href="#_from_client_method">from-client method</a>
  * <a href="#_upgrading">upgrading</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 name="_please_read_this_first"></a>

### please read this first

<a name="_important_notes"></a>

#### important notes

Please make sure you understand the following points first.

  * gitolite runs as a single user on a server, and is invoked via ssh.  Thus,
    every user 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/ssh-troubleshooting.mkd][doc6] 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.

A gitolite setup has:

  * a server
  * a "hosting user" on the server -- the userid under which gitolite runs.
    (Side note: there is *usually* only one hosting user per server (machine),
    but gitolite makes it trivial to have as many as you want.  Advanced users
    can look [here][mgs]!)
  * an "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

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

#### requirements

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

##### client/workstation

  * 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="_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.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="_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 indefero using the
'git clone' command:

    git clone git://github.com/sitaramc/gitolite.git
            # (OR)
    git clone git://sitaramc.indefero.net/sitaramc/gitolite.git

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

### installation and setup

<a name="methods"></a>

<a name="_install_methods_and_deciding_which_one_to_use"></a>

#### install methods and deciding which one to use

Gitolite has 4 install methods:

  * **package method** if you have a gitolite RPM or a DEB available
  * **root method** if you have root access to the server, and you plan to
    have multiple "hosting users" on it
  * **non-root method** if you don't have root access to the server, but you
    do have at least one account with a password
  * **from-client method** if you are not comfortable with public keys and
    server side commands

Here's how you install using these 3 methods.  Future upgrades are equally
easy -- the steps required for upgrading are marked "(U)".

<a name="_conventions_used"></a>

#### 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="_package_method_directly_on_the_server_using_RPM_DEB"></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/YourName.pub`.

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

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

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

<a name="_root_method_directly_on_the_server_manually_with_root_access"></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/YourName.pub`.

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

        cd $HOME
        git clone git://github.com/sitaramc/gitolite gitolite-source
        cd gitolite-source
        # now checkout whatever branch you want; for early adopters I suggest
        # "pu", as in "git checkout -t origin/pu" for recent gits
        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 `which gl-setup`.  This
    should respond with `/usr/local/bin/gl-setup`.  If this is not what you
    get, you have some `$PATH` issues.  Make sure `/usr/local/bin` is in the
    `$PATH` for the git user, and that no prior components of the path contain
    another copy of `gl-setup`.  You *must* run the one in the directory that
    is the first argument of `gl-system-install` above.

  * now run `gl-setup /tmp/YourName.pub`.

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

<a name="_non_root_method_directly_on_the_server_manually_without_root_access"></a>

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

**WARNING: if you want to use this method your shell access to the git account
on the server should be via `su - git` from some other userid.  If that is not
possible, you should (a) know the password in case you screw up the keys AND
(b) know how to force ssh to ask for a password if required, AND (c) know how
to handle multiple keys in ssh.**

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

  * if `$HOME/bin` is not on the default PATH, fiddle with your `.bashrc` or
    `.bash_profile` or similar files and add it somehow.

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

        cd $HOME
        git clone git://github.com/sitaramc/gitolite gitolite-source
        # now checkout whatever branch you want; for early adopters I suggest
        # "pu", as in "git checkout -t origin/pu" for recent gits
        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/YourName.pub`.

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

<a name="fc"></a>

<a name="_from_client_method_install_from_the_client_to_the_server"></a>

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

The advantage of this method is that it forces you to solve the ssh pubkey
problem **before** attempting to install.  It works best if you have dedicated
userids, one on the server for installing gitolite, and one on the client for
administering it.

The disadvantage is that the admin user ends up with [two keys][twokeys] --
one for shell access (that he started with) and one for gitolite access (which
the script creates if needed).

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.

This method is verbosely documented in this [transcript][], including
*outputs* of the commands concerned.

<a name="_URLs_for_gitolite_managed_repos"></a>

### URLs for gitolite-managed repos

The URL for normal users (i.e., users other than the admin) is always of the
form "git@server:reponame".  So, for instance, `git clone git@server:testing`
gets any valid user a copy of the "testing" repo.

In the first 3 install methods, the admin user will also use the same URL
format, like `git clone git@server:gitolite-admin`.

However, in the fourth ("from-client") method, the admin user needs a
different URL (`gitolite:reponame`) to gain access to the gitolite
repositories.  Check [here][twokeys] for why.

<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][gash] 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.

<a name="_package_method_and_root_method"></a>

#### package method and root method

With the first two methods of installation, it's trivial to create multiple
gitolite instances.  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="_from_client_method"></a>

#### from-client method

You can do the same thing using this method also, but it's a little more
cumbersome.  Instead, I'll describe a different scenario -- one "admin"
installing gitolite on different servers.  You can adapt that to the above
case quite easily if you wish.

Thanks to Matt Perzel, the easy-install command now takes an optional 4th
parameter, which is the "nickname" of the gitolite server.  It gets defined in
`~/.ssh/config`, and if not used it defaults to "gitolite".

So if you used the following command to install gitolite to 2 different
servers:

    ./src/gl-easy-install -q git my.1st.git.server admin_user1 gitolite_server_1
    ./src/gl-easy-install -q git my.2nd.git.server admin_user1 gitolite_server_2

you will find that `~/gitolite_server_1-admin` and `~/gitolite_server_2-admin`
have been created as respective clones.  Or you can re-clone elsewhere:

    cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git
    cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git

<a name="_upgrading"></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!

If you've added any new hooks, please also run the next step (`gl-setup`)
also.

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

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

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

----

[doc6]: 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
[gash]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html