INSTALL: pre-requisites, and lots of stuff on ssh

the duplicate pubkey problem and the need to document it was highlighted by
Ilari

...damn I spend more time on ssh than on git it seems to me :(

INSTALL

@@ -1,3 +1,17 @@
+### 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.
+
+Gitosis-lite 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
@@ -100,4 +114,41 @@ And once in a while, if you're feeling particularly BOFH-ish, take a look at
 
 ----
 
+Footnotes:
+
+[1] Actually, due to the way gitosis-lite 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 gitosis-lite -- 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
+gitosis-lite 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
+gitosis-lite 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 :-)
+
+----
+
 gitosis-lite is released under the GPL v2 license.  See COPYING for details