git stash: show status relative to current directory
[git.git] / Documentation / howto / setup-git-server-over-http.txt
blob622ee5c8dd7c384794a21baa6093d85a47f89a54
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
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.
12 What's needed:
14 - Have an Apache web-server
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
21 - can edit the configuration of it.
23   This could be found under /etc/httpd, or refer to your Apache documentation.
25   On Debian: this means being able to edit files under /etc/apache2
27 - can restart it.
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.
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.
41 - have permissions to chown a directory
43 - have git installed on the client, and
45 - either have git installed on the server or have a webdav client on
46   the client.
48 In effect, this means you're going to be root, or that you're using a
49 preconfigured WebDAV server.
52 Step 1: setup a bare GIT repository
53 -----------------------------------
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).
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:
65     $ cd /usr/local/apache/htdocs
66     $ mkdir my-new-repo.git
68   On Debian:
70     $ cd /var/www
71     $ mkdir my-new-repo.git
74 Initialize a bare repository
76     $ cd my-new-repo.git
77     $ git --bare init
80 Change the ownership to your web-server's credentials. Use "grep ^User
81 httpd.conf" and "grep ^Group httpd.conf" to find out:
83     $ chown -R www.www .
85   On Debian:
87     $ chown -R www-data.www-data .
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.
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.
99 Step 2: enable DAV on this repository
100 -------------------------------------
102 First make sure the dav_module is loaded. For this, insert in httpd.conf:
104     LoadModule dav_module libexec/httpd/libdav.so
105     AddModule mod_dav.c
107 Also make sure that this line exists which is the file used for
108 locking DAV operations:
110   DAVLockDB "/usr/local/apache2/temp/DAV.lock"
112   On Debian these steps can be performed with:
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
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.
125 Then, add something like this to your httpd.conf
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>
135   On Debian:
136     Create (or add to) /etc/apache2/conf.d/git.conf :
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>
146     Debian automatically reads all files under /etc/apache2/conf.d.
148 The password file can be somewhere else, but it has to be readable by
149 Apache and preferably not readable by the world.
151 Create this file by
152     $ htpasswd -c /usr/local/apache2/conf/passwd.git <user>
154     On Debian:
155       $ htpasswd -c /etc/apache2/passwd.git <user>
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.
161 You need to restart Apache.
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.
167 On Debian:
169    To test the WebDAV part, do:
171    $ apt-get install litmus
172    $ litmus http://<servername>/my-new-repo.git <username> <password>
174    Most tests should pass.
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://...".
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 .
185 Step 3: setup the client
186 ------------------------
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.
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):
195     machine <servername>
196     login <username>
197     password <password>
199 ...and set permissions:
200      chmod 600 ~/.netrc
202 If you want to access the web-server by its IP, you have to type that in,
203 instead of the server name.
205 To check whether all is OK, do:
207    curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD
209 ...this should give something like 'ref: refs/heads/master', which is
210 the content of the file HEAD on the server.
212 Now, add the remote in your existing repository which contains the project
213 you want to export:
215    $ git-config remote.upload.url \
216        http://<username>@<servername>/my-new-repo.git/
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.
223 Step 4: make the initial push
224 -----------------------------
226 From your client repository, do
228    $ git push upload master
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.
235 Using a proxy:
236 --------------
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.
244 Troubleshooting:
245 ----------------
247 If git-http-push says
249    Error: no DAV locking support on remote repo http://...
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.
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.
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.
263 Reading /usr/local/apache2/logs/error_log is often helpful.
265   On Debian: Read /var/log/apache2/error.log instead.
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.
272 Debian References: http://www.debian-administration.org/articles/285
274 Authors
275   Johannes Schindelin <Johannes.Schindelin@gmx.de>
276   Rutger Nijlunsing <git@wingding.demon.nl>
277   Matthieu Moy <Matthieu.Moy@imag.fr>