Merge branch 'lt/case-insensitive'
[git/git.git] / 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
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 on the client, and
44
45 - either have git installed on the server or have a webdav client on
46 the client.
47
48 In effect, this means you're going to be root, or that you're using a
49 preconfigured WebDAV server.
50
51
52 Step 1: setup a bare GIT repository
53 -----------------------------------
54
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).
60
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:
64
65 $ cd /usr/local/apache/htdocs
66 $ mkdir my-new-repo.git
67
68 On Debian:
69
70 $ cd /var/www
71 $ mkdir my-new-repo.git
72
73
74 Initialize a bare repository
75
76 $ cd my-new-repo.git
77 $ git --bare init
78
79
80 Change the ownership to your web-server's credentials. Use "grep ^User
81 httpd.conf" and "grep ^Group httpd.conf" to find out:
82
83 $ chown -R www.www .
84
85 On Debian:
86
87 $ chown -R www-data.www-data .
88
89
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.
93
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.
97
98
99 Step 2: enable DAV on this repository
100 -------------------------------------
101
102 First make sure the dav_module is loaded. For this, insert in httpd.conf:
103
104 LoadModule dav_module libexec/httpd/libdav.so
105 AddModule mod_dav.c
106
107 Also make sure that this line exists which is the file used for
108 locking DAV operations:
109
110 DAVLockDB "/usr/local/apache2/temp/DAV.lock"
111
112 On Debian these steps can be performed with:
113
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
120
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.
124
125 Then, add something like this to your httpd.conf
126
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>
134
135 On Debian:
136 Create (or add to) /etc/apache2/conf.d/git.conf :
137
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>
145
146 Debian automatically reads all files under /etc/apach2/conf.d.
147
148 The password file can be somewhere else, but it has to be readable by
149 Apache and preferably not readable by the world.
150
151 Create this file by
152 $ htpasswd -c /usr/local/apache2/conf/passwd.git <user>
153
154 On Debian:
155 $ htpasswd -c /etc/apache2/passwd.git <user>
156
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.
160
161 You need to restart Apache.
162
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.
166
167 On Debian:
168
169 To test the WebDAV part, do:
170
171 $ apt-get install litmus
172 $ litmus http://<servername>/my-new-repo.git <username> <password>
173
174 Most tests should pass.
175
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://...".
179
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 .
183
184
185 Step 3: setup the client
186 ------------------------
187
188 Make sure that you have HTTP support, i.e. your git was built with
189 curl (version more recent than 7.10). The command 'git http-push' with
190 no argument should display a usage message.
191
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):
194
195 machine <servername>
196 login <username>
197 password <password>
198
199 ...and set permissions:
200 chmod 600 ~/.netrc
201
202 If you want to access the web-server by its IP, you have to type that in,
203 instead of the server name.
204
205 To check whether all is OK, do:
206
207 curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD
208
209 ...this should give something like 'ref: refs/heads/master', which is
210 the content of the file HEAD on the server.
211
212 Now, add the remote in your existing repository which contains the project
213 you want to export:
214
215 $ git-config remote.upload.url \
216 http://<username>@<servername>/my-new-repo.git/
217
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.
221
222
223 Step 4: make the initial push
224 -----------------------------
225
226 From your client repository, do
227
228 $ git push upload master
229
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.
233
234
235 Using a proxy:
236 --------------
237
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.
242
243
244 Troubleshooting:
245 ----------------
246
247 If git-http-push says
248
249 Error: no DAV locking support on remote repo http://...
250
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.
254
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.
259
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.
262
263 Reading /usr/local/apache2/logs/error_log is often helpful.
264
265 On Debian: Read /var/log/apache2/error.log instead.
266
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.
270
271
272 Debian References: http://www.debian-administration.org/articles/285
273
274 Authors
275 Johannes Schindelin <Johannes.Schindelin@gmx.de>
276 Rutger Nijlunsing <git@wingding.demon.nl>
277 Matthieu Moy <Matthieu.Moy@imag.fr>