Project

General

Profile

HowTo configure Redmine for advanced git integration » History » Version 23

Mr. DTTH, 2013-08-08 05:23

1 1 Felix Schäfer
h1. HowTo configure Redmine for advanced git integration
2
3 3 Felix Schäfer
{{>TOC}}
4
5 1 Felix Schäfer
h2. Scope
6
7 21 Mr. DTTH
_Install on Centos 6.x_
8
9 17 Mr. DTTH
This HowTo explains how to serve git repositories on apache through the http-based "git-smart-http protocol":http://progit.org/2010/03/04/smart-http.html introduced in git 1.6.6. 
10 1 Felix Schäfer
11 17 Mr. DTTH
The git-smart-http offers various advantages over ssh or git-based access: you can use redmine access control as-is, no need for extra ssh keys or whatnot, you can secure it through SSL as needed, and there's generally less problems with firewalls and https/https ports than exist with ssh and git ports. git-smart-http also doesn't have some of the drawbacks of its "dumb" predecessor, as it doesn't require any complex DAV setup.
12 1 Felix Schäfer
13 17 Mr. DTTH
This HowTo is mainly written from memory and was conducted on a setup which was already serving [[Repositories_access_control_with_apache_mod_dav_svn_and_mod_perl|svn repositories integrated with redmine]], so it might be possible that I forgot some things or take them for granted. 
14
15
This is a wiki page, feel free to correct or amend anything you find lacking :-) You can also "drop me a line":/users/3866.
16
17 7 Felix Schäfer
Another option to integrate grack with redmine is the "modified grack+redmine plugin":http://github.com/friflaj/redmine_grack or "any other grack modified for redmine":http://github.com/search?q=grack&type=Everything&repo=&langOverride=&start_value=1, though those ones lack documentation and I haven't tried them, so I can't say much about those.
18 1 Felix Schäfer
19
h2. Prerequisites
20
21
* Apache with mod_perl (access control)
22
* git (version at least 1.6.6)
23
* A way to serve git-smart-http
24 10 Hallison Vasconcelos Batista
** mod_cgi (or mod_cgid) if you want to use the stock "git-http-backend":http://www.kernel.org/pub/software/scm/git/docs/git-http-backend.html
25 1 Felix Schäfer
** a rack server if you want to use "grack":http://github.com/schacon/grack (basically a rack wrapper around the right git commands) or
26 10 Hallison Vasconcelos Batista
"git-webby":http://git.io/BU7twg (another implementation based on grack but written in Sinatra).
27 1 Felix Schäfer
28 17 Mr. DTTH
You should already have a rack server to run redmine, and that's why I chose grack as the backend and which I will describe in this tutorial. 
29 1 Felix Schäfer
30 17 Mr. DTTH
Using the stock git-http-backend should be quite straightforward though (skip the [[HowTo_configure_Redmine_for_advanced_git_integration#Install-grack|grack installation]] part and get your install with the git-http-backend going (the "git-http-backend manpage":http://www.kernel.org/pub/software/scm/git/docs/git-http-backend.html has some examples), when that's done go on with the [[HowTo_configure_Redmine_for_advanced_git_integration#Access-control|access control]] part).
31
32 20 Mr. DTTH
h2. Install Git
33
34
<pre><code class="bash">
35
yum install git
36
</code></pre>
37
38 2 Felix Schäfer
h2. Install grack
39 1 Felix Schäfer
40 3 Felix Schäfer
h3. Get the sources
41 2 Felix Schäfer
42 19 Mr. DTTH
Fetch grack from its "github repository":http://github.com/schacon/grack, I checked out mine to @/var/www/grack@
43 1 Felix Schäfer
44 19 Mr. DTTH
<pre><code class="bash">
45
cd /var/www
46
git clone http://github.com/schacon/grack.git
47
</code></pre>
48 1 Felix Schäfer
49 18 Mr. DTTH
And create a directory for repositories :
50
51
<pre><code class="bash">
52 1 Felix Schäfer
mkdir /opt/repositories
53 21 Mr. DTTH
mkdir /opt/repositories/git
54 18 Mr. DTTH
chown -R apache:apache /opt/repositories/git
55
</code></pre>
56
57 2 Felix Schäfer
h3. Configuration
58
59
Edit the @config.ru@ file and adapt it to your local configuration. @project_root@ must contain the path to the directory containing your git repositories, @git_path@ must obviously contain the path to the git, mine looks like this (on gentoo):
60 1 Felix Schäfer
61 21 Mr. DTTH
<pre><code class="bash">
62
vi /var/www/grack/config.ru
63
</code></pre>
64
65
And edit file :
66
67 2 Felix Schäfer
<pre><code class="ruby">$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/lib')
68 1 Felix Schäfer
69 2 Felix Schäfer
use Rack::ShowExceptions
70 1 Felix Schäfer
71 18 Mr. DTTH
require 'grack'
72 1 Felix Schäfer
73 18 Mr. DTTH
require 'git_adapter'
74 2 Felix Schäfer
75 18 Mr. DTTH
config = {
76
  :project_root => "/opt/repositories/git",
77 2 Felix Schäfer
  :git_path => '/usr/bin/git',
78
  :upload_pack => true,
79 1 Felix Schäfer
  :receive_pack => true,
80
}
81
82 21 Mr. DTTH
run GitHttp::App.new(config)
83
</code></pre>
84 3 Felix Schäfer
85 1 Felix Schäfer
h3. Integrate with Apache
86
87 17 Mr. DTTH
You could obviously use any rack server you like at this point, but the access control mechanism @Redmine.pm@ is written for apache with mod_perl, so you will at least need to reverse proxy your rack server through apache. 
88 1 Felix Schäfer
89 17 Mr. DTTH
My rack server of choice is "passenger":http://modrails.com/ (solid performance, apache module, mostly simple configuration) and it is already configured on my system. 
90
91
As passenger installation and configuration is not within the scope of this HowTo, please refer to the "passenger documentation":http://modrails.com/documentation.html or to the passenger installation guide from your distribution.
92
93
There's a little more work to do here to get passenger to work with this, you will need to create the directories @public@ and @tmp@ in the grack directory. 
94 1 Felix Schäfer
95
Please also be aware that in the standard configuration, passenger will run the grack application with the same user and group owning the @config.ru@ file. This user must have read- and write-access as needed to the git repositories!
96
97 21 Mr. DTTH
Create directories 'public' and 'tmp' in /var/www/grack for apache :
98
99
<pre><code class="bash">
100
cd /var/www/grack
101
mkdir public
102
mkdir tmp
103
chown -R apache:apache /var/www/grack
104
</code></pre>
105
106
Edit config file "/etc/httpd/conf/httpd.conf" for support multi virtualhost by remove comment :
107
108
<pre><code class="bash">
109
NameVirtualHost *:80
110
</code></pre>
111
112
Create a file virtualhost :
113
114
<pre><code class="bash">
115
vi /etc/httpd/conf.d/git.conf
116
</code></pre>
117
118 22 Mr. DTTH
with text :
119 1 Felix Schäfer
120 22 Mr. DTTH
<pre><code class="apache">
121
<VirtualHost *:80>
122
    ServerName git.yourdomain.com
123
    DocumentRoot "/var/www/grack/public"
124
    <Directory "/var/www/grack/public">
125 1 Felix Schäfer
        Options None
126
        AllowOverride None
127 22 Mr. DTTH
        <IfVersion < 2.3 >
128 1 Felix Schäfer
        Order allow,deny
129
        Allow from all
130 22 Mr. DTTH
        </IfVersion>
131
        <IfVersion >= 2.3>
132
        Require all granted
133
        </IfVersion>
134
     </Directory>
135
 </VirtualHost>
136
</code></pre>
137 2 Felix Schäfer
138 22 Mr. DTTH
In controlpanel DNS record at domain name page, create a subdomain with name "git.yourdomain.com" and point to your IP server.
139 2 Felix Schäfer
140 22 Mr. DTTH
At this point, if you have a repository in "/opt/repositories/git/myrepo", you should be able to access it through "http://git.yourdomain.com/myrepo", for example :
141 2 Felix Schäfer
142 22 Mr. DTTH
Use a git client as Gitbash or TortoiseGit to clone repos :
143
144
<pre><code class="apache">
145
git clone http://git.yourdomain.com/myrepo
146
</code></pre>
147
148
If it successful, git on server and connection is very good!
149 3 Felix Schäfer
150
h2. Access control
151
152
You now have a working git server, albeit with no access control. Currently, the shipped perl module for access control @Redmine.pm@ (in @extra/svn/@ in your redmine directory) does not support access control for the git-smart-http protocol, the patch in #4905 aims to implement that.
153
154 11 Gregory Bartholomew
h3. Applying the patch
155 1 Felix Schäfer
156 23 Mr. DTTH
_If you are using Redmine >= 2.1.0, step over to Configuring Apache_
157
158 3 Felix Schäfer
Download the latest (or better: correct) version of the patch from #4905 to your redmine directory. In the redmine directory, apply the patch: @patch -p1 < the-patch-file.patch@ should work (if it tells you stuff about being unable to apply a hunk, the patch is incompatible with your @Redmine.pm@ version, if it says other stuff, try @patch -p0 < the-patch-file.patch@ or @patch Redmine.pm < the-patch-file.patch@, if it still borks, ask for advice on #4905).
159 1 Felix Schäfer
160
-You will possibly still need to edit the file from here, because the current version of the patch only works for repositories served from @http://git.myhost.com/git/myrepo@ though the above example uses @http://git.myhost.com/myrepo@.- This step isn't needed anymore, the patch has been updated to take the information from the @Location@ block from apache into account.
161 8 Felix Schäfer
162 3 Felix Schäfer
h3. Configuring Apache
163 17 Mr. DTTH
164 3 Felix Schäfer
You now have to make Apache aware of your new authentication module (if you already had done this step for subversion integration, you can go to the @Location@ directives directly). 
165 17 Mr. DTTH
166
Copy or link @Redmine.pm@ (from your @extra/svn/@ directory) to @/usr/lib/perl5/Apache/Redmine.pm@ (ubuntu) or wherever your distribution puts its apache perl modules (e.g. gentoo puts them in @/usr/lib64/perl5/vendor_perl/5.8.8/Apache/@, fedora puts them in @/usr/lib64/perl5/vendor_perl/Apache/@).
167 3 Felix Schäfer
168 1 Felix Schäfer
Having done that, reload apache to make sure everything in the patching phase went well (if not, remove the link or the file create in the step just before and restart apache to get apache back up, try to find the error in your Redmine.pm file). Now edit your vhost configuration to look somewhat like (same as above but with more stuff):
169
170 23 Mr. DTTH
<pre><code class="bash">
171
vi /etc/httpd/conf.d/git.conf
172
</code></pre>
173 1 Felix Schäfer
174 23 Mr. DTTH
with :
175 1 Felix Schäfer
176 23 Mr. DTTH
<pre><code class="bash">
177 1 Felix Schäfer
178 23 Mr. DTTH
<VirtualHost *:80>
179
180
    ServerName git.yourdomain.com
181
182
    DocumentRoot "/var/www/grack/public"
183
184
    <Directory "/var/www/grack/public">
185
186 1 Felix Schäfer
        Options None
187 23 Mr. DTTH
188 1 Felix Schäfer
        AllowOverride None
189 23 Mr. DTTH
190
        <IfVersion < 2.3 >
191
192 1 Felix Schäfer
        Order allow,deny
193 23 Mr. DTTH
194 1 Felix Schäfer
        Allow from all
195
196 23 Mr. DTTH
        </IfVersion>
197 1 Felix Schäfer
198 23 Mr. DTTH
        <IfVersion >= 2.3>
199 1 Felix Schäfer
200 23 Mr. DTTH
        Require all granted
201 1 Felix Schäfer
202 23 Mr. DTTH
        </IfVersion>
203 1 Felix Schäfer
204 23 Mr. DTTH
     </Directory>
205
206
     PerlLoadModule Apache::Redmine
207
    <Directory "/var/www/grack/public">
208
209
        Options None
210
211
        AllowOverride None
212
213
        <IfVersion < 2.3 >
214
215
        Order allow,deny
216
217
        Allow from all
218
219
        </IfVersion>
220
221
        <IfVersion >= 2.3>
222
223
        Require all granted
224
225
        </IfVersion>
226
227
     </Directory>
228
229
     
230
     <Location "/">
231
232
       AuthType Basic
233
234
       AuthName "Redmine git repositories"
235
236
       Require valid-user
237
238
       PerlAccessHandler Apache::Authn::Redmine::access_handler
239
       PerlAuthenHandler Apache::Authn::Redmine::authen_handler
240
   
241
       RedmineDSN "DBI:mysql:database=your_database;host=localhost:3306"
242
243
       RedmineDbUser "user_database"
244
       RedmineDbPass "password_database"       
245
       RedmineGitSmartHttp yes
246
     </Location>
247
248
 </VirtualHost>
249
</code></pre>
250
251
Restart your apache, and everything should be good and well :-)
252 13 Gregory Bartholomew
253
h2. Known issues
254
255
If you are using the stock git-http-backend directly under apache and you are finding errors like "Request not supported: '/git/your-git-repo'" in your apache error log, you may need to add "SetEnv REMOTE_USER=$REDIRECT_REMOTE_USER" to the to the list of environment variables that you are setting in your apache configuration.  
256
257
Unfortionately, this setting may cause redmine to borke.  If so, you will need to set the variable for only the requests that are passed through git-http-backend.  One way to accomplish this is with mod_rewrite.  Below is a sample apache configuration from a Fedora 17 system that uses git-http-backend and mod_rewrite.
258
259
In httpd.conf:
260
261
<pre><code class="apache">Listen xxx.xxx.xxx.xxx:80
262
<VirtualHost xxx.xxx.xxx.xxx:80>
263
   DocumentRoot /var/www/redmine/public
264
   ServerName servername.domain:80
265
   Include conf/servername.conf
266
</VirtualHost>
267
268
Listen xxx.xxx.xxx.xxx:443
269
<VirtualHost xxx.xxx.xxx.xxx:443>
270
   DocumentRoot /var/www/redmine/public
271
   ServerName servername.domain:443
272
   Include conf/servername.conf
273
   Include conf/ssl.conf
274
</VirtualHost></code></pre>
275
276
In servername.conf:
277
278
<pre><code class="apache">PerlLoadModule Apache::Authn::Redmine
279
280
SetEnv GIT_PROJECT_ROOT /git-1/repositories
281
SetEnv GIT_HTTP_EXPORT_ALL
282
283
<IfModule mod_rewrite.c>
284
   RewriteEngine On
285 15 Gregory Bartholomew
286
   RewriteCond %{HTTPS} ^off$
287
   RewriteCond %{REQUEST_URI} !^/git-private/
288 13 Gregory Bartholomew
   RewriteRule ^.*$ https://servername.domain$0 [R=301,L]
289
   RewriteRule ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /git-1/repositories/$1 [L]
290
   RewriteRule ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /git-1/repositories/$1 [L]
291
   RewriteRule ^/git/(.*)$ /usr/libexec/git-core/git-http-backend/$1 [E=REMOTE_USER:$REDIRECT_REMOTE_USER,H=cgi-script,L]
292
</IfModule>
293
294
<Directory /usr/libexec/git-core>
295
   <Files "git-http-backend">
296
      Options +ExecCGI
297
   </Files>
298
</Directory>
299
300
<Location /git>
301
   AuthType Basic
302 14 Gregory Bartholomew
   AuthName "CAMPUS"
303 13 Gregory Bartholomew
   AuthBasicProvider external
304
   AuthExternal pwauth
305
   Require valid-user
306
307
   PerlAccessHandler Apache::Authn::Redmine::access_handler
308
   PerlAuthenHandler Apache::Authn::Redmine::authen_handler
309
 
310
   RedmineDSN "DBI:mysql:database=redmine;host=localhost" 
311
   RedmineDbUser "redmine" 
312
   # RedmineDbPass "password"
313
   RedmineGitSmartHttp yes
314
</Location>
315
316
Alias /git-private /git-1/repositories
317
318
<Location /git-private>
319
   Order deny,allow
320
   Deny from all
321
   <Limit GET PROPFIND OPTIONS REPORT>
322
      Options Indexes FollowSymLinks MultiViews
323
      Allow from 127.0.0.1
324
      Allow from localhost
325
   </Limit>
326
</Location>
327
328
<Directory "/var/www/redmine/public">
329
   RailsEnv production
330
   RailsBaseURI /
331
332
   Options -MultiViews
333
   AllowOverride All
334
</Directory></code></pre>
335
336
In conf/ssl.conf:
337
338
<pre><code class="apache">LogLevel warn
339
SSLEngine on
340
SSLProtocol all -SSLv2
341
SSLCipherSuite RC4-SHA:AES128-SHA:ALL:!ADH:!EXP:!LOW:!MD5:!SSLV2:!NULL
342
SSLCertificateFile /etc/pki/tls/certs/your-server.crt
343
SSLCertificateKeyFile /etc/pki/tls/private/your-server.key
344
SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt
345
SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
346
347
<Files ~ "\.(cgi|shtml|phtml|php3?)$">
348
    SSLOptions +StdEnvVars
349
</Files>
350
<Directory "/var/www/cgi-bin">
351
    SSLOptions +StdEnvVars
352
</Directory>
353 1 Felix Schäfer
354
SetEnvIf User-Agent ".*MSIE.*" \
355
         nokeepalive ssl-unclean-shutdown \
356 13 Gregory Bartholomew
         downgrade-1.0 force-response-1.0
357
</code></pre>
358
359
In conf.d/ssl.conf:
360
361 17 Mr. DTTH
<pre><code class="apache">LoadModule ssl_module modules/mod_ssl.so
362
SSLPassPhraseDialog exec:/usr/libexec/httpd-ssl-pass-dialog
363
SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
364 13 Gregory Bartholomew
SSLSessionCacheTimeout  300
365 15 Gregory Bartholomew
SSLMutex default
366 13 Gregory Bartholomew
SSLRandomSeed startup file:/dev/urandom  256
367
SSLRandomSeed connect builtin
368 1 Felix Schäfer
SSLCryptoDevice builtin
369
</code></pre>
370
371
You will also need to have the perl modules Net::LDAP, Authen::Simple, and Authen::Simple::LDAP installed.  The first two are available in Fedora's default package repositories.  
372
373
The third must be installed after the other two and it must be obtained directly from cpan.  Below are the commands that I used to install these packages on Fedora 17.
374
375
yum -y install gcc make perl-LDAP perl-Authen-Simple
376
cpan
377
cpan> install Authen::Simple::LDAP