gitolite/doc/2-admin.mkd

# administering and running gitolite

*Note*: some of the paths in this document use variable names.  Just refer to
`~/.gitolite.rc` for the correct values for *your* installation.

### administer

First of all, ***do NOT add new repos manually***, unless you know how to add
the required hook as well.  Without the hook, branch-level access control will
not work for that repo, which sorta defeats the idea of using gitolite :-)

Please read on to see how to do this correctly.

#### adding users and repos

  * ask each user who will get access to send you a public key.  See other
    sources (for example
    [here](http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key))
    for how to do this

  * rename each public key according to the user's name, with a `.pub`
    extension, like `sitaram.pub` or `john-smith.pub`.  You can also use
    periods and underscores

  * copy all these `*.pub` files to `$GL_KEYDIR`

  * the config file (`$GL_CONF`) is very well commented, please take a couple
    of minutes to read it.  Then edit it and

      * add new repos as needed
      * add new users and give them permissions as required.  The users names
        should be exactly the same as their keyfile names, but without the
        `.pub` extension

#### specifying gitweb and daemon access

This is a feature that I personally do not use (corporate environments don't
like unauthenticated access of any kind to any repo!), but someone wanted it,
so here goes.

There's **no special syntax** for this -- just give read permission to a user
called `gitweb` or `daemon`!  (This also means you can't have a normal user
with either of those two names, but I doubt that's a problem!).  See the "faq,
tips, etc" document for easy ways to specify access for multiple repositories.

Note that this does **not** install or configure gitweb/daemon -- that is a
one-time setup you must do separately.  All this does is:

  * for gitweb, add the repo to the list of projects to be served by gitweb
    (see the config file variable `$PROJECTS_LIST`, which should have the same
    value you specified for `$projects_list` when setting up gitweb)
  * for daemon, create the file `git-daemon-export-ok` in the repository

`src/gl-compile-conf` will keep these files consistent with the config
settings -- this includes removing such settings if you remove "read"
permissions for the special usernames.

#### compiling

  * backup your `~/.ssh/authorized_keys` file if you feel nervous :-)
      * that's "backup" as in "copy", not "move".  The next step won't work if
        the file doesn't exist.  Even an empty one is fine but it must be
        present
      * if you don't have an `~/.ssh/authorized_keys` file at all, you may
        have logged in with a password, which in turn might mean you are not
        familiar with ssh and authkeys etc.  If so, please read up at least
        [this](http://sitaramc.github.com/0-installing/9-gitolite-basics.html#IMPORTANT_overview_of_ssh),
        and preferably also the man pages for sshd and sshd\_config, to make
        sure you understand the security implications of what you are doing.
        Once you have understood that, create at least an empty
        `~/.ssh/authorized_keys` file before proceeding to the next step

  * cd to `$GL_ADMINDIR` and run `src/gl-compile-conf`

That should be it, really.  However, if you want to be doubly sure, or maybe
the first couple of times you use it, you may want to check these:

  * check the outputs

      * `~/.ssh/authorized_keys` should contain one line for each "user" pub
        key added, between two "marker" lines (which you should please please
        not remove!).  The line should contain a "command=" pointing to a
        `$GL_ADMINDIR/src/gl-auth-command` file, then some sshd restrictions, the
        key, etc.
      * `$GL_CONF_COMPILED` should contain an expanded list of the access
        control rules.  It may look a little long, but it's fairly intuitive!

  * if the run threw up any "initialising empty repo" messages, check the
    individual repos (inside `$REPO_BASE`) if you wish.  Especially make sure
    the `$REPO_BASE/[reponame].git/hooks/update` got copied OK and is
    executable