From ad727488fc9882e39295b32168618309ebadaa6b Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Sun, 14 Nov 2010 11:05:13 +0530 Subject: [PATCH] (install doc) various updates (thanks to a somewhat heated "discussion" with "abstrakt" on #git) While I don't agree with everything he said, some improvements are always possible (always, always!) in docs: - move the "conventions used" section closer to the action - add note about RPM/DEB using "gitolite" as the user, not "git" - de-emphasise multiple gitolite hosting users at the top; refer advanced users to the already present detailed section later instead - in that section, add a bit of intro, and hand-wave the inconsistency between its 2 sub-sections ;-) ---- Unrelated to the "discussion" today, someone else (running Arch? don't remember) had a system where /usr/local/bin was not in $PATH for a normal user, so I added a note about that. --- doc/1-INSTALL.mkd | 75 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/doc/1-INSTALL.mkd b/doc/1-INSTALL.mkd index 09da2f2..c918a88 100644 --- a/doc/1-INSTALL.mkd +++ b/doc/1-INSTALL.mkd @@ -4,13 +4,13 @@ In this document: * please read this first * important notes - * conventions used * requirements * client/workstation * server * technical skills * installation and setup * install methods and deciding which one to use + * conventions used * (package method) directly on the server, using RPM/DEB * (root method) directly on the server, manually, with root access * (non-root method) directly on the server, manually, without root access @@ -56,8 +56,9 @@ A gitolite setup has: * a server * a "hosting user" on the server -- the userid under which gitolite runs. - You can have any number of "hosting users" on one server; in fact every - user can host their own gitolite instance + (Side note: there is *usually* only one hosting user per server (machine), + but gitolite makes it trivial to have as many as you want. Advanced users + can look [here][mgs]!) * an "admin user" -- the user who sets up gitolite and configures it * the admin user's client or workstation, from which he does all his work @@ -70,18 +71,6 @@ emergency use. However, I will not be documenting it because (a) if you know ssh you'll know how to extrapolate my instructions to do this and (b) if you don't know ssh it'll be a nightmare to support you. - - -#### conventions used - -Throughout the documentation, we use "YourName" as the admin user, and his -workstation is called "client". The hosting user is "git", and the server is -called "server". **Please substitute your values as needed**. - -Also, we often say "the rc file". This means `~/.gitolite.rc` on the server. -And when we say the "access control rules", or "conf file", or "config file", -we mean `conf/gitolite.conf` on your gitolite-admin clone. - #### requirements @@ -151,6 +140,22 @@ Gitolite has 4 install methods: Here's how you install using these 3 methods. Future upgrades are equally easy -- the steps required for upgrading are marked "(U)". + + +#### conventions used + +Throughout the documentation, we use "YourName" as the admin user, and his +workstation is called "client". The hosting user is "git", and the server is +called "server". **Please substitute your values as needed**. + +**If you're using DEB or RPM**, the installer creates a user called +"gitolite", so substitute that for "git" anywhere in the docs where the +"hosting user" is mentioned as "git". + +Also, we often say "the rc file". This means `~/.gitolite.rc` on the server. +And when we say the "access control rules", or "conf file", or "config file", +we mean `conf/gitolite.conf` on your gitolite-admin clone. + #### (package method) directly on the server, using RPM/DEB @@ -160,10 +165,10 @@ easy -- the steps required for upgrading are marked "(U)". * (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.). - * on the server, "su - git", then as "git" user, run `gl-setup + * on the server, "su - gitolite", then as "gitolite" user, run `gl-setup /tmp/YourName.pub`. - * on the client, run `cd; git clone git@server:gitolite-admin` + * on the client, run `cd; git clone gitolite@server:gitolite-admin` @@ -182,8 +187,14 @@ easy -- the steps required for upgrading are marked "(U)". mkdir -p /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks - * on the server, "su - git", then as "git" user, run `gl-setup - /tmp/YourName.pub`. + * on the server, "su - git", then as "git" user, run `which gl-setup`. This + should respond with `/usr/local/bin/gl-setup`. If this is not what you + get, you have some `$PATH` issues. Make sure `/usr/local/bin` is in the + `$PATH` for the git user, and that no prior components of the path contain + another copy of `gl-setup`. You *must* run the one in the directory that + is the first argument of `gl-system-install` above. + + * now run `gl-setup /tmp/YourName.pub`. * on the client, run `cd; git clone git@server:gitolite-admin` @@ -257,14 +268,27 @@ repositories. Check [here][twokeys] for why. ### special cases -- multiple gitolite servers +(**Advanced users only, please!**) + +There is no gitolite "daemon"; it gets invoked via sshd which calls +"gl-auth-command" via the "command=" option in the authkeys file (see +[gitolite and ssh][gash] for more). + +If you think about it, this means every real (unix) user on the system can +host her own gitolite server! + +Of course, one doesn't normally do that in the interests of sanity, but let's +say you want to create one gitolite instance for each department on some +company-wide mega-server. + #### package method and root method With the first two methods of installation, it's trivial to create multiple -gitolite instances (say one for each department, on some mega company-wide -server). You can even do this without giving shell access to the admins. -Here's an example with just two "departments", and their admins Alice and Bob: +gitolite instances. You can even do this without giving shell access to the +admins. Here's an example with just two "departments", and their admins Alice +and Bob: * create userids `webbrowser_repos` and `webserver_repos` * ask Alice and Bob for their pubkeys; copy them to the respective home @@ -285,6 +309,11 @@ domain, and that's quite enough for normal operations. #### from-client method +You can do the same thing using this method also, but it's a little more +cumbersome. Instead, I'll describe a different scenario -- one "admin" +installing gitolite on different servers. You can adapt that to the above +case quite easily if you wish. + Thanks to Matt Perzel, the easy-install command now takes an optional 4th parameter, which is the "nickname" of the gitolite server. It gets defined in `~/.ssh/config`, and if not used it defaults to "gitolite". @@ -352,3 +381,5 @@ uninstalling gitolite is described in great detail in [doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/uninstall.mkd [twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd#twokeys [transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd +[mgs]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#_special_cases_multiple_gitolite_servers +[gash]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd