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.
   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 at the server _and_ client
  44
  45 In effect, this probably means you're going to be root.
  46
  47
  48 Step 1: setup a bare GIT repository
  49 -----------------------------------
  50
  51 At the time of writing, git-http-push cannot remotely create a GIT
  52 repository. So we have to do that at the server side with git. Another
  53 option would be to generate an empty repository at the client and copy
  54 it to the server with WebDAV. But then you're probably the first to
  55 try that out :)
  56
  57 Create the directory under the DocumentRoot of the directories served
  58 by Apache. As an example we take /usr/local/apache2, but try "grep
  59 DocumentRoot /where/ever/httpd.conf" to find your root:
  60
  61     $ cd /usr/local/apache/htdocs
  62     $ mkdir my-new-repo.git
  63
  64   On Debian:
  65
  66     $ cd /var/www
  67     $ mkdir my-new-repo.git
  68
  69
  70 Initialize a bare repository
  71
  72     $ cd my-new-repo.git
  73     $ git --bare init-db
  74
  75
  76 Change the ownership to your web-server's credentials. Use "grep ^User
  77 httpd.conf" and "grep ^Group httpd.conf" to find out:
  78
  79     $ chown -R www.www .
  80
  81   On Debian:
  82
  83     $ chown -R www-data.www-data .
  84
  85
  86 If you do not know which user Apache runs as, you can alternatively do
  87 a "chmod -R a+w .", inspect the files which are created later on, and
  88 set the permissions appropriately.
  89
  90 Restart apache2, and check whether http://server/my-new-repo.git gives
  91 a directory listing. If not, check whether apache started up
  92 successfully.
  93
  94
  95 Step 2: enable DAV on this repository
  96 -------------------------------------
  97
  98 First make sure the dav_module is loaded. For this, insert in httpd.conf:
  99
 100     LoadModule dav_module libexec/httpd/libdav.so
 101     AddModule mod_dav.c
 102
 103 Also make sure that this line exists which is the file used for
 104 locking DAV operations:
 105
 106   DAVLockDB "/usr/local/apache2/temp/DAV.lock"
 107
 108   On Debian these steps can be performed with:
 109
 110     Enable the dav and dav_fs modules of apache:
 111     $ a2enmod dav_fs
 112     (just to be sure. dav_fs might be unneeded, I don't know)
 113     $ a2enmod dav
 114     The DAV lock is located in /etc/apache2/mods-available/dav_fs.conf:
 115       DAVLockDB /var/lock/apache2/DAVLock
 116
 117 Of course, it can point somewhere else, but the string is actually just a
 118 prefix in some Apache configurations, and therefore the _directory_ has to
 119 be writable by the user Apache runs as.
 120
 121 Then, add something like this to your httpd.conf
 122
 123   <Location /my-new-repo.git>
 124      DAV on
 125      AuthType Basic
 126      AuthName "Git"
 127      AuthUserFile /usr/local/apache2/conf/passwd.git
 128      Require valid-user
 129   </Location>
 130
 131   On Debian:
 132     Create (or add to) /etc/apache2/conf.d/git.conf :
 133
 134     <Location /my-new-repo.git>
 135        DAV on
 136        AuthType Basic
 137        AuthName "Git"
 138        AuthUserFile /etc/apache2/passwd.git
 139        Require valid-user
 140     </Location>
 141
 142     Debian automatically reads all files under /etc/apach2/conf.d.
 143
 144 The password file can be somewhere else, but it has to be readable by
 145 Apache and preferably not readable by the world.
 146
 147 Create this file by
 148     $ htpasswd -c /usr/local/apache2/conf/passwd.git <user>
 149
 150     On Debian:
 151       $ htpasswd -c /etc/apache2/passwd.git <user>
 152
 153 You will be asked a password, and the file is created. Subsequent calls
 154 to htpasswd should omit the '-c' option, since you want to append to the
 155 existing file.
 156
 157 You need to restart Apache.
 158
 159 Now go to http://<username>@<servername>/my-new-repo.git in your
 160 browser to check whether it asks for a password and accepts the right
 161 password.
 162
 163 On Debian:
 164
 165    To test the WebDAV part, do:
 166
 167    $ apt-get install litmus
 168    $ litmus http://<servername>/my-new-repo.git <username> <password>
 169
 170    Most tests should pass.
 171
 172 A command line tool to test WebDAV is cadaver.
 173
 174 If you're into Windows, from XP onwards Internet Explorer supports
 175 WebDAV. For this, do Internet Explorer -> Open Location ->
 176 http://<servername>/my-new-repo.git [x] Open as webfolder -> login .
 177
 178
 179 Step 3: setup the client
 180 ------------------------
 181
 182 Make sure that you have HTTP support, i.e. your git was built with curl.
 183 The easiest way to check is to look for the executable 'git-http-push'.
 184
 185 Then, add the following to your $HOME/.netrc (you can do without, but will be
 186 asked to input your password a _lot_ of times):
 187
 188     machine <servername>
 189     login <username>
 190     password <password>
 191
 192 ...and set permissions:
 193      chmod 600 ~/.netrc
 194
 195 If you want to access the web-server by its IP, you have to type that in,
 196 instead of the server name.
 197
 198 To check whether all is OK, do:
 199
 200    curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/
 201
 202 ...this should give a directory listing in HTML of /var/www/my-new-repo.git .
 203
 204
 205 Now, add the remote in your existing repository which contains the project
 206 you want to export:
 207
 208    $ git-repo-config remote.upload.url \
 209        http://<username>@<servername>/my-new-repo.git/
 210
 211 It is important to put the last '/'; Without it, the server will send
 212 a redirect which git-http-push does not (yet) understand, and git-http-push
 213 will repeat the request infinitely.
 214
 215
 216 Step 4: make the initial push
 217 -----------------------------
 218
 219 From your client repository, do
 220
 221    $ git push upload master
 222
 223 This pushes branch 'master' (which is assumed to be the branch you
 224 want to export) to repository called 'upload', which we previously
 225 defined with git-repo-config.
 226
 227
 228 Troubleshooting:
 229 ----------------
 230
 231 If git-http-push says
 232
 233    Error: no DAV locking support on remote repo http://...
 234
 235 then it means the web-server did not accept your authentication. Make sure
 236 that the user name and password matches in httpd.conf, .netrc and the URL
 237 you are uploading to.
 238
 239 If git-http-push shows you an error (22/502) when trying to MOVE a blob,
 240 it means that your web-server somehow does not recognize its name in the
 241 request; This can happen when you start Apache, but then disable the
 242 network interface. A simple restart of Apache helps.
 243
 244 Errors like (22/502) are of format (curl error code/http error
 245 code). So (22/404) means something like 'not found' at the server.
 246
 247 Reading /usr/local/apache2/logs/error_log is often helpful.
 248
 249   On Debian: Read /var/log/apache2/error.log instead.
 250
 251
 252 Debian References: http://www.debian-administration.org/articles/285
 253
 254 Authors
 255   Johannes Schindelin <Johannes.Schindelin@gmx.de>
 256   Rutger Nijlunsing <git@wingding.demon.nl>