req.mkd

   1 <!-- options: toc -->
   2
   3 % Before you start...
   4
   5 include sidebar-toc
   6
   7 This page talks about what you need to make sure you have before you install
   8 gitolite.  For most people, this is not a big deal, but please read through it
   9 anyway.  If you want to make sure, there's a section on trying it out safely.
  10
  11 # your skills
  12
  13   * If you're installing gitolite, you're a "system admin", like it or not.
  14     Since most people use the ssh mode, **[ssh][]** is therefore a necessary
  15     skill.  Please take the time to learn at least enough to get passwordless
  16     access working.
  17
  18   * You also need to be somewhat familiar with git itself.  You cannot
  19     administer a whole bunch of git repositories if you don't know the basics
  20     of git.
  21
  22     Please make sure you understand at least the following concepts: *bare
  23     versus non-bare repos, cloning a repo, making changes and committing them,
  24     pushing commits to a 'remote', the special remote called 'origin',
  25     difference between a fast-forward push and a rewind push, 'refs' (i.e.,
  26     branches and tags)*.
  27
  28     It also helps to understand git's hooks mechanism, git-config, and so on.
  29
  30   * Some familiarity with Unix and shells is probably required.
  31
  32   * [Regular expressions][regex] are a big part of gitolite in many places but
  33     familiarity is not necessary to do *basic* access control.
  34
  35 # your server
  36
  37   * Any Unix system with a posix compatible "sh" and a **sane** file system.
  38   * Git version 1.6.6 or later.
  39   * Perl 5.8.8 or later (see <https://lwn.net/Articles/348084/> if this does
  40     not seem to be enough).
  41   * Openssh (almost any version).  Optional if you're using [smart
  42     http][http].
  43       * **IMPORTANT**: although a default openssh config will not do this (AFAIK),
  44         **do not** allow the user to set environment variables if you care about
  45         security at all.
  46   * A dedicated Unix userid to be the hosting user, usually "git" but it can
  47     be any user, even your own normal one.  (If you're using an RPM/DEB the
  48     install probably created one called "gitolite").
  49
  50 # you and your users' clients
  51
  52   * Openssh client.
  53   * Git 1.6.6 or later.  Almost any git client will work, as long as it knows
  54     how to use ssh keys and send the right one along.
  55
  56 # cautions and caveats
  57
  58 **Please take note of the following points**:
  59
  60   * If you're bringing existing repos into gitolite, please see
  61     [this][existing] first.
  62
  63   * Gitolite expects all the directories and files it manages/uses to be owned
  64     by the [hosting user][hu] and not have strange permissions and ownerships.
  65
  66   * Gitolite does NOT like it if you fiddle with [files and directories it
  67     cares about][files] in any way except as directed in the documentation.
  68
  69   * Gitolite depends on several system-installed packages: openssh, git, perl,
  70     sh being the main ones.  They should all be configured sensibly and with
  71     most of the normal defaults.  (For example, if your sshd config says the
  72     authorized keys file should be placed in some directory other than the
  73     default, expect trouble).
  74
  75 @@gray((For your entertainment, [here][no-way] are some requests I have
  76 refused over the years).)@@
  77
  78 # trying out gitolite safely {#trying}
  79
  80 If you're not sure if gitolite is right for you or your system, it's easy to
  81 take it for a trial run, in ssh mode, and play with all of its features
  82 (except mirroring).  This is very safe, and does not affect anything on your
  83 system permanently.
  84
  85 <font color="red">**WARNING: this will clobber [these files and
  86 directories][clobber] in your `$HOME`.  Ideally, you should use a throwaway
  87 userid**.</font>
  88
  89 Just create a **throw-away userid**, log in to it, then run these commands:
  90
  91     git clone git://github.com/sitaramc/gitolite
  92     cd gitolite
  93     prove t/ssh*
  94
  95 You will get an error that forces you to read `t/README` and set an env var
  96 before the test can proceed.  This is intentional; I've had people who don't
  97 pay attention to the "data loss" warning, and then complain that it was not
  98 prominent enough.  Forcing them to read a much smaller page appears to focus
  99 their attention better!
 100
 101 If it doesn't work, re-read this page to see if you may have missed something
 102 that gitolite requires, or ask for [support][contact].
 103
 104 If it works, you get a gitolite installation with 7 gitolite users ("admin",
 105 and "u1" through "u6").
 106
 107 Don't forget that the client and the server are all on the same user on the
 108 same machine; we're *simulating* 7 gitolite users using ssh keys!  (How?
 109 Maybe `~/.ssh/config` will give you a hint).
 110
 111 URLs look like `user:repo`, so for example you can clone the admin repo by
 112 `git clone admin:gitolite-admin`.  Remote commands look like `ssh u1 info`.
 113
 114 So start by cloning the admin repo, and try out whatever you want!