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