gitolite/doc/install.mkd

F=install 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").

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

F=rpmdeb 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. (The name of this file determines your gitolite username, so if you leave it as id_rsa.pub, your gitolite username will be id_rsa, which may not be what you want).

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

Note: please see appendix d for command line options for [gl-setup][].

On your workstation:

git clone gitolite@server:gitolite-admin

F=nonroot 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, 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. (The name of this file determines your gitolite username, so if you leave it as id_rsa.pub, your gitolite username will be id_rsa, which may not be what you want).

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
gitolite/src/gl-system-install
# defaults to being the same as:
# gitolite/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

Note: please see appendix d for command line options for [gl-setup][].

On your workstation:

git clone git@server:gitolite-admin

F=upgrfromclient 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.

F=root root method

On your workstation:

• copy your ~/.ssh/id_rsa.pub file to /tmp/YourName.pub on the server. (The name of this file determines your gitolite username, so if you leave it as id_rsa.pub, your gitolite username will be id_rsa, which may not be what you want).

On your server, as root:

git clone git://github.com/sitaramc/gitolite
gitolite/src/gl-system-install
# defaults to being the same as:
# gitolite/src/gl-system-install /usr/local/bin /var/gitolite/conf /var/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

Note: please see appendix d for command line options for [gl-setup][].

On your workstation:

git clone git@server:gitolite-admin

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

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.

#insttrouble install trouble?

If you run into trouble, please read the following sections.

common install problems

The most common problem is usually 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][gl_ssh] and the [ssh troubleshooting][sts] 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 a][instpath] 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.

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

F=instbg helpful background information

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

• 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 the [ssh troubleshooting][sts] document 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.

F=instrequire requirements

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

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 later
  • 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 5.8 or later
• 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").

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.

F=getgl_ 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/

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.

#instappendices_ appendixes

The following sections have some miscellaneous information that does not cleanly to fit anywhere else.

#instpath appendix a: 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 gitolite/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 gitolite/src/gl-system-install command (or /usr/local/bin by default)
• non-root method: the first argument to the gitolite/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.

#clean appendix b: cleaning out a botched install

When people have trouble installing gitolite, they often try to change a bunch of things manually on the server. Or sometimes they'll upgrade from one install method to another without checking some things over properly. Or they'll follow instructions meant for a much newer version of gitolite and make a royal mess of the whole thing.

Here's how to clean up, without losing your actual repositories.

All this is on the server. Note that the instructions are so long because they're generic enough to fit any situation.

• Clean out the existing install

  • edit ~/.ssh/authorized_keys and delete all lines between # gitolite start and # gitolite end inclusive.

  • look in ~/.gitolite.rc for 2 variables starting with GL_PACKAGE_. If they are defined (and not just commented out), you need to clean out all gitolite related files and directories from those two paths.

    Just for reference, the defaults for a non-root install are 'conf' and 'hooks' in $HOME/share/gitolite, while for an RPM/DEB or root install they should be in /var/gitolite/ or some such.

    If those variables don't exist or are commented out, ignore this step.

  • look in $PATH for any gitolite programs and delete them also. A good way to hunt them down is which gl-auth-command, and in the path you find, delete all "gl-*" programs (perhaps after checking the list, if the path you find happens to be /usr/bin or such!!)

    Repeat this step until there are no more. I know of people who mixed different install methods and had two, or even three, versions lying around.

  • make some temp directory (say "old"), and move the following files/directories into it: ~/.gitolite, ~/.gitolite.rc and ~/repositories/gitolite-admin.git. If there's nothing you need to salvage from them you can delete them too.

  • if you used an RPM/DEB install, remove the package also.

• Now install a fresh copy of gitolite using whatever method you prefer. (If you used a different method earlier and did not clean things out properly per the instructions given above, expect trouble).

• You now have a brand new "rc" file. If your old rc file had any non-default settings you should manually pull them in to the new one. However, do NOT change the two variables starting with GL_PACKAGE_ in the new rc file; even if the old one had something different leave them alone.

• You also have a brand new gitolite-admin repo. Clone this to your workstation, then use the saved copy of the old admin repo to salvage whatever you need (entire revision history, or just the conf/key files, whatever floats your boat).

  Once you've got your admin repo looking how you want it, including 'repo' statements for all your existing repos, just add/commit/push it.

• Go back to the server and run gl-setup once again (no arguments needed).

That should do it.

#uninstall_ appendix c: uninstalling gitolite completely

To uninstall gitolite completely, first follow the "clean out..." steps in the previous section.

If you have not really started using gitolite properly yet, you can remove all of ~/repositories also and be done.

But if you do need to preserve the other repos and wish to continue to use them, remove all the update hooks that gitolite installs in 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.

#gl-setup appendix d: command line options for gl-setup

After gl-system-install (or the RPM/DEB) have installed the code, gl-setup sets up the actual gitolite instance. (Gitolite in [pictures][] may help explain this better.)

In ssh mode, gl-setup expects a pubkey filename the first time it is run, and will complain if you don't supply it. On subsequent runs it is optional; you only need to supply it if you want to quickly and easily change the admin's (or indeed anyone's!) pubkey without going through all the steps that [gl-admin-push][adminpush] requires.

In http mode, gl-setup expects an "admin name" the first time it is run. On subsequent runs, arguments are ignored.

gl-setup accepts the following command line options, which must appear before the pubkey filename/admin name:

• -q -- quiet mode; suppress the editor that pops up to allow you to change the rc file the first time. Meaningless/ignored on subseqent runs.
• -q -q -- extra quiet mode; suppress the editor as well as the sshkeys-lint check at the end of the run. Old-timers who know ssh so well that they still use protocol 1 keys must use this mode, because sshkeys-lint will barf on them. Equivalent to -q in http mode.