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