docs/http.mkd

   1 # installing on a smart http git server
   2
   3 ----
   4
   5 !!! note "Note:"
   6     "smart http" refers to the feature that came with git 1.6.6, late 2009 or
   7     so.  The base documentation for this is `man git-http-backend`.  Do
   8     **NOT** read `Documentation/howto/setup-git-server-over-http.txt` and
   9     think that is the same or even relevant -- that is from 2006 and is quite
  10     different (and arguably obsolete).
  11
  12 # WARNINGS and important notes
  13
  14   * Please read [authentication versus authorisation][auth] first, and make
  15     sure you understand what is gitolite's responsibility and what isn't.
  16
  17   * I have tested this only on stock Fedora (whatever is the current version);
  18     YDMV.
  19
  20 [auth]: concepts#authentication-and-authorisation
  21
  22 # assumptions:
  23
  24   * Apache 2.x and git installed.
  25   * Httpd runs under the "apache" userid; adjust instructions below if not.
  26   * Similarly for "/var/www" and other file names/locations.
  27
  28 # instructions
  29
  30 In place of detailed instructions, there is a script called
  31 `t/smart-http.root-setup`.  **Do NOT run this script as is -- it is actually
  32 meant for my testing setup and deletes stuff**.  However, it does provide an
  33 excellent (and working!) narration of what you need to do to install gitolite
  34 in smart http mode.
  35
  36 Make a copy of the script, go through it carefully, (possibly removing lines
  37 that delete files etc.), change values per your system, and only then run it.
  38
  39 !!! note "Note:"
  40
  41     The `GIT_PROJECT_ROOT` variable (see "man git-http-backend") is no longer
  42     optional.  Make sure you set it to some place outside apache's
  43     `DOCUMENT_ROOT`.</span>
  44
  45 # allowing unauthenticated access
  46
  47 If you want users to see repos without performing any HTTP authentication, you
  48 should first decide what repos they should have unauthenticated access to:
  49
  50     repo foo bar baz        # or maybe '@all'?
  51         R   =   nobody
  52
  53 Then in the rc file (`~/.gitolite.rc`), in the section marked "rc variables
  54 used by various features", add this (including the trailing comma):
  55
  56     HTTP_ANON_USER      =>  'nobody',
  57
  58 **Updated 2019-10-19**
  59
  60 The above does not seem to work any more.  The way it was supposed to work was
  61 that the user could supply a userid, or not.  If he did not, then gitolite
  62 would notice (the environment variable `REMOTE_USER` would be empty) and would
  63 then use whatever was specified above (in this case, `nobody`).
  64
  65 This does not seem to happen any more.  Apache seems to insist on a userid,
  66 period.  Unfortunately I am very far from being an expert in apache
  67 configuration, so, if someone can make this work *without* requiring any
  68 userid at all, please let me know.
  69
  70 # Making repositories available to both ssh and http mode clients
  71
  72 This section has been contributed by Thomas Hager (duke at sigsegv dot at),
  73 and is available [here](contrib/ssh-and-http).
  74
  75 # usage
  76
  77 !!! danger "Warning:"
  78     Http mode does not seem capable of setting an exit code when things fail,
  79     unlike ssh mode.  Therefore, using an http-hosted gitolite in scripts may
  80     need more care and thought.
  81
  82 ## client side
  83
  84 Git URLs look like `https://user:password@server/git/reponame.git`.
  85
  86 The custom commands, like "info", "expand" should be handled as follows.  The
  87 command name will come just after the `/git/`, followed by a `?`, followed by
  88 the arguments, with `+` representing a space.  Here are some examples:
  89
  90 ```sh
  91 # ssh git@server info
  92 curl https://user:password@server/git/info
  93 # ssh git@server info repopatt
  94 curl https://user:password@server/git/info?repopatt
  95 # ssh git@server info repopatt user1 user2
  96 curl https://user:password@server/git/info?repopatt+user1+user2
  97 ```
  98
  99 With a few nice shell aliases, you won't even notice the horrible convolutions
 100 here ;-)  See t/smart-http for a couple of useful ones.
 101
 102 ## server side
 103
 104 The `gitolite` command (for example, `gitolite compile`, `gitolite query-rc`,
 105 and so on) *can* be run on the server, but it's not straightforward.  Assuming
 106 you installed exactly as given in this page, you should
 107
 108   * get a shell by using, say, `su -s /bin/bash - apache`
 109   * run `export HOME=$HOME/gitolite-home`
 110   * run `export PATH=$PATH:$HOME/bin`
 111
 112 and *then* you can run `gitolite <subcommand>`
 113