gitolite/doc/http.mkd

# how to setup gitolite to use smart http mode

**Note**: "smart http" refers to the feature that came with git 1.6.6, late
2009 or so.  The base documentation for this is `man git-http-backend`.  Do
**NOT** read `Documentation/howto/setup-git-server-over-http.txt` and think
that is the same or even relevant -- that is from 2006 and is quite different
(and arguably obsolete).

## WARNINGS and important notes

  * Please read [authentication versus authorisation][auth] first, and make
    sure you understand what is gitolite's responsibility and what isn't.

  * I have tested this only on stock Fedora 16; YDMV.

## assumptions:

  * Apache 2.x and git installed.
  * Httpd runs under the "apache" userid; adjust instructions below if not.
  * Similarly for "/var/www" and other file names/locations.

## instructions

The detailed instructions I used to have in g2 have now been replaced by a
script called `t/smart-http.root-setup`.  **Do NOT run this script as is -- it
is actually meant for my testing setup and deletes stuff**.  However, it does
provide an excellent (and working!) narration of what you need to do to
install gitolite in smart http mode.

Make a copy of the script, go through it carefully, (possibly removing lines
that delete files etc.), change values per your system, and only then run it.

<font color="gray">Note that the `GIT_PROJECT_ROOT` variable (see "man
git-http-backend") is no longer optional.  Make sure you set it to some place
outside apache's `DOCUMENT_ROOT`.</font>

## Making repositories available to both ssh and http mode clients

This section has been contributed by Thomas Hager (duke at sigsegv dot at).

Assumptions:

  * Apache 2.x with CGI and Suexec support installed.
  * Git and Gitolite installed with user "git" and group "git", and pubkey SSH
    access configured and working.
  * Git plumbing installed to /usr/libexec/git-core
  * Gitolite base located at /opt/git
  * Apache `DOCUMENT_ROOT` set to /var/www
  * Apache runs with user www and group www

Please adjust the instructions below to reflect your setup (users and paths).

Edit your .gitolite.rc and add

    $ENV{GIT_HTTP_BACKEND} = "/usr/libexec/git-core/git-http-backend";
    $ENV{PATH} .= ":/opt/git/bin";

at the very top (as described in `t/smart-http.root-setup`).

Next, check which document root your Apache's suexec accepts:

    # suexec -V
     -D AP_DOC_ROOT="/var/www"
     -D AP_GID_MIN=100
     -D AP_HTTPD_USER="www"
     -D AP_LOG_EXEC="/var/log/apache/suexec.log"
     -D AP_SAFE_PATH="/usr/local/bin:/usr/bin:/bin"
     -D AP_UID_MIN=100
     -D AP_USERDIR_SUFFIX="public_html"

We're interested in `AP_DOC_ROOT`, which is set to `/var/www` in our case.

Create a `bin` and a `git` directory in `AP_DOC_ROOT`:

    install -d -m 0755 -o git -g git /var/www/bin
    install -d -m 0755 -o www -g www /var/www/git

`/var/www/git` is just a dummy directory used as Apache's document root (see below).

Next, create a shell script inside `/var/www/bin` named `gitolite-suexec-wrapper.sh`,
with mode **0700** and owned by user and group **git**. Add the following content:

    #!/bin/bash
    #
    # Suexec wrapper for gitolite-shell
    #

    export GIT_PROJECT_ROOT="/opt/git/repositories"
    export GITOLITE_HTTP_HOME="/opt/git"

    exec ${GITOLITE_HTTP_HOME}/gitolite-source/src/gitolite-shell

Edit your Apache's config to add http pull/push support, preferably in
a dedicated `VirtualHost` section:

    <VirtualHost *:80>
        ServerName        git.example.com
        ServerAlias       git
        ServerAdmin       you@example.com

        DocumentRoot /var/www/git
        <Directory /var/www/git>
            Options       None
            AllowOverride none
            Order         allow,deny
            Allow         from all
        </Directory>

        SuexecUserGroup git git
        ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper.sh/
        ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper.sh/

        <Location /git>
            AuthType Basic
            AuthName "Git Access"
            Require valid-user
            AuthUserFile /etc/apache/git.passwd
        </Location>
    </VirtualHost>

This Apache config is just an example, you probably should adapt the authentication
section and use https instead of http!

Finally, add an `R = daemon` access rule to all repositories you want to
make available via http.

## usage

### client side

Git URLs look like `http://user:password@server/git/reponame.git`.

The custom commands, like "info", "expand" should be handled as follows.  The
command name will come just after the `/git/`, followed by a `?`, followed by
the arguments, with `+` representing a space.  Here are some examples:

    # ssh git@server info
    curl http://user:password@server/git/info
    # ssh git@server info repopatt
    curl http://user:password@server/git/info?repopatt
    # ssh git@server info repopatt user1 user2
    curl http://user:password@server/git/info?repopatt+user1+user2

With a few nice shell aliases, you won't even notice the horrible convolutions
here ;-)  See t/smart-http for a couple of useful ones.

### server side

The 'gitolite' command (for example, 'gitolite compile', 'gitolite query-rc',
and so on) *can* be run on the server, but it's not straightforward.  Assuming
you installed exactly as given in this document, you should

  * get a shell by using, say, `su -s /bin/bash - apache`
  * run `export HOME=$HOME/gitolite-home`
  * run `export PATH=$PATH:$HOME/bin`

and *then* you can run `gitolite <subcommand>`