perf/run: read GIT_PERF_REPO_NAME from perf.repoName
[git.git] / Documentation / howto / setup-git-server-over-http.txt
blobf44e5e9458592a0554e4e2e163a6b029c1435f80
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
6 How to setup Git server over http
7 =================================
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].
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.
20 What's needed:
22 - Have an Apache web-server
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
29 - can edit the configuration of it.
31   This could be found under /etc/httpd, or refer to your Apache documentation.
33   On Debian: this means being able to edit files under /etc/apache2
35 - can restart it.
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.
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.
49 - have permissions to chown a directory
51 - have Git installed on the client, and
53 - either have Git installed on the server or have a webdav client on
54   the client.
56 In effect, this means you're going to be root, or that you're using a
57 preconfigured WebDAV server.
60 Step 1: setup a bare Git repository
61 -----------------------------------
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).
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:
73     $ cd /usr/local/apache/htdocs
74     $ mkdir my-new-repo.git
76   On Debian:
78     $ cd /var/www
79     $ mkdir my-new-repo.git
82 Initialize a bare repository
84     $ cd my-new-repo.git
85     $ git --bare init
88 Change the ownership to your web-server's credentials. Use `"grep ^User
89 httpd.conf"` and `"grep ^Group httpd.conf"` to find out:
91     $ chown -R www.www .
93   On Debian:
95     $ chown -R www-data.www-data .
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.
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.
107 Step 2: enable DAV on this repository
108 -------------------------------------
110 First make sure the dav_module is loaded. For this, insert in httpd.conf:
112     LoadModule dav_module libexec/httpd/libdav.so
113     AddModule mod_dav.c
115 Also make sure that this line exists which is the file used for
116 locking DAV operations:
118   DAVLockDB "/usr/local/apache2/temp/DAV.lock"
120   On Debian these steps can be performed with:
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
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.
133 Then, add something like this to your httpd.conf
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>
143   On Debian:
144     Create (or add to) /etc/apache2/conf.d/git.conf :
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>
154     Debian automatically reads all files under /etc/apache2/conf.d.
156 The password file can be somewhere else, but it has to be readable by
157 Apache and preferably not readable by the world.
159 Create this file by
160     $ htpasswd -c /usr/local/apache2/conf/passwd.git <user>
162     On Debian:
163       $ htpasswd -c /etc/apache2/passwd.git <user>
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.
169 You need to restart Apache.
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.
175 On Debian:
177    To test the WebDAV part, do:
179    $ apt-get install litmus
180    $ litmus http://<servername>/my-new-repo.git <username> <password>
182    Most tests should pass.
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://...".
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 .
193 Step 3: setup the client
194 ------------------------
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.
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):
203     machine <servername>
204     login <username>
205     password <password>
207 ...and set permissions:
208      chmod 600 ~/.netrc
210 If you want to access the web-server by its IP, you have to type that in,
211 instead of the server name.
213 To check whether all is OK, do:
215    curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD
217 ...this should give something like 'ref: refs/heads/master', which is
218 the content of the file HEAD on the server.
220 Now, add the remote in your existing repository which contains the project
221 you want to export:
223    $ git-config remote.upload.url \
224        http://<username>@<servername>/my-new-repo.git/
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.
231 Step 4: make the initial push
232 -----------------------------
234 From your client repository, do
236    $ git push upload master
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.
243 Using a proxy:
244 --------------
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.
252 Troubleshooting:
253 ----------------
255 If git-http-push says
257    Error: no DAV locking support on remote repo http://...
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.
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.
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.
271 Reading /usr/local/apache2/logs/error_log is often helpful.
273   On Debian: Read /var/log/apache2/error.log instead.
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.
280 Debian References: http://www.debian-administration.org/articles/285
282 Authors
283   Johannes Schindelin <Johannes.Schindelin@gmx.de>
284   Rutger Nijlunsing <git@wingding.demon.nl>
285   Matthieu Moy <Matthieu.Moy@imag.fr>