ips.mkd

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