190 lines
7.2 KiB
Markdown
190 lines
7.2 KiB
Markdown
In this document:
|
|
|
|
* pre-requisites
|
|
* quickinstall
|
|
* install notes
|
|
* administer
|
|
* run
|
|
* special cases
|
|
* errors, warnings, etc
|
|
|
|
----
|
|
|
|
### pre-requisites
|
|
|
|
One of the big needs I'm trying to fill here is people who do not have root
|
|
access, permissions to create other userids, etc. This could be a typical
|
|
hosting provider type of thing, or -- in a corporate setting -- a very tightly
|
|
controlled server.
|
|
|
|
Gitolite requires these:
|
|
|
|
* git itself, the more recent the better
|
|
* perl, typically installed with git, since git sort of needs it; any
|
|
version that includes `Data::Dumper`[1] will do.
|
|
* one user account on the server, with password access [2]
|
|
|
|
### quickinstall
|
|
|
|
I assume all the files pertaining to this software are untarred and available
|
|
in the current directory.
|
|
|
|
A quick install, taking all the defaults, can be done with the following
|
|
commands; just copy and paste them into your shell:
|
|
|
|
# this one is fixed to the location shown
|
|
cp example.gitolite.rc ~/.gitolite.rc
|
|
|
|
# the destinations below are defaults; if you change the paths in the "rc"
|
|
# file above, these destinations also must change accordingly
|
|
|
|
# mkdir $REPO_BASE, $GL_ADMINDIR, and $GL_KEYDIR
|
|
mkdir ~/repositories
|
|
mkdir ~/.gitolite
|
|
mkdir ~/.gitolite/keydir
|
|
|
|
# copy sample conf to $GL_CONF
|
|
cp example.conf ~/.gitolite/gitolite.conf
|
|
|
|
# copy the 3 programs to $GL_ADMINDIR
|
|
cp update-hook.pl ~/.gitolite
|
|
cp gl-auth-command ~/.gitolite
|
|
cp gl-compile-conf ~/.gitolite
|
|
|
|
# optional; copy the documents also (if you untarred the package into a
|
|
# temporary directory and need to get rid of it)
|
|
cp INSTALL README.markdown ~/.gitolite
|
|
|
|
### install notes
|
|
|
|
* At present the location of `~/.gitolite.rc` is fixed (maybe later I'll
|
|
change it to a "git config" variable).
|
|
|
|
If you edit it and change any paths, be sure to keep the perl syntax --
|
|
you *don't* have to know perl to do so, it's fairly easy to guess in this
|
|
limited case. And of course, make sure you adjust the commands shown
|
|
above to suit the new locations
|
|
|
|
* the config file is (by default) at `~/.gitolite/gitolite.conf`.
|
|
Edit the file as you wish. The comments in the file ought to be clear
|
|
enough but let me know if not
|
|
|
|
* if you want to bring in existing (bare, server) repos into gitolite,
|
|
this should work:
|
|
* backup the repo, then move it to `$BASE_REPO`
|
|
* copy `$GL_ADMINDIR/update-hook.pl` to `[reponame].git/hooks/update` --
|
|
if you don't do this, per branch restrictions will not work
|
|
* then update the keys and the config file and "compile"
|
|
|
|
### administer
|
|
|
|
* 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-gitosis.html#generating_a_public_key))
|
|
for how to do this
|
|
* for each "user" in `$GL_CONF`, copy their public key to a file called
|
|
"user.pub" in `$GL_KEYDIR`. For example, mine would be called
|
|
"sitaram.pub"
|
|
* edit the config file (`$GL_CONF`) to add the new users in whatever way you
|
|
like
|
|
* backup your `~/.ssh/authorized_keys` file if you feel nervous :-)
|
|
* cd to `$GL_ADMINDIR` and run `./gl-compile-conf`
|
|
|
|
#### optional -- if you want to be doubly sure
|
|
|
|
It should all work, but the first couple of times 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/gl-auth-command` file, then some sshd restrictions, the
|
|
key, etc.
|
|
* `$GL_CONF_COMPILED` (default
|
|
`~/.gitolite/gitolite.conf-compiled.pm`) 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
|
|
|
|
### run
|
|
|
|
Just use it as normal. Every new repo mentioned has been created already, so
|
|
(as long as your clients are using git > 1.6.2), you can just clone it.
|
|
|
|
And once in a while, if you're feeling particularly BOFH-ish, take a look at
|
|
`$GL_ADMINDIR/log` :-)
|
|
|
|
### special cases
|
|
|
|
#### one user, many keys
|
|
|
|
Sometimes the same user needs to access the server from differnt machines
|
|
(like a desktop and a laptop, for instance). Gitolite needs to be given all
|
|
these public keys, but associate *all* of them with the same user.
|
|
|
|
Recall from the "administer" section above that each "user" has one public key
|
|
file called "user.pub", which seems to imply a one-to-one match.
|
|
|
|
But this is not strictly true -- gitolite allows a *filename* to have a small
|
|
"location" piece attached to it. So you can have "sitaram@laptop.pub" and
|
|
"sitaram@desktop.pub", for instance, and they'll all be treated as keys for
|
|
"sitaram". Just add both the files to "keydir/", and use the username
|
|
"sitaram" (*without* the "@location" part) in your `gitolite.conf` file.
|
|
|
|
Advantages: if a user reports *one of his keys* is lost or needs replacing,
|
|
it's easy to remove or replace just that.
|
|
|
|
(Gitosis keeps multiple entries in the same "user.pub", which means to delete
|
|
or change one of the keys you have to edit the file and figure out which of
|
|
the 2 or more long lines should be removed).
|
|
|
|
### errors, warnings, etc
|
|
|
|
* when you clone an empty repo, git seems to complain about the remote
|
|
hanging up or something. I have no idea what that is, but it doesn't seem
|
|
to hurt anything. This happens even in normal git, not just gitolite.
|
|
|
|
### Footnotes:
|
|
|
|
[1] Actually, due to the way gitolite is architected, you can manage
|
|
without `Data::Dumper` on the server if you have no choice. Only
|
|
`gl-compile-conf` needs it, so just run that on some other machine and copy
|
|
the two output files across. Cumbersome but doable... the advantage of
|
|
separating all the hard work into a manually-run piece :)
|
|
|
|
[2] If you have *only* pubkey access, and **no** password access, then your
|
|
pubkey is already in the server's `~/.ssh/authorized_keys`. If you also need
|
|
to access git as a developer (clone, push, etc), do *not* submit this same
|
|
pubkey to gitolite -- it won't work.
|
|
|
|
Instead, create a different keypair for your "developer" role (by, e.g.,
|
|
`ssh-keygen -t rsa -f ~/.ssh/gitdev`), then give `~/.ssh/gitdev.pub` to
|
|
gitolite as "yourname.pub", just like you would do for any other user.
|
|
|
|
Then you create a suitable `~/.ssh/config` to use the correct key
|
|
automatically, something like this:
|
|
|
|
host gitadm
|
|
hostname my.server
|
|
user my_userid_on_server
|
|
|
|
host gitdev
|
|
hostname my.server
|
|
user my_userid_on_server
|
|
identityfile ~/.ssh/gitdev
|
|
|
|
From now on, `ssh gitadm` will get you a command line on the server, to do
|
|
gitolite admin and other work. And your repository URLs would look like
|
|
`gitdev:reponame.git`. Very, very, simple...
|
|
|
|
And as with gitosis, there's more "ssh" magic than "git" magic here :-)
|
|
|
|
----
|
|
|
|
gitolite is released under the GPL v2 license. See COPYING for details
|