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

In this document:

  * <a href="#_WARNINGS_plus_stuff_I_need_help_with">WARNINGS, plus stuff I need help with</a>
  * <a href="#_additional_requirements">additional requirements</a>
  * <a href="#_detailed_instructions">detailed instructions</a>
      * <a href="#_install_gitolite_under_apache_">install gitolite under "apache"</a>
      * <a href="#_setup_apache">setup apache</a>
  * <a href="#_usage">usage</a>
  * <a href="#_allowing_anonymous_access">allowing anonymous access</a>

----

<a name="_WARNINGS_plus_stuff_I_need_help_with"></a>

### WARNINGS, plus stuff I need help with

  * I have NOT converted the test suite to use this mode.  Volunteers to
    convert it to http access are welcome :-)

  * I have no idea how to handle the password issue other than creating a
    `~/.netrc` file and making it `chmod 600`.  Anyway, http based access is
    inherently less secure than pubkeys so not much point worrying about it.

  * I have not tested any of the ancillary standalone programs (like
    gl-dont-panic) in this mode.  They're most likely going to crash and burn
    because `$HOME` is not defined or in the wrong place; manually set
    `HOME=$GITOLITE_HTTP_HOME` and hope for the best.  Luckily most of them
    have to do with sshkeys so this may not matter.  YMMV.

  * tested on stock Fedora 14; if you test on other environments please let me
    know how it worked out and if we need to adjust this document

  * tested https with dummy certs and `GIT_SSL_NO_VERIFY`; no reason why it
    shouldn't work on a proper setup with everything in place

  * have not tried making repos available to both ssh *and* http mode clients;
    (I'd guess it ought to work fine if the "apache" user was made login-able
    and given a proper $HOME and `~/.ssh/authorized_keys` and all that).  If
    anyone has the energy to try that please let me know how that went.

<a name="_additional_requirements"></a>

### additional requirements

  * requires `GIT_PROJECT_ROOT` (see "man git-http-backend" for what this is)
    set explicitly (i.e., it is no longer optional).  Please set it to some
    place outside apache's `DOCUMENT_ROOT`.

<a name="_detailed_instructions"></a>

### detailed instructions

I assume you've installed apache 2.x and git on the server.

I assume your httpd runs under the "apache" userid; adjust instructions below
if it does not.  Similarly for "/var/www" and other file names/locations.

<a name="_install_gitolite_under_apache_"></a>

#### install gitolite under "apache"

Follow the "non-root" method, but since you can't even "su - apache", make the
following variations when doing this as root:

  * `cd ~apache` first; this is `/var/www` on Fedora 14

  * do this in the shell

        mkdir gitolite-home
        export GITOLITE_HTTP_HOME
        GITOLITE_HTTP_HOME=/var/www/gitolite-home
        PATH=$PATH:$GITOLITE_HTTP_HOME/bin

  * now run the first 3 install steps for "non-root" method (clone, mkdir, and
    gl-system-install), but **substitute** `GITOLITE_HTTP_HOME` in place of
    `HOME` in the mkdir and gl-system-install steps.

    **Do NOT run the gl-setup step yet**.

        cd gitolite-home
        git clone /tmp/gitolite.git gitolite-source

        cd gitolite-source
        GHH=$GITOLITE_HTTP_HOME     # just for convenience in next 2 commands
        mkdir -p              $GHH/bin $GHH/share/gitolite/conf $GHH/share/gitolite/hooks
        src/gl-system-install $GHH/bin $GHH/share/gitolite/conf $GHH/share/gitolite/hooks

  * after the gl-system-install step, add these to the **top** of
    /var/www/gitolite-home/share/gitolite/conf/example.gitolite.rc

        $ENV{GIT_HTTP_BACKEND} = "/usr/libexec/git-core/git-http-backend";
            # or wherever you have that file; not NO trailing slash
        $ENV{PATH} .= ":$ENV{GITOLITE_HTTP_HOME}/bin";
            # note the ".=" here, not "="

  * run gl-setup with the name of your admin user

        gl-setup sitaram

  * IMPORTANT: fix up ownerships

        chown -R apache.apache $GITOLITE_HTTP_HOME

<a name="_setup_apache"></a>

#### setup apache

You will need to setup certain values in the httpd conf, as given in `man
git-http-backend`.  You can put all them into, for instance,
`/etc/httpd/conf.d/gitolite.conf` and apache [at least on Fedora 14] will pick
it up.  These are the values to use; note that these are somewhat different
from those in the manpage cited above, plus we have one extra variable:

    SetEnv GIT_PROJECT_ROOT /var/www/gitolite-home/repositories
    SetEnv GIT_HTTP_EXPORT_ALL
    ScriptAlias /git/ /var/www/gitolite-home/bin/gl-auth-command/
        # note trailing slash

    SetEnv GITOLITE_HTTP_HOME /var/www/gitolite-home

    <Location /git>
        AuthType Basic
        AuthName "Private Git Access"
        Require valid-user
        AuthUserFile /path/to/some/passwdfile
    </Location>

Now create/update the password file in `/path/to/some/passwdfile` using the
`htpasswd` command, and you're all done for the setup!

<a name="_usage"></a>

### usage

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

It gets even more interesting for the `setperms` command, which expects STDIN.
I didn't want to get too much into the code here, so I found that the
following works and I'm leaving it at that:

    (echo R user1 user2; echo RW user3 user4) |
        curl --data-binary @- http://user:password@server/git/setperms?reponame.git

With a few nice shell aliases, you won't even notice the horrible convolutions
here ;-)

<a name="_allowing_anonymous_access"></a>

### allowing anonymous access

Like [mob branches][mob] with ssh, you can allow completely
**un**-authenticated users to still have some rights specified in gitolite.
Briefly, here's how:

  * specify a ScriptAlias in apache config for unauthenticated access also.  I
    prefer something like

        ScriptAlias /gitmob/ /var/www/gitolite-home/bin/gl-auth-command/

  * set `$GL_HTTP_ANON_USER` to some name, like 'mob' or 'anon' in the rc file

  * give rights to this user ('mob' or 'anon' or whatever you used) in the
    gitolite config file and push the change

URLs (in this example) will then look like `http://server/gitmob/reponame.git`
-- we lose the userid:passwd part and change 'git' to 'gitmob'.

Enjoy!

[mob]: http://github.com/sitaramc/gitolite/blob/pu/doc/mob-branches.mkd