docs/fool_proof_setup.mkd

   1 # fool-proof, step-by-step, install and setup
   2
   3 ----
   4
   5 This page is useful if the normal [install](install) instructions did not work for
   6 you.
   7
   8 # pre-requisites, etc
   9
  10 These are the pre-requisites:
  11
  12   * Any Linux machine on which git has already been installed.
  13   * Probably any BSD or legacy system like Solaris will also work, but I have
  14     not tested them.
  15       * I do not consider Apple devices to be Unix enough; it should work, but
  16         please do not ask me for help if it does not.
  17
  18 This page has several restrictions and constraints that seem unnecessary to
  19 people who **do** understand ssh. That's the whole point -- I'm compensating
  20 for lack of ssh knowledge by removing things that trip people up.
  21
  22 If even this page does not help you install gitolite, I probably cannot help
  23 you.  Either you did not follow the instructions carefully <font
  24 color="gray">(maybe some task has to be run on your workstation, but you ran
  25 it on the server, or you ran something as root when it should be as the
  26 hosting user, etc.)</font>, or your environment is far too different from
  27 standard Unix, or you have some other problem.  In any case, it is not
  28 something I can help with.  Sorry.
  29
  30 # assumptions
  31
  32   * Your name is Ron.  Substitute accordingly in the instructions below.
  33
  34   * You have a workstation.
  35
  36   * You have a server called `server`.
  37
  38   * You have root access on this server.
  39
  40 # installation tasks
  41
  42 1.  Create a new userid on the server, say `git`.  This will be the **hosting
  43     user**.  ("hosting user" means when you're done installing, your users
  44     will use URLs like `git@server:reponame` or `ssh://git@server/reponame`).
  45
  46     **Make sure this is a NEW userid**.
  47
  48     If the name you want already exists, then:
  49
  50       * Log in as root.
  51       * If you have any data on that user's HOME directory save it somewhere
  52         else.
  53       * Delete the userid.
  54       * Completely wipe out (erase) the home directory of the user (since on
  55         most systems merely deleting the user does not remove the home
  56         directory).
  57       * Re-create the userid again.
  58
  59 2.  If you don't already have one, make yourself an ssh keypair **on your
  60     workstation**.
  61
  62     Do NOT add this public key to the authorised keys file on the newly
  63     created hosting user!
  64
  65     Your ONLY access to the new (`git`) userid should be by logging onto the
  66     server as root, then running `su - git`.
  67
  68 3.  Now copy the pubkey from your workstation (`~/.ssh/id_rsa.pub`) to the
  69     server as `/tmp/ron.pub`.  (Your name is Ron, remember?)
  70
  71 4.  Log on to the server as root.
  72
  73 5.  Switch to the `git` user:
  74
  75         su - git
  76
  77 6.  Clone the gitolite source code
  78
  79         git clone https://github.com/sitaramc/gitolite
  80
  81 7.  Install it
  82
  83         cd $HOME
  84         mkdir -p bin
  85         gitolite/install -to $HOME/bin
  86
  87 8.  Set it up
  88
  89         cd $HOME
  90         $HOME/bin/gitolite setup -pk /tmp/ron.pub
  91
  92 9.  Now go to your workstation and type in
  93
  94         git ls-remote git@server:gitolite-admin
  95
  96     This should return something like
  97
  98         9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4    HEAD
  99         9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4    refs/heads/master
 100
 101     (do I have to mention that your SHAs will be different?)
 102
 103 # administration tasks
 104
 105 Most day-to-day administration is done by making changes to a clone of the
 106 gitolite-admin repo and pushing.  (There are some things that are done by
 107 editing `$HOME/.gitolite.rc` on the server, but those are too advanced for
 108 this tutorial so we will ignore that).
 109
 110 1.  To start administering gitolite, clone the gitolite-admin repo:
 111
 112         git clone git@server:gitolite-admin
 113
 114 2.  Now go to the new directory this creates, and look around:
 115
 116         cd gitolite-admin
 117         ls -A
 118
 119     which gives you
 120
 121         conf/  .git/  keydir/
 122
 123     Ignoring the ".git" and exploring further:
 124
 125         ls -A conf keydir
 126
 127     which says:
 128
 129         conf:
 130         gitolite.conf
 131
 132         keydir:
 133         ron.pub
 134
 135 3.  Let's say you want to add your colleague Alice.  She has sent you her ssh
 136     public key by email (the file is called `id_rsa.pub`).  Save this file as
 137     /tmp/alice.pub, then do this:
 138
 139         # still in your gitolite-admin clone, from the previous step
 140         cp /tmp/alice.pub keydir
 141         git add keydir
 142         git commit -m 'new user alice'
 143         git push
 144
 145 4.  Well, that might not be sufficient.  There aren't any new repos for alice
 146     to play with, yet.  So here's what you do: edit "conf/gitolite.conf" and
 147     add something like to the end:
 148
 149         repo foo
 150             RW+     =   alice
 151             R       =   ron
 152
 153     Save the file, then `git add conf; git commit -m 'new repo foo'; git
 154     push`.
 155
 156     This will automatically create a brand new repo called "foo" on the server, and
 157     alice will be able to clone from it, or push anything to it.
 158