| 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> |