Documentation/howto/setup-git-server-over-http.txt

   1 From: Rutger Nijlunsing <rutger@nospam.com>
   2 Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S).
   3 Date: Thu, 10 Aug 2006 22:00:26 +0200
   4 Content-type: text/asciidoc
   5
   6 How to setup git server over http
   7 =================================
   8
   9 Since Apache is one of those packages people like to compile
  10 themselves while others prefer the bureaucrat's dream Debian, it is
  11 impossible to give guidelines which will work for everyone. Just send
  12 some feedback to the mailing list at git@vger.kernel.org to get this
  13 document tailored to your favorite distro.
  14
  15
  16 What's needed:
  17
  18 - Have an Apache web-server
  19
  20   On Debian:
  21     $ apt-get install apache2
  22     To get apache2 by default started,
  23     edit /etc/default/apache2 and set NO_START=0
  24
  25 - can edit the configuration of it.
  26
  27   This could be found under /etc/httpd, or refer to your Apache documentation.
  28
  29   On Debian: this means being able to edit files under /etc/apache2
  30
  31 - can restart it.
  32
  33   'apachectl --graceful' might do. If it doesn't, just stop and
  34   restart apache. Be warning that active connections to your server
  35   might be aborted by this.
  36
  37   On Debian:
  38     $ /etc/init.d/apache2 restart
  39   or
  40     $ /etc/init.d/apache2 force-reload
  41     (which seems to do the same)
  42   This adds symlinks from the /etc/apache2/mods-enabled to
  43   /etc/apache2/mods-available.
  44
  45 - have permissions to chown a directory
  46
  47 - have git installed on the client, and
  48
  49 - either have git installed on the server or have a webdav client on
  50   the client.
  51
  52 In effect, this means you're going to be root, or that you're using a
  53 preconfigured WebDAV server.
  54
  55
  56 Step 1: setup a bare GIT repository
  57 -----------------------------------
  58
  59 At the time of writing, git-http-push cannot remotely create a GIT
  60 repository. So we have to do that at the server side with git. Another
  61 option is to generate an empty bare repository at the client and copy
  62 it to the server with a WebDAV client (which is the only option if Git
  63 is not installed on the server).
  64
  65 Create the directory under the DocumentRoot of the directories served
  66 by Apache. As an example we take /usr/local/apache2, but try "grep
  67 DocumentRoot /where/ever/httpd.conf" to find your root:
  68
  69     $ cd /usr/local/apache/htdocs
  70     $ mkdir my-new-repo.git
  71
  72   On Debian:
  73
  74     $ cd /var/www
  75     $ mkdir my-new-repo.git
  76
  77
  78 Initialize a bare repository
  79
  80     $ cd my-new-repo.git
  81     $ git --bare init
  82
  83
  84 Change the ownership to your web-server's credentials. Use "grep ^User
  85 httpd.conf" and "grep ^Group httpd.conf" to find out:
  86
  87     $ chown -R www.www .
  88
  89   On Debian:
  90
  91     $ chown -R www-data.www-data .
  92
  93
  94 If you do not know which user Apache runs as, you can alternatively do
  95 a "chmod -R a+w .", inspect the files which are created later on, and
  96 set the permissions appropriately.
  97
  98 Restart apache2, and check whether http://server/my-new-repo.git gives
  99 a directory listing. If not, check whether apache started up
 100 successfully.
 101
 102
 103 Step 2: enable DAV on this repository
 104 -------------------------------------
 105
 106 First make sure the dav_module is loaded. For this, insert in httpd.conf:
 107
 108     LoadModule dav_module libexec/httpd/libdav.so
 109     AddModule mod_dav.c
 110
 111 Also make sure that this line exists which is the file used for
 112 locking DAV operations:
 113
 114   DAVLockDB "/usr/local/apache2/temp/DAV.lock"
 115
 116   On Debian these steps can be performed with:
 117
 118     Enable the dav and dav_fs modules of apache:
 119     $ a2enmod dav_fs
 120     (just to be sure. dav_fs might be unneeded, I don't know)
 121     $ a2enmod dav
 122     The DAV lock is located in /etc/apache2/mods-available/dav_fs.conf:
 123       DAVLockDB /var/lock/apache2/DAVLock
 124
 125 Of course, it can point somewhere else, but the string is actually just a
 126 prefix in some Apache configurations, and therefore the _directory_ has to
 127 be writable by the user Apache runs as.
 128
 129 Then, add something like this to your httpd.conf
 130
 131   <Location /my-new-repo.git>
 132      DAV on
 133      AuthType Basic
 134      AuthName "Git"
 135      AuthUserFile /usr/local/apache2/conf/passwd.git
 136      Require valid-user
 137   </Location>
 138
 139   On Debian:
 140     Create (or add to) /etc/apache2/conf.d/git.conf :
 141
 142     <Location /my-new-repo.git>
 143        DAV on
 144        AuthType Basic
 145        AuthName "Git"
 146        AuthUserFile /etc/apache2/passwd.git
 147        Require valid-user
 148     </Location>
 149
 150     Debian automatically reads all files under /etc/apache2/conf.d.
 151
 152 The password file can be somewhere else, but it has to be readable by
 153 Apache and preferably not readable by the world.
 154
 155 Create this file by
 156     $ htpasswd -c /usr/local/apache2/conf/passwd.git <user>
 157
 158     On Debian:
 159       $ htpasswd -c /etc/apache2/passwd.git <user>
 160
 161 You will be asked a password, and the file is created. Subsequent calls
 162 to htpasswd should omit the '-c' option, since you want to append to the
 163 existing file.
 164
 165 You need to restart Apache.
 166
 167 Now go to http://<username>@<servername>/my-new-repo.git in your
 168 browser to check whether it asks for a password and accepts the right
 169 password.
 170
 171 On Debian:
 172
 173    To test the WebDAV part, do:
 174
 175    $ apt-get install litmus
 176    $ litmus http://<servername>/my-new-repo.git <username> <password>
 177
 178    Most tests should pass.
 179
 180 A command line tool to test WebDAV is cadaver. If you prefer GUIs, for
 181 example, konqueror can open WebDAV URLs as "webdav://..." or
 182 "webdavs://...".
 183
 184 If you're into Windows, from XP onwards Internet Explorer supports
 185 WebDAV. For this, do Internet Explorer -> Open Location ->
 186 http://<servername>/my-new-repo.git [x] Open as webfolder -> login .
 187
 188
 189 Step 3: setup the client
 190 ------------------------
 191
 192 Make sure that you have HTTP support, i.e. your git was built with
 193 libcurl (version more recent than 7.10). The command 'git http-push' with
 194 no argument should display a usage message.
 195
 196 Then, add the following to your $HOME/.netrc (you can do without, but will be
 197 asked to input your password a _lot_ of times):
 198
 199     machine <servername>
 200     login <username>
 201     password <password>
 202
 203 ...and set permissions:
 204      chmod 600 ~/.netrc
 205
 206 If you want to access the web-server by its IP, you have to type that in,
 207 instead of the server name.
 208
 209 To check whether all is OK, do:
 210
 211    curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD
 212
 213 ...this should give something like 'ref: refs/heads/master', which is
 214 the content of the file HEAD on the server.
 215
 216 Now, add the remote in your existing repository which contains the project
 217 you want to export:
 218
 219    $ git-config remote.upload.url \
 220        http://<username>@<servername>/my-new-repo.git/
 221
 222 It is important to put the last '/'; Without it, the server will send
 223 a redirect which git-http-push does not (yet) understand, and git-http-push
 224 will repeat the request infinitely.
 225
 226
 227 Step 4: make the initial push
 228 -----------------------------
 229
 230 From your client repository, do
 231
 232    $ git push upload master
 233
 234 This pushes branch 'master' (which is assumed to be the branch you
 235 want to export) to repository called 'upload', which we previously
 236 defined with git-config.
 237
 238
 239 Using a proxy:
 240 --------------
 241
 242 If you have to access the WebDAV server from behind an HTTP(S) proxy,
 243 set the variable 'all_proxy' to 'http://proxy-host.com:port', or
 244 'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man
 245 curl' for details.
 246
 247
 248 Troubleshooting:
 249 ----------------
 250
 251 If git-http-push says
 252
 253    Error: no DAV locking support on remote repo http://...
 254
 255 then it means the web-server did not accept your authentication. Make sure
 256 that the user name and password matches in httpd.conf, .netrc and the URL
 257 you are uploading to.
 258
 259 If git-http-push shows you an error (22/502) when trying to MOVE a blob,
 260 it means that your web-server somehow does not recognize its name in the
 261 request; This can happen when you start Apache, but then disable the
 262 network interface. A simple restart of Apache helps.
 263
 264 Errors like (22/502) are of format (curl error code/http error
 265 code). So (22/404) means something like 'not found' at the server.
 266
 267 Reading /usr/local/apache2/logs/error_log is often helpful.
 268
 269   On Debian: Read /var/log/apache2/error.log instead.
 270
 271 If you access HTTPS locations, git may fail verifying the SSL
 272 certificate (this is return code 60). Setting http.sslVerify=false can
 273 help diagnosing the problem, but removes security checks.
 274
 275
 276 Debian References: http://www.debian-administration.org/articles/285
 277
 278 Authors
 279   Johannes Schindelin <Johannes.Schindelin@gmx.de>
 280   Rutger Nijlunsing <git@wingding.demon.nl>
 281   Matthieu Moy <Matthieu.Moy@imag.fr>