gitolite/doc/big-config.mkd

# what is a "big-config"

In this document:

  * <a href="#when_why_do_we_need_it_">when/why do we need it?</a>
  * <a href="#how_do_we_use_it_">how do we use it?</a>
  * <a href="#other_optimisations">other optimisations</a>
  * <a href="#what_are_the_downsides_">what are the downsides?</a>
  * <a href="#extra_coolness_usergroups_and_LDAP_similar_tools">(extra coolness) usergroups and LDAP/similar tools</a>

<a name="when_why_do_we_need_it_"></a>

### when/why do we need it?

A "big config" is anything that has a few thousand users and a few thousand
repos, organised into groups that are much smaller in number (like maybe a few
hundreds of repogroups and a few dozens of usergroups).

So let's say you have

    @wbr    =   lynx firefox
    @devs   =   alice bob

    repo @wbr
        RW+     next    =   @devs
        RW    master    =   @devs

Gitolite internally translates this to

    repo lynx firefox
        RW+     next    =   alice bob
        RW    master    =   alice bob

Not just that -- it now generates the actual config rules once for each
user-repo-ref combination (there are 8 combinations above; the compiled config
file looks partly like this:

    %repos = (
      'firefox' => {
        'R' => {
          'alice' => 1,
          'bob' => 1
        },
        'W' => {
          'alice' => 1,
          'bob' => 1
        },
        'alice' => [
          {
            'refs/heads/next' => 'RW+'
          },
          {
            'refs/heads/master' => 'RW'
          }
        ],
        'bob' => [
          {
            'refs/heads/next' => 'RW+'
          },
          {
            'refs/heads/master' => 'RW'
          }
        ]
      },
      'lynx' => {
        'R' => {
          'alice' => 1,
          'bob' => 1
        },
        'W' => {
          'alice' => 1,
          'bob' => 1
        },
        'alice' => [
          {
            'refs/heads/next' => 'RW+'
          },
          {
            'refs/heads/master' => 'RW'
          }
        ],
        'bob' => [
          {
            'refs/heads/next' => 'RW+'
          },
          {
            'refs/heads/master' => 'RW'
          }
        ]
      }
    );

Phew!

You can imagine what that does when you have 10,000 users and 10,000 repos.
Let's just say it's not pretty :)

<a name="how_do_we_use_it_"></a>

### how do we use it?

Now, if you had all those 10,000 users and repos explicitly listed (no
groups), then there is no help.  But if, like the above example, you had
groups like we used above, there is hope.

Just set

    $GL_BIG_CONFIG = 1;

in the `~/.gitolite.rc` file on the server (see next section for more
variables).  When you do that, and push this configuration, the compiled file
looks like this:

    %repos = (
      '@wbr' => {
        '@devs' => [
          {
            'refs/heads/next' => 'RW+'
          },
          {
            'refs/heads/master' => 'RW'
          }
        ],
        'R' => {
          '@devs' => 1
        },
        'W' => {
          '@devs' => 1
        }
      },
    );
    %groups = (
      '@devs' => {
        'alice' => 'master',
        'bob' => 'master'
      },
      '@wbr' => {
        'firefox' => 'master',
        'lynx' => 'master'
      }
    );

That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.

<a name="other_optimisations"></a>

### other optimisations

The default RC file contains the following lines (we've already discussed the
first one):

    $GL_BIG_CONFIG = 0;
    $GL_NO_DAEMON_NO_GITWEB = 0;
    $GL_NO_CREATE_REPOS = 0;
    $GL_NO_SETUP_AUTHKEYS = 0;

`GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
if you *do* have a large number of repositories, and do *not* use gitolite's
support for gitweb or git-daemon access (see "[easier to specify gitweb
description and gitweb/daemon access][gw]" for details).  This will save a lot
of time when you push the gitolite-admin repo with changes.  This variable
also control whether "git config" lines (such as `config hooks.emailprefix =
"[gitolite]"`) will be processed or not.

Setting this is relatively harmless to a normal installation, unlike the next
two variables :-)  `GL_NO_CREATE_REPOS` and `GL_NO_SETUP_AUTHKEYS` are meant
for installations where some backend system already exists that does all the
actual repo creation, and all the authentication setup (ssh auth keys),
respectively.

Summary: Please **leave those two variables alone** unless you're initials are
"JK" ;-)

Also note that using all 3 of the `GL_NO_*` variables will result in
*everything* after the config compile being skipped.  In other words, gitolite
is being used **only** for its access control language.

[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb

<a name="what_are_the_downsides_"></a>

### what are the downsides?

There is one minor issue.

If you use the delegation feature, you can no longer define or extend
@groups in a fragment, for security reasons.  It will also not let you use any
group other than the @fragname itself (specifically, groups which contained a
subset of the allowed @fragname, which would work normally, do not work now).

(If you didn't understand all that, you're probably not using delegation, so
feel free to ignore it!)

<a name="extra_coolness_usergroups_and_LDAP_similar_tools"></a>

### (extra coolness) usergroups and LDAP/similar tools

[Please NOTE: this is all about *user* groups, not *repo* groups]

Gitolite now allows usergroup information to be passed in from outside.  The
`gl-auth-commmand` can now take an optional list of usergroup names after the
first argument (which is the username).

To understand why this is useful, consider the following:

Some people have an LDAP-backed ssh daemon (or some other similar mechanism
that can speak "ssh" to the client), with pubkeys stored in LDAP, etc., and
some way (not using `~/.ssh/authorized_keys`) of invoking gitolite.

Such setups also have "usergroups", and a way to tell, for each user, what
groups he/she is a member of.  So let's say "alice" works on projects "foo"
and "bar", while "bob" is works on project "bar" and is a member of the
`L3_support` team.

You can use those group names in the gitolite config file for access control
as "@foo", "@bar", `@L3_support`, etc.; please note the "@" prefix because
gitolite requires it.

However, that still leaves a wee little inconvenience.  You still have to add
lines like this to the gitolite config file:

    @foo        = alice
    @bar        = alice bob
    @L3_support = bob

You don't need to do that anymore now.  Tell your authentication system that,
after authenticating alice, instead of running:

    /some/path/to/gl-auth-command alice

it should first find the groups that alice is a member of, and then run:

    /some/path/to/gl-auth-command alice foo bar

That's it.  Internally, gitolite will behave as if the config file had also
specified:

    @foo = alice
    @bar = alice